Server-Side API Overview
- 4 minutes to read
The Web Forms control comprises client and server parts:
- The client part provides a UI to design and interact with a dashboard.
- The server part handles client data requests and provides backend functionality such as accessing data, storing dashboards, etc.
You should configure the Web Dashboard on the server side before the first use: prepare a dashboard storage, register predefined data sources, add dashboard parameters, etc. Each platform (Web Forms, MVC, .NET Core) has a different approach to utilizing a server-side API. For ASPxDashboard, you can choose between two approaches to set up a server-side backend:
Use the ASPxDashboard control’s server-side API to specify the default settings. The control’s instance exposes this API. It is a default mode. The following code snippet shows basic server-side settings for this approach:
protected void Page_Load(object sender, EventArgs e) { DataSourceInMemoryStorage dataSourceStorage = new DataSourceInMemoryStorage(); // ... ASPxDashboard1.SetDashboardStorage(new DashboardFileStorage(Server.MapPath("App_Data/Dashboards"))); ASPxDashboard1.SetDataSourceStorage(dataSourceStorage); ASPxDashboard1.ConfigureDataConnection += ASPxDashboard1_ConfigureDataConnection; }Use an API the DashboardConfigurator class exposes. In this case, set the ASPxDashboard.UseDashboardConfigurator property to true and use the DashboardConfigurator to process data-related operations and handle data-related events (set the dashboard/data source storage, specify a connection provider, etc). The static DashboardConfigurator.Default property provides access to the DashboardConfigurator class instance. The following code snippet shows basic server-side settings for this approach:
void Application_Start(object sender, EventArgs e) { DataSourceInMemoryStorage dataSourceStorage = new DataSourceInMemoryStorage(); // ... DashboardConfigurator.Default.SetDashboardStorage(new DashboardFileStorage(Server.MapPath("App_Data/Dashboards"))); DashboardConfigurator.Default.SetDataSourceStorage(dataSourceStorage); DashboardConfigurator.Default.ConfigureDataConnection += Default_ConfigureDataConnection; }
ASPxDashboard Control API
The default approach is to use the ASPxDashboard control’s API and use callbacks to exchange data with the server side. It is a native Web Forms approach that allows you to integrate the dashboard control into the ASP.NET Page Life Cycle. The page raises events at each stage of the life cycle that you can handle to run your own code.
The Web Dashboard control uses a RESTful API to request data and performs multiple requests to get the required data from the server. The ASP.NET Web Forms platform does not support parallel requests — additional requests during this time are queued. For example, you have a complex dashboard that displays multiple data bound items. If you change the master filter in a certain item and you have a few detail items in which data should be updated, all these items send their own requests to the server one-by-one. The session state blocks parallel execution and forces parallel requests to be executed sequentially. This behavior can lead to performance degradation. You can support multiple requests in one of the following ways:
- Disable the session state.
- Use an API the DashboardConfigurator class exposes.
- Enable batch requests when ASPxDashboard loads dashboard items’ data. For this, set the DataRequestOptions.ItemDataRequestMode property to BatchRequests.
DashboardConfigurator Instance API
The DashboardConfigurator‘s API allows you to support simultaneous requests. When the server responds with the data, the browser uses JavaScript to receive the data, processes it and updates only the part of the page that changed. All this occurs asynchronously in the background without any page reloads.
The DashboardConfigurator sends requests to the server using the HTTP Handlers. All operations are performed by the HTTP Handler - the ASPX page is not created. Since the Session is disabled by default, asynchronous parallel processing is possible. This saves a lot of resources and decreases request processing time, especially if the dashboard is displayed on a complex page.
Follow the steps below to use the DashboardConfigurator:
Set the ASPxDashboard.UseDashboardConfigurator property to true.
Register a new ASPxHttpHandlerModule that should process requests with the DXDD.axd path:
<system.web> ... <httpHandlers> ... <add type="DevExpress.Web.ASPxHttpHandlerModule, DevExpress.Web.v18.2, Version=18.2.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" verb="GET,POST" path="DXDD.axd" validate="false" /> </httpHandlers> </system.web> <system.webServer> ... <handlers> ... <add type="DevExpress.Web.ASPxHttpHandlerModule, DevExpress.Web.v18.2, Version=18.2.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" verb="GET,POST" path="DXDD.axd" name="WebDashboardHandler" preCondition="integratedMode" /> </handlers> </system.webServer>In the Application_Start method of the Global.asax file, use the DashboardConfigurator.SetDashboardStorage method to assign a dashboard storage to the DashboardConfigurator.
Configure additional Web Dashboard’s settings at the DashboardConfigurator‘s level if necessary. For example, customize connection settings, specify a custom data store schema, set a data connection provider, etc.
If you want to access the Session from DashboardConfigurator‘s events, perform the following steps:
- Set the DashboardBootstrapper.SessionState property to ReadOnly to notify the handler that the session should be loaded before actual processing;
Call the static ASPxDashboard control’s constructor to initialize the handler and required resources:
DevExpress.DashboardWeb.DashboardBootstrapper.SessionState = SessionStateBehavior.ReadOnly; ASPxDashboard.StaticInitialize();