The requested page is not available for the requested platform. You are viewing the content for Default platform.

Request and Pass Report Parameter Values

  • 5 min to read

This document illustrates how to assign the default and custom values to a report's parameters and describes the editors that are used to request these values in a Print Preview.

Requesting Parameter Values in a Print Preview

The Parameter.Value property specifies the parameter's value. This value must correspond to the parameter's value type the Parameter.Type property defines.

A parameter's value is not requested from end-users and is automatically passed to the report when the parameter's Parameter.Visible property is set to false. When a report has at least one visible parameter, a Print Preview provides a user interface for submitting parameter values.

When loading a Print Preview, a report's document is not created by default unless values for all visible parameters are submitted. To create report documents without requesting parameter values (and using their default values instead), set the report's XtraReport.RequestParameters property to false.

Passing Parameter Values at Runtime

You can specify parameter values in code. The following code illustrates how to assign a value to a report parameter at runtime:

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

private void button1_Click(object sender, EventArgs e) {
    // 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;

    // Show the report's print preview depending on your target platform.
    // ...
}

You can provide values to a multi-value report parameter in code by constructing a required type value array and assigning this array to the Parameter.Value property:

report.Parameters["parameter1"].Value = new int[] { 1, 2, 3 };

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

Note

We recommend that you do not assign these property values using parameters when declaring custom public properties in XtraReport class descendants. The application that opens this file must contain a declaration of this report class to restore these property values from a serialized report definition.

Passing Parameter Values to a Web Report Through a URL

In web reporting applications, you can pass a parameter value to a report using 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 required parameter in the XtraReport.Parameters collection and obtain the parameter value using 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 an application and pass a parameter value to your web page as shown below:

Viewer.aspx?parameter1=100

You can also pass values for multiple parameters through a URL by separating them with "&". The general syntax looks as follows:

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

Standard Parameter Editors

The Parameter.Type property determines which values a parameter can accept. The corresponding value editors are created automatically for the following standard parameter types:

  • String
  • Date
  • Number

    • 16-bit integer
    • 32-bit integer
    • 64-bit integer
    • floating point
    • double-precision floating point
    • decimal
  • Boolean
  • GUID (Globally Unique Identifier)

The following image illustrates the standard editors for parameter values in a WinForms application:

parameters-ui-win

Look-Up Parameter Editors

You can list a parameter's values in a lookup editor:

Assign Multiple Values to a Parameter

A parameter can also be allowed to accept multiple values (by enabling its Parameter.MultiValue property).

parameters-ui-multi-value

When creating cascading parameters, the list of values available for one parameter is filtered based on another parameter's current value. See Create Multi-Value and Cascading Report Parameters for more information.

Custom Parameter Editors

For parameters of both standard and custom types, you can implement custom editors. The Parameters panel displays these editors when a report is being loaded in a Print Preview.

Custom editor implementation for parameters varies depending on your application's platform: