Create and Register a Custom Control in the Report Designer Toolbox (ASP.NET Core)

• Apr 30, 2024
• 4 minutes to read

This topic explains how to create a custom report control inherited from the XRLabel control and register the control in the End-User Report Designer Toolbox in the ASP.NET Core Reporting application.

View Example: Reporting for ASP.NET Core - Create a Custom Report Control

To get started with this tutorial, create a new application as described in the following help topic: Use DevExpress Visual Studio Templates to Create an ASP.NET Core Reporting App with a Report Designer.

Create a Custom Control Class

Add a new class that inherits from the XRLabel class and declare its properties with relevant attributes. Override the PutStateToBrick method to specify how to display a control in the preview. In this example, a value is assigned to the VisualBrick.Text property:

NumericLabel.cs

using DevExpress.Utils.Serializing;
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
using System.ComponentModel;

public class NumericLabel : XRLabel
{
    [Browsable(true), Bindable(false), Category("Data")]
    [XtraSerializableProperty]
    [DefaultValue("")]
    [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible),
    EditorBrowsable(EditorBrowsableState.Always)]
    public int Number { get; set; }

    // Render the control in the Designer's Preview and in the document.
    protected override void PutStateToBrick(VisualBrick brick, PrintingSystemBase ps)
    {
        base.PutStateToBrick(brick, ps);
        brick.Text = this.Number.ToString();
    }
}

MyControl.cs

using DevExpress.Utils.Serializing;
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.Localization;
using DevExpress.XtraReports;
using DevExpress.XtraReports.UI;
using System.ComponentModel;
using System.Drawing;

public enum MyEnum { One, Two, Three }

public class MyControl : XRLabel {
    public static readonly SizeF InitSizeF = new SizeF(200, 50);

    [XtraSerializableProperty,
    DefaultValue(true),
    Favorite(true),
    SRCategory(ReportStringId.CatBehavior)]
    public bool BoolProp { get; set; }

    [XtraSerializableProperty,
    DefaultValue(MyEnum.One)]
    public MyEnum EnumProp { get; set; }

    [XtraSerializableProperty]
    public Item[] ArrayProp { get; set; }

    protected override void PutStateToBrick(VisualBrick brick, PrintingSystemBase ps) {
        base.PutStateToBrick(brick, ps);
        brick.Text = EnumProp.ToString();
    }

    public class Item {
        [XtraSerializableProperty]
        public int PropA { get; set; }
    }
}

Limitations

• The Visual Studio Report Designer does not display a custom control in the Toolbox by default. To show a custom control in the Toolbox, add the ToolboxItem attribute and set it to true. Then, rebuild the project.

• Reporting for Web does not support custom XRTableRow and XRTableCell control implementations in a custom XRTable control.

Register a Custom Control in the Web End-User Report Designer

To add a custom control to the Report Designer toolbox, register custom control type using Report Designer fluent API with the IReportDesignerModelBuilder.CustomControls(Type[]) method.

The question mark is the default icon for a custom control. To define your own icon, add a style template with a name that is based on the name of the custom control’s class and uses the following pattern:

.dxrd-image-<namespace in lowercase>_<class name in lowercase>

The following code snippet registers the MyControl and NumericLabel custom control types using the IReportDesignerModelBuilder.CustomControls(Type[]) method:

HomeController.cs

using Microsoft.AspNetCore.Mvc;
using DevExpress.XtraReports.Web.ReportDesigner;
using DevExpress.XtraReports.Web.ReportDesigner.Services;

namespace Reporting_AspNetCore_Create_Custom_Control.Controllers {
    public class HomeController : Controller {
        public IActionResult Index([FromServices] IReportDesignerModelBuilder reportDesignerModelBuilder) {
            ReportDesignerModel model = reportDesignerModelBuilder
                .Report("TestReport")
                .CustomControls(typeof(MyControl), typeof(NumericLabel))
                .BuildModel();
            return View(model);
        }
    }
}

The following code snippet specifies an SVG icon for the NumericLabel control:

Index.cshtml

@model DevExpress.XtraReports.Web.ReportDesigner.ReportDesignerModel

<script type="text/html" id="dxrd-svg-toolbox-numericlabel">
        <svg viewBox="-2 -4 32 32" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <g id="Layer_1" transform="translate(-2, -4)" style="enable-background:new 0 0 32 32">
        <g id="Window">
          <path d="M30, 10L30, 5C30, 4.5 29.5, 4 29, 4L3, 4C2.5, 4 2, 4.5 2, 5L2, 10L30, 10z" fill="#1177D7" class="Blue" />
        </g>
      </g>
      <g id="Layer_1" transform="translate(-2, -4.00000095367432)" style="enable-background:new 0 0 32 32">
        <g id="Window">
          <path d="M28, 10L28, 26L4, 26L4, 10L2, 10L2, 27C2, 27.5 2.5, 28 3, 28L29, 28C29.5, 28 30, 27.5 30, 27L30, 10L28, 10z" fill="#727272" class="Black" />
        </g>
      </g>
    </svg>
</script>

@{
    var designerRender = Html.DevExpress().ReportDesigner("reportDesigner")
        .Height("1000px")
        .Bind(Model);
    @designerRender.RenderHtml();
}


@section Scripts {
    <link href="~/css/dx-reporting-skeleton-screen.css" rel="stylesheet" />
    <link rel="stylesheet" href="~/css/viewer.part.bundle.css" />
    <link rel="stylesheet" href="~/css/designer.part.bundle.css" />
    <link rel="stylesheet" href="~/css/ace/ace.bundle.css" />

    <script src="~/js/reporting.thirdparty.bundle.js"></script>
    <script src="~/js/viewer.part.bundle.js"></script>
    <script src="~/js/designer.part.bundle.js"></script>

    @designerRender.RenderScripts()
}

Remove an Existing Control from the Toolbox

You can use the CustomizeToolbox event to remove an existing control from the Toolbox. Call the getControlInfo method of the event argument’s ASPxClientReportDesignerCustomizeToolboxEventArgs.ControlsFactory property to obtain the specified control and set the IElementMetadata.isToolboxItem property to false:

JS

function onCustomizeToolbox(s, e) {
    // Hide the XRLabel control in the Toolbox.
    var info = e.ControlsFactory.getControlInfo("XRLabel");
    info.isToolboxItem = false;
}