Skip to main content
All docs
V24.1

Reference Report Parameters

  • 6 minutes to read

After you create a report parameter, you can reference this parameter in the report’s filter string, in expressions, and in a control’s Text property. You can also bind control and data source parameters to report parameters. Refer to the sections below for more details.

Reference in a Report’s Filter String

You can reference a report parameter in the report’s filter string. This allows you to conditionally filter the report’s data loaded from a data source.

reference parameter in report filter string

Tip

When you use a report’s filter string to filter data, all the data is loaded from a data source before the filter is applied. If you use a large dataset, filter data at the data source level. Refer to the Filter Data topic for more information.

Reference in Expressions

You can reference a report parameter in expressions of controls and calculated fields.

Reference report parameters in expressions

This allows you to conditionally change the data a control or calculated field displays.

You can use the Field List to create an XRLabel control that displays only a parameter value. To do this, drag the parameter from the Field List and drop it onto the report’s band.

Drag and drop a report parameter

You can also use parameters in expressions to specify the visibility of a report’s bands or conditionally change a control’s appearance.

Reference parameters in the Expression Editor

Refer to the following topics for more information:

Reference in a Control’s Text Property

You can use a report parameter in a control’s Text property.

Reference a parameter in a control's Text property (Designer)

This allows you to create a placeholder (embedded field) that is substituted by a parameter value.

Reference a parameter in a control's Text property (Preview)

Refer to the following topic for information on embedded fields: Use Embedded Fields (Mail Merge).

Bind Control Parameters to Report Parameters

You can create parameters for the XRCrossTab and XRChart controls and bind these parameters to report parameters. This allows you to conditionally filter data at the control level. Refer to the following topic for details on how to filter data for the XRChart control: Use Charts to Visualize Grouped Data.

You can also specify a parameter for the XRSubreport control and bind this parameter to report parameters. This allows you to pass parameter values from the main report to the subreport and conditionally change the subreport’s data and appearance. Refer to the following topic for more information: XRSubreport - Reference a Report.

Bind Data Source Parameters to Report Parameters

You can create parameters for data sources and bind them to report parameters. The table below contains information about which tasks this allows you to solve, a data source for which the task can be solved, and links to documentation sections you can reference for details.

Task Data Source Documentation
Filter data at the data source level SQL Data Source
Entity Framework Data Source
MongoDB Data Source
Bind a Report to a Database
Bind a Report to an Entity Framework Data Source
Bind a Report to a MongoDB Instance
Pass report parameters to a stored procedure SQL Data Source
Entity Framework Data Source
Use Query Parameters
Bind a Report to an Entity Framework Stored Procedure
Pass report parameters to a method that loads data Object Data Source Bind a Report to an Object Data Source

When you bind a report to the JSON Data Source, you can specify a URI from which a JSON file should be loaded. You can bind path parameters, query parameters, and header parameters to report parameters to conditionally configure HTTP requests to the web service endpoint. Refer to the following topic for details: Bind a Report to JSON Data.

Reference a Report Parameter in Code

The code sample below demonstrates how to create a date parameter, specify an expression for the parameter’s default value, and reference the parameter in a label‘s expression.

using System.Drawing;
using DevExpress.XtraReports.UI;
// ...
using DevExpress.XtraReports.Parameters;
// ...
using DevExpress.XtraReports.Expressions;
// ...
// Create a date report parameter.
// Use an expression to specify the parameter's default value.
var dateParameter = new Parameter() {
    Name = "date",
    Description = "Date:",
    Type = typeof(System.DateTime),
    ExpressionBindings = { new BasicExpressionBinding("Value", "Now()") }
};

// Create a label and bind the label's Text property to the parameter value.
// Use the parameter's name to reference the parameter in the label's expression.
var dateLabel = new XRLabel() {
    ExpressionBindings = { new ExpressionBinding("Text", "?date") },
    BoundsF = new RectangleF(0, 0, 200, 50),
};

// Create a report and add the label to the report's Detail band.
var report = new XtraReport() {
    Bands = { new DetailBand() { Controls = { dateLabel } } },
};

// Add the parameter to the report's Parameters collection.
report.Parameters.Add(dateParameter);

If a report parameter’s Value property is set to an expression, assigning a static value to this property in code has no effect. When you open the report Preview, the expression value is displayed instead of the assigned static value.

If you want to change the default expression value to a static value in code, remove the expression from the parameter’s ExpressionBindings collection and then assign the static value to the parameter’s Value property:

using DevExpress.XtraReports.UI;
using System;
using System.Linq;
// ...
var report = new XtraReport();
report.LoadLayoutFromXml("../Path/To/Report.repx");

var paramName = "date";
var parameter = report.Parameters[paramName];
var paramValueExpression = parameter.ExpressionBindings
    .FirstOrDefault(p => p.PropertyName == "Value");

// Remove an expression from the report's ExpressionBindings collection.
if (paramValueExpression != null) {
    parameter.ExpressionBindings.Remove(paramValueExpression);
}

// Assign a static value to the parameter's Value property.
report.Parameters[paramName].Value = DateTime.Parse("02/05/2022");