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 to allow 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;

Also, you can 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 Web Report in a URL

Add the Web Document Viewer to your web page and handle the Page_Load event. In the event handler, create a new report instance, find the parameter in the report's Parameters collection and obtain the parameter value from the Request.QueryString property.

using DevExpress.XtraReports.Web;
//...
protected void Page_Load(object sender, EventArgs e) {
    XtraReport1 report = new XtraReport1();
    report.Parameters["parameter1"].Value = Convert.ToInt32(Request.QueryString["parameter1"]);
    ASPxWebDocumentViewer1.OpenReport(new CachedReportSourceWeb(report));
}

Run the application and pass the parameter value to your web page as shown below:

Viewer.aspx?parameter1=100

You can also pass values for multiple parameters. Separate parameter values with the & character:

_{WebPageURL}?{ParameterName1}={ParameterValue1}&{ParameterName2}={ParameterValue2}_

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