Migrate from Web Viewer to Web Dashboard in ASP.NET MVC
- 7 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 MVC:
Attach JavaScript Libraries
The MVC Dashboard control requires additional client-side libraries and MVC Viewer scripts:
If you added the “Resources” section to the application’s Web.config file to include libraries for the Web Viewer, 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 MVC Viewer uses.
The MVC 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.
To attach the Dashboard Javascript file, change the ExtensionsFactory.GetScripts) method’s parameters: use the ExtensionSuite.Dashboard value instead of ExtensionSuite.DashboardViewer.
Old:
<head>
...
@Html.DevExpress().GetScripts(
// ...
new Script { ExtensionSuite = ExtensionSuite.DashboardViewer }
)
...
</head>
New:
<head>
...
@Html.DevExpress().GetScripts(
// ...
new Script { ExtensionSuite = ExtensionSuite.Dashboard }
)
...
</head>
Tip
Topic: Attach the JavaScript Files
Attach the Style Sheets
You need to attach the style sheets for the Dashboard Extension. For this, change the ExtensionsFactory.GetStyleSheets extension method’s parameter from ExtensionSuite.DashboardViewer to the ExtensionSuite.Dashboard value.
Old:
<head>
...
@Html.DevExpress().GetStyleSheets(
// ...
new StyleSheet { ExtensionSuite = ExtensionSuite.DashboardViewer }
)
...
</head>
New:
<head>
...
@Html.DevExpress().GetStyleSheets(
// ...
new StyleSheet { ExtensionSuite = ExtensionSuite.Dashboard }
)
...
</head>
Tip
Topic: Attach the Style Sheets.
Add Route Definition
Call the RouteCollectionExtension.MapDashboardRoute method to add the MVC Dashboard’s route. The code snippet below shows how to add the required code to the RouteConfig.cs file:
using DevExpress.DashboardWeb.Mvc;
// ...
public static void RegisterRoutes(RouteCollection routes) {
// ...
RouteTable.Routes.MapDashboardRoute("api/dashboard");
// ...
}
Add Extension Code
The DashboardExtension class is used for the Web Dashboard in ASP.NET MVC. To add a Dashboard extension to a View, call the MvcDashboardFactory.Dashboard helper method instead of MvcDashboardFactory.DashboardViewer. This method provides a parameter that returns the DashboardExtensionSettings. Use these settings to switch the Dashboard Extension to the viewer mode:
Old:
@model DevExpress.DashboardWeb.Mvc.DashboardSourceModel
@Html.DevExpress().DashboardViewer(settings => {
settings.Name = "DashboardViewer";
settings.AllowExportDashboard = true;
settings.CallbackRouteValues = new { Controller = "Home", Action = "DashboardViewerPartial" };
settings.ExportRouteValues = new { Controller = "Home", Action = "DashboardViewerPartialExport" };
}).BindToSource(Model).GetHtml()
New:
@Html.DevExpress().Dashboard(settings => {
settings.Name = "Dashboard";
settings.AllowExportDashboard = true;
settings.WorkingMode = DevExpress.DashboardWeb.WorkingMode.ViewerOnly;
}).GetHtml()
Add Controller Code
For the old control, you have to use the Controller.PartialView(String) method to render a Partial View with the MVC Viewer and pass a model to the View:
public ActionResult DashboardViewerPartial() {
return PartialView("_DashboardViewerPartial", DashboardViewerSettings.Model);
}
The MVC Dashboard Control sends requests to the internal DashboardController and adjusts routing only once with the RouteCollectionExtension.MapDashboardRoute method. This allows you to include the MVC Dashboard anywhere in your application. There is no need to create a separate partial View for MVC Dashboard.
Provide Dashboards
The Dashboard Source Model is not used to provide dashboards anymore. You should create dashboard storage instead.
This part of code is not required and you can delete it from the HomeController.cs file:
class DashboardViewerSettings {
public static DashboardSourceModel Model {
get {
return DashboardSourceModel();
}
}
private static DashboardSourceModel DashboardSourceModel() {
DashboardSourceModel model = new DashboardSourceModel();
model.DashboardSource = System.Web.Hosting.HostingEnvironment.MapPath(@"~\File1.xml");
return model;
}
}
Create storage and register the dashboard in it to provide dashboards. The code below shows how to create the default In-Memory storage in the Global.asax file and register a dashboard:
using DevExpress.DashboardWeb;
// ...
public class MvcApplication : System.Web.HttpApplication {
protected void Application_Start() {
// ...
DashboardInMemoryStorage storage = new DashboardInMemoryStorage();
DashboardConfigurator.Default.SetDashboardStorage(storage);
storage.RegisterDashboard("dashboard1", XDocument.Load(System.Web.Hosting.HostingEnvironment.MapPath(@"~\File1.xml")));
}
// ...
}
Tip
Topic: Prepare a Dashboard Storage
Provide Data
The Dashboard Source Model is not used anymore to provide data. You need to use the DashboardConfigurator instead.
- Use the DashboardConfigurator.ConfigureDataConnection event to customize connection settings before the MVC Dashboard connects to a data store (database, OLAP cube, etc.)
- Use the DashboardConfigurator.CustomFilterExpression event to include WHERE clauses in SQL queries.
- Use the DashboardConfigurator.DataLoading event to provide data for a data source assigned in code.
Reload Data
In the MVC Viewer, the ASPxClientDashboardViewer.ReloadData method was used to reload data in all dashboard data sources. For the MVC Dashboard, we change the model of data usage, and data is reloaded automatically. For the MVC Dashboard, we changed the data usage model and data is reloaded automatically. You can handle the ASPxDashboard.ConfigureDataReloadingTimeout event to set the data reloading timeout in the MVC 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 MVC Dashboard has the following specifics related to security:
- MVC Dashboard does not load dashboards with custom SQL queries by default. Refer to the Custom SQL Queries article for details.
- If the working mode is set to viewer and you use the DashboardConfigurator’s server-side API, handle the DashboardConfigurator.VerifyClientTrustLevel event to verify the trust level used to specify which actions a client can initiate to execute them on the server.
- For security reasons, the MVC 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 MVC Dashboard is used.
Tip
Topic: Security Considerations
Appearance
The MVC Dashboard control supports the same set of themes as MVCxDashboardViewer:
- ASPxDashboard.ColorSchemeLight
- ASPxDashboard.ColorSchemeLightCompact
- ASPxDashboard.ColorSchemeDark
- ASPxDashboard.ColorSchemeDarkCompact
Tip
Topic: Appearance Customization
Client-Side API
The MVC 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 an end user applies a filter or changes the master filter item’s state, 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 MVC Dashboard extension, define custom Dashboard Storage and override the LoadDashboard method that is used to load dashboards. You can edit the loaded dashboard in this method and provide the updated version to the MVC Dashboard control.
For instance, see the code below:
public class MyDashboardFileStorage : DashboardFileStorage {
public MyDashboardFileStorage(string workingDirectory) : base(workingDirectory) { }
protected override XDocument LoadDashboard(string dashboardID) {
var doc = base.LoadDashboard(dashboardID);
if (dashboardID == "Dashboard1") {
Dashboard dashboard = new Dashboard();
dashboard.LoadFromXDocument(doc);
//Customize Dashboard
//...
return dashboard.SaveToXDocument();
}
}
}
Refer to the How to customize a dashboard before displaying it in a browser code example to see this approach in action.
Dashboard is not loaded.
A dashboard may not be loaded due to security reasons.The MVC Dashboard control automatically checks whether a dashboard contains data connection parameters. In this case, the dashboard is not loaded. For information on how to protect parameters used to establish a connection to data for the MVC Dashboard, refer to the T453795 ticket.
Cannot find the FilterElementDefaultValues event in the MVC Dashboard.
The MVC Dashboard control provides the IDashboardStateService service that allows you to specify values of parameters, filter elements, and other state parameters. See Manage Dashboard State for more information.
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.