Migrate from Web Viewer to Web Dashboard in ASP.NET Web Forms

  • 6 minutes to read

The Web Dashboard Control replaced the old Web Dashboard Viewer, and the Web Viewer is not included in our installation packages.

The Web Dashboard Viewer was introduced in 2012 to display dashboards in web applications. However, you cannot design dashboards in this control. To create a dashboard, you need to use the WinForms Dashboard Designer or the Visual Studio Dashboard Designer.

The Web Dashboard Control allows you to create and display dashboards in the same application. In addition to the designer feature set, the Web Dashboard Control is more scalable and uses cache and memory more efficiently because of its RESTful architecture.

You should make the following changes when you migrate to the Web Dashboard in ASP.NET Web Forms:

Embed Client Libraries

The Web Dashboard control requires the following client-side libraries in addition to Web Viewer scripts:

If you use the “Resources” section in the application’s Web.config file, all the scripts are added automatically.

If the Web.config file has no “Resource” section, attach the jQuery UI, Knockout, and Ace libraries to the web page in addition to the scripts the Web Viewer uses.

The Web Dashboard also requires the jQuery 3.3.1+ script. Make sure that you use the up-to-date jQuery version.

Provide Dashboards

Below are several examples that show how to provide dashboards for a new control when migrating from the Web Viewer:

Example 1. Load a dashboard XML file.

Change the ASPxDashboardViewer.DashboardSource property to ASPxDashboard.DashboardXmlPath:





Example 2. Load a dashboard created at design time.

Change the ASPxDashboardViewer.DashboardSource property to ASPxDashboard.DashboardType:





Example 3. Load a dashboard at runtime.

The ASPxDashboard.DashboardLoading event replaces ASPxDashboardViewer.DashboardLoading. The new control accepts the dashboard definition in the XDocument format instead of String.


protected void Page_Load(object sender, EventArgs e) {
    ASPxDashboardViewer1.DashboardId = "File1";

protected void ASPxDashboardViewer1_DashboardLoading(object sender, 
                DevExpress.DashboardWeb.DashboardLoadingEventArgs e) {
    if(e.DashboardId == "File1") {
        string definitionPath = Server.MapPath("~/File1.xml");
        string dashboardDefinition = File.ReadAllText(definitionPath);
        e.DashboardXml = dashboardDefinition;


protected void Page_Load(object sender, EventArgs e) {
    ASPxDashboard1.InitialDashboardId = "File1";

protected void ASPxDashboard1_DashboardLoading(object sender, 
                DevExpress.DashboardWeb.DashboardLoadingWebEventArgs e) {
    if(e.DashboardId == "File1") {
        string definitionPath = Server.MapPath("~/File1.xml");
        e.DashboardXml = XDocument.Load(definitionPath);

Example 4. Load dashboards from the dashboard storage.

Create a storage and register a dashboard in it to provide dashboards. The code below demonstrates how to create the default file storage and register a dashboard:

protected void Page_Load(object sender, EventArgs e) {
      DashboardFileStorage dashboardFileStorage = new DashboardFileStorage(System.Web.Hosting.HostingEnvironment.MapPath(@"~/App_Data/Dashboards"));

Provide Data

The Web Dashboard control provides the following equivalents for events used in the Web Viewer:

Web Dashboard Viewer

Web Dashboard Control




Allows you to customize connection settings before Dashboard connects to a data store (a database, OLAP cube, etc.).



Allows you to include WHERE clauses in SQL queries.



Provides data for a data source assigned in code.

Reload Data

In the Web Viewer, you used the ASPxClientDashboardViewer.ReloadData method to reload data in all dashboard data sources. For the Web Dashboard, we change the model of data usage, and data is reloaded automatically. You can handle the ASPxDashboard.ConfigureDataReloadingTimeout event to set the data reloading timeout in the Web Dashboard. To refresh data manually, call the ASPxClientDashboard.ReloadData method.


The Web Dashboard has the following specifics related to security:


The Web Dashboard control supports the same set of themes as ASPxDashboardViewer:

  • ASPxDashboard.ColorSchemeLight
  • ASPxDashboard.ColorSchemeLightCompact
  • ASPxDashboard.ColorSchemeDark
  • ASPxDashboard.ColorSchemeDarkCompact

Client-Side API

The Web Dashboard control uses a similar client-side API (for exporting, coloring, requesting parameter values, etc.) as the Web Viewer except for the following differences:


Cannot find the DashboardLoaded event in the Web Dashboard.

In the ASPxDashboard control, handle the ASPxDashboard.DashboardLoading event to customize the loaded dashboard on the server side.

For instance, see the code below:

protected void ASPxDashboard1_DashboardLoading(object sender, 
            DevExpress.DashboardWeb.DashboardLoadingWebEventArgs e) {
  if (e.DashboardId == "Dashboard1") { 
    Dashboard dashboard = new Dashboard();
    //Customize Dashboard
    e.DashboardXml = dashboard.SaveToXDocument();

To see this approach in action, refer to the How to customize a dashboard before displaying it in a browser code example.

Dashboard is not loaded.

A dashboard may not be loaded due to security reasons. The Web Dashboard control automatically checks whether a dashboard contains data connection parameters. In this case, the dashboard is not loaded. To learn how to protect parameters used to establish a connection to data when the Web Dashboard is used, refer to the T453795 ticket.

Cannot find the FilterElementDefaultValues event in the Web Dashboard.

The Web Dashboard control provides the ASPxDashboard.SetInitialDashboardState event that allows you to specify the values of parameters, filter elements, and other state parameters. To learn more about the dashboard state, see Manage Dashboard State.

Cannot switch a new control to Viewer mode.

Refer to the Designer and Viewer Modes topic for details on how to switch over modes.

See Also