Create a Report Parameter

  • 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.

    Shared_FieldList_AddParameter

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

    Shared_FieldList_AddParameter

  • 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.

    parameters-filter-string-add-parameter

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.

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);

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.

parameters-add-new-dialog

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.

parameters-ui-win

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

Pass Parameter Values in Code

Specify Parameter Values

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

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;

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:

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.

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);  
}