How to: Add a Dashboard Extension to an XAF ASP.NET Core Blazor Application

• Jul 09, 2025
• 2 minutes to read

You can use extensions to customize the dashboard control used by the Dashboards Module. This topic integrates a simple example extension into your XAF ASP.NET Core Blazor application.

Step-by-Step Instructions

1. Copy the following dashboard extension files to the YourApplicationName.Blazor.Server\wwwroot folder:

   • BlazorDashboardApp\wwwroot\parameter-item.js. This file contains the definition of the ParameterCustomItem extension. You will create a Controller that loads this script in the last step.

     window.ParameterCustomItem = /*...*/;
     

   • BlazorDashboardApp\wwwroot\dashboard-events-scripts.js. This file contains the code that registers the extension in the dashboard control and adds custom toolbar buttons to Grid item captions:

     window.dashboardEvents = {
         onBeforeRender: (args) => {
             // Registers the Parameter item and the Dashboard Panel.
             var dashboardControl = args.component;
             dashboardControl.registerExtension(new ParameterCustomItem(dashboardControl));
             // ...
         },
         // Adds a new custom toolbar item to the dashboard item caption.
         extensions: {
             viewerApi: {
                 onItemCaptionToolbarUpdated: function (e) {
                     // ...
                 }
             }
         }    
     }
     

2. Create a new JavaScript file in the YourApplicationName.Blazor.Server\wwwroot folder and name it xaf-dashboard-user-script.js. Copy the following code snippet to the file:

   const xafDashboardUserScript = {
       onBeforeRender: function (dashboardControl) {
           window.dashboardEvents.onBeforeRender({ component: dashboardControl });
           const viewerApi = dashboardControl.findExtension("viewerApi");
           viewerApi.on("itemCaptionToolbarUpdated",
               window.dashboardEvents.extensions.viewerApi.onItemCaptionToolbarUpdated);
       }
   };
   
   window.xafBlazorDashboardUserScripts = [xafDashboardUserScript];
   

   xafDashboardUserScript is a plain JavaScript object that contains a single onBeforeRender method. XAF calls this method before it renders a dashboard, because xafDashboardUserScript is included in the xafBlazorDashboardUserScripts array. The onBeforeRender method does the following:

   • Calls the window.dashboardEvents.onBeforeRender method (defined in the dashboard-events-scripts.js file) that registers a custom toolbar item.
   • Ensures that the onItemCaptionToolbarUpdated method is called. XAF does not support extensions: { viewerApi: { ... } } syntax, therefore you must subscribe to the ViewerApiExtension‘s itemCaptionToolbarUpdated event explicitly.

3. To add custom scripts and the extension’s icons to the application, navigate to the YourApplicationName.Blazor.Server\Pages\_Host.cshtml file and add the following links to it: dashboard-events-scripts.js and xaf-dashboard-user-script.js.

   <link href="_content/DevExpress.ExpressApp.Blazor/styles.css" asp-append-version="true" rel="stylesheet" />
   <link href="css/site.css" rel="stylesheet" />
   <script src="dashboard-events-scripts.js"></script>
   <script src="xaf-dashboard-user-script.js"></script>
   

4. Navigate to YourApplicationName.Blazor.Server\App.razor and add the following line at the top of the file:

   @DxResourceManager.RegisterScripts((config) => config.Register(new DxResource("/parameter-item.js", 900)))
   

   This ensures that the parameter-item.js script is loaded in the correct order (after all other required scripts have been loaded).

The Parameter custom item is now available in the Dashboard Designer, and you can see a custom toolbar item in the first Grid dashboard item.