Create a Report Parameter

• Oct 13, 2020
• 5 minutes to read

This topic describes how to create a basic report parameter and specify its value.

Create a Parameter at Design Time

Report Designers offer multiple ways to create a parameter:

• Right-click Parameters in the the Field List and select Add Parameter from the context menu.

  

• Select the report and click the Parameters property’s ellipsis button in the Property Grid. Click Add in the invoked Report Parameters Editor dialog.

  

• Create a parameter in-place in dialogs and wizards. The image below shows how to create a parameter in a FilterString Editor. Select Add Parameter from the context menu when you construct a condition.

  

Specify the following basic options:

Option	Description
Name	A parameter should have a unique name with which you can refer to this parameter in expressions and filter strings.
Type	Specifies which values a parameter can accept. See the Parameter Types section for more information.
Default Value or Expression	Specifies a parameter’s value. Expressions are parsed and processed to obtain a value.
Show in the parameters panel (corresponds to the parameter’s Visible property)	Specifies whether to show the parameter’s editor in the Parameters panel. This editor allows users to change the value.

Create a Parameter in Code

The code sample below creates a Parameter class instance, specifies its properties, and adds this instance to the report’s Parameters collection.

C#

using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.Expressions;
// ...
XtraReport report = new XtraReport();
Parameter parameter = new Parameter() {
    Name = "dateParameter",
    Type = typeof(System.DateTime),
    Value = DateTime.Now
};
report.Parameters.Add(parameter);

VB.NET

Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Parameters
Imports DevExpress.XtraReports.Expressions
' ...
Private report As New XtraReport()
Private parameter As New Parameter() With {.Name = "dateParameter", .Type = GetType(Date), .Value = Date.Now}
report.Parameters.Add(parameter)

You can specify additional parameter options based on your scenarios. See the sections below for more information.

Parameter Types

The Parameter.Type property determines which values a parameter can accept. The following parameter types are available:

• String
• Date

• Number

  • 16-bit integer
  • 32-bit integer
  • 64-bit integer
  • floating point
  • double-precision floating point
  • decimal

• Boolean

• GUID (Globally Unique Identifier)

You can create a parameter of custom type.

Use the Parameters Panel to Ask for User Input

Enable the Show in the parameters panel option (corresponds to the parameter’s Visible property) to make your report interactive. Document Viewers display the Parameters panel that shows editors for report parameters marked as visible. This allows users to specify a value before the report is rendered. Specify the parameter’s Description to display the editor’s caption in the Parameters panel.

The Reset button reverts the parameters displayed on the Parameters panel to their previous values.

Tip

Disable the report’s RequestParameters property to avoid the Waiting for parameter values message in Preview and display the report with default parameter values.

Enable the Allow Null Value property if the parameter’s value can be unspecified.

The following image shows editors for different parameter types.

To implement a custom editor, select your platform from the list below.

• Windows Forms - handle the XtraReport.ParametersRequestBeforeShow event. See Provide Custom Editors for Report Parameters for a code sample.

• WPF - assign a custom DataTemplate to the ParametersPanel.ParameterTemplateSelector property to customize report parameter editors in a WPF application. See Provide Custom Editors for Report Parameters for a code sample.

• ASP.NET - handle the ASPxClientWebDocumentViewer.CustomizeParameterEditors event to create custom parameter editors. See Provide Custom Editors for Report Parameters for a code sample.

Pass Parameter Values in Code

Specify Parameter Values

The following code illustrates how to assign a value to a report parameter:

C#

using System;
using System.Windows.Forms;
// ...

// Create a report instance.
XtraReport1 report = new XtraReport1();

// Obtain a parameter and set its value.
report.Parameters["parameter1"].Value = 30;

// Hide the Parameters' UI from end-users (if you did not hide it at design time).
report.Parameters["parameter1"].Visible = false;

VB.NET

Imports System
Imports System.Windows.Forms
' ...

' Create a report instance.
Dim report As New XtraReport1()

' Obtain a parameter and set its value.
report.Parameters("parameter1").Value = 30

' Hide the Parameters' UI from end-users (if you did not hide it at design time).
report.Parameters("parameter1").Visible = False

You can also update a parameter’s value in a report’s BeforePrint event handler or in a method that generates a report document (such as PrintTool.ShowPreviewDialog or PrintTool.ShowRibbonPreviewDialog).

Pass Parameter Values to a Report in a Web Application

Include parameters as the query string in the report URL and pass the modified URL to the method that opens a report. On the server side, parse the URL and apply parameters to the report before it is opened.

The method implementation is different for different platforms. Review the following topics for more information:

• ASP.NET Web Forms - Pass Parameters from the Client to a Report
• Angular - Pass Parameters from the Client to a Report

You can also use the client-side API and call the GetParametersModel method to access the report parameters:

ASP.NET Web Forms and MVC	Angular	ASP.NET Core, React, Vue
ASPxClientWebDocumentViewer.GetParametersModel	JSReportViewer.GetParametersModel	IPreviewModel.GetParametersModel

Set Parameter Values on a Button Click

Handle the button click event in an MVC application to specify report parameters.

C#

public ActionResult Viewer(int rowKey) {  
            string someValue = GetAParamValueByAKey(rowKey);  
            var report = new XtraReport1();  
            // Pass parameters to a report.
            report.Parameters\["param1"].Value \= someValue;  
            return View(report);  
}

VB.NET

Public Function Viewer(ByVal rowKey As Integer) As ActionResult
            Dim someValue As String = GetAParamValueByAKey(rowKey)
            Dim report = New XtraReport1()
            ' Pass parameters to a report.
            report.Parameters\("param1").Value \= someValue
            Return View(report)
End Function