Request and Pass Report Parameter Values

https://docs.devexpress.com/XtraReports/10000/detailed-guide-to-devexpress-reporting/shape-report-data/use-report-parameters/request-and-pass-report-parameter-values

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:

• C#
• VB.NET

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:

• C#
• VB.NET

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.

• C#
• VB.NET

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:

#Look-Up Parameter Editors

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

• Assign a Static List of Values to a Parameter

  A parameter can be provided with a predefined set of static values, without creating a separate data source. Each value is accompanied by a description that appears in the Print Preview's user interface.

  

  See How to assign a list of static values to a report parameter for a code example.

• Assign a Dynamic List of Values to a Parameter

  A parameter can obtain a list of values from a specified data source.

  

  See How to assign a list of dynamic values to a report parameter for a code example.

#Assign Multiple Values to a Parameter

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

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:

• Windows Forms

  In Windows Forms applications, you can provide custom parameter editors in the XtraReport.ParametersRequestBeforeShow event handler.

  For a code sample, see Provide Custom Editors for Report Parameters.

• WPF

  To customize report parameter editors in WPF applications, assign a custom DataTemplate to the ParametersPanel.ParameterTemplateSelector property.

  For a code sample, see Provide Custom Editors for Report Parameters.

• ASP.NET

  You can provide custom parameter editors in the ASPxClientWebDocumentViewer.CustomizeParameterEditors event handler.

  For a code sample, see Provide Custom Editors for Report Parameters.