Report Parameters in ASP.NET Core Applications
- 4 minutes to read
Report parameters allow the user to filter report data and modify the report appearance. This topic describes how to handle report parameters in an ASP.NET Core Reporting application. For general information about report parameters, review the following help section: Use Report Parameters.
The client should pass parameter values to the server so that the server-side reporting engine can apply parameters and process the report. The Document Viewer control (and the Report Designer Preview) on the client displays the Parameters panel, which shows editors for the visible report parameters and allows the user to specify parameter values and send parameters to the server. In your application, you can bypass the reporting controls UI and send parameters to the server in a URL query string.
Specify Parameter Values
You can use the Parameters Panel or the Document Viewer Client-Side API to specify parameter values. The ParametersInitialized client-side event allows you to get the client-side parameter values when they are initialized and modify them. You can also submit parameter values in a URL’s query string. Refer to the following topic for more information: Specify Parameter Values in an ASP.NET Core Reporting Application.
Parameters in the Document Viewer
The Document Viewer displays a panel that shows editors for visible report parameters and allows users to set parameter values.
The Document Viewer loads a report and builds a client-side parameter model. You can use the IPreviewModel.GetParametersModel client-side method to access parameters on the client.
The Document Viewer subsequently analyzes the parameter model and creates editors for each visible parameter. The editor type depends on the parameter type, as illustrated in the following table:
| Parameter Type | Editor Type |
|---|---|
| String | dxTextBox |
| DateTime | dxDateBox |
| Int16, Int32, Int64, Single, Double, Decimal | dxTextBox |
| Guid | dxTextBox |
| Boolean | dxSelectBox |
| Enum | dxSelectBox |
| Any type with predefined values | dxSelectBox |
| Any type with predefined values and multi-value option enabled | dxTagBox |
| Date Range - the DateTime type with predefined values from the RangeParametersSettings | A complex control that includes two dxCalendar controls |
You can handle the CustomizeParameterEditors event to customize the standard editors. You can also use a different DevExtreme editor for a certain parameter type. Review the following help topic for an example: Custom Parameter Editor in the Document Viewer (ASP.NET Core).
Parameters in the Report Designer
The Report Designer allows you to add a parameter to the report or edit existing parameters.
The Parameter.Type enumeration contains common parameter types that are available out-of-the-box. You can call the client-side RemoveParameterType method to unregister a parameter type, so that the user cannot add a parameter of this type to a report.
The following objects define each parameter type available in the Report Designer:
- ParameterInfo
- An object that contains parameter settings. Use the GetParameterInfo method to obtain parameter settings for the specified parameter type.
- EditorOptions
- An object that specifies the editor that displays parameter values. Use the GetParameterEditor method to obtain an editor for the specified parameter type.
The AddParameterType method allows you to register a new parameter type. The method requires the ParameterInfo and EditorOptions objects.
The following image shows the dialog used to add a parameter to a report in the customized Report Designer component. The customization removes the System.DateTime type, and adds the Custom Type parameter type.
You can configure parameter editing settings, (for example, make parameters, parameter groups, and parameter separators read-only or disable specified property editors for parameters). For more information on parameter editing settings, refer to the following topic: Specify Parameter Editing Settings .
Custom Parameter Types
If your report requires a parameter whose type is not based on the available report parameter types, you should implement the following functionality:
- Custom serializer
- The parameter can be stored in a session, in report definition files, and passed from the client to the server and back.
- Type converter
- When a parameter is bound to a report control, the control calls the converter to display the parameter value.
- Client-side editor
- Displays and edits the parameter value.
This functionality should be available for all reports that contain a custom parameter type, in Report Designer and Document Viewer components.
For implementation details and code examples, review the following help topic: Create Editors for Custom Parameter Types in an ASP.NET Core Application.