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.
Tip
Topic: Required Client Libraries
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:
Old:
ASPxDashboardViewer1.DashboardSource="~/File1.xml";
New:
ASPxDashboard1.DashboardXmlPath="~/File1.xml";
Example 2. Load a dashboard created at design time.
Change the ASPxDashboardViewer.DashboardSource property to ASPxDashboard.DashboardType:
Old:
ASPxDashboardViewer1.DashboardSource="typeof(Dashboard1)";
New:
ASPxDashboard1.DashboardType="typeof(Dashboard1)";
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.
Old:
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;
}
}
New:
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"));
ASPxDashboard1.SetDashboardStorage(dashboardFileStorage);
}
Tip
Topic: Prepare a Dashboard Storage
Provide Data
The Web Dashboard control provides the following equivalents for events used in the Web Viewer:
Web Dashboard Viewer | Web Dashboard Control | Description |
|---|---|---|
ASPxDashboardViewer.ConfigureDataConnection | Allows you to customize connection settings before Dashboard connects to a data store (a database, OLAP cube, etc.). | |
ASPxDashboardViewer.CustomFilterExpression | Allows you to include WHERE clauses in SQL queries. | |
ASPxDashboardViewer.DataLoading | 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.
Tip
KB article: T520250: Web Dashboard - How to manage an in-memory data cache when the Client data processing is used
Security
The Web Dashboard has the following specifics related to security:
- Web Dashboard does not load dashboards with custom SQL queries by default. Refer to the Custom SQL Queries article for details.
- For security reasons, the Web Dashboard control checks whether a dashboard contains data connection parameters. In this case, the dashboard is not loaded. Refer to the T453795 - How to protect parameters used to establish a connection to data when the Web/MVC Dashboard is used ticket to learn how to protect parameters used to establish a connection to data when the Web Dashboard is used.
Tip
Topic: Security Considerations
Appearance
The Web Dashboard control supports the same set of themes as ASPxDashboardViewer:
- ASPxDashboard.ColorSchemeLight
- ASPxDashboard.ColorSchemeLightCompact
- ASPxDashboard.ColorSchemeDark
- ASPxDashboard.ColorSchemeDarkCompact
Tip
Topic: Appearance Customization
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:
-
1) When filtering is applied, or the state of the master filter item changes, the ASPxClientDashboard.ItemMasterFilterStateChanged event is raised instead of ASPxClientDashboardViewer.MasterFilterSet.
2) When an end user clears selection in the master filter item, the ASPxClientDashboard.ItemMasterFilterStateChanged event is raised again instead of ASPxClientDashboardViewer.MasterFilterCleared.
-
1) After drill-down (or drill-up) is performed, the ASPxClientDashboard.ItemDrillDownStateChanged event is raised instead of ASPxClientDashboardViewer.DrillDownPerformed (or ASPxClientDashboardViewer.DrillUpPerformed).
FAQ
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();
dashboard.LoadFromXDocument(e.DashboardXml);
//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 the viewer mode.
Refer to the Designer and Viewer Modes topic for details on how to switch over modes.