Create a Report Parameter

• May 02, 2022
• 6 minutes to read

This topic demonstrates how to create a report parameter in the Visual Studio Report Designer and in code. The topic also describes the options you can specify for a report parameter.

Create a Report Parameter in the Report Designer

In the Visual Studio Report Designer, you can create a parameter from the Field List, Properties window, or FilterString Editor. The created parameter appears in the Field List‘s Parameters node.

Create From the Field List

Right-click the Parameters node in the Field List and select Add Parameter.

Specify parameter options in the invoked Add New Parameter dialog and click OK.

Create From the Properties Window

Select a report and click the Parameters property’s ellipsis button in the Properties window.

Click Add parameter in the invoked Report Parameters Editor dialog to add a new parameter. Specify parameter options and click OK.

Create From the FilterString Editor

You can create a parameter when you construct a condition in the FilterString Editor. Choose the Select a parameter field, click the field, and select Add Parameter in the invoked context menu.

Specify parameter options in the invoked Add New Parameter dialog and click OK.

Parameter Options

Name

The name by which you can reference a parameter in a report.

Note

Report parameters should have unique names. A name should not contain C# keywords or XtraReport property names.

Description

A parameter description that appears on a report’s Print Preview in the Parameters panel.

Visible

Specifies whether a parameter is visible in the Parameters panel.

You can assign an expression to this option. The example below specifies an expression that shows/hides a parameter based on a value of another parameter.

Enabled

Specifies whether a parameter editor is enabled or disabled in the Parameters panel. You can set this option to No to make a parameter’s default value read-only.

You can also assign an expression to this option. The example below specifies an expression that enables/disables a parameter’s editor based on a value of another parameter.

Type

The type of parameter values. The following types are available:

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

You can also create a parameter of a custom type.

Default Value

A parameter’s default value. This value is displayed in the Parameters panel when you open a report’s Print Preview.

You can specify an expression for this option. For example, set this option to Now() to use the current date as a date parameter’s default value.

Note

You can use only constants, operators, and date-time, logical, math, and string functions in an expression for a parameter’s default value.

Allow Null Value

When the Allow Null Value option is enabled, you can leave the parameter’s value unspecified.

Allow Multiple Values

When the Allow Multiple Values option is enabled, you can specify multiple values for a report parameter.

Select All Values

Enable the Select All Values option to use all elements from a custom set of values as a parameter’s default value.

Note

You can specify the Select All Values option only when the Allow Multiple Values option is enabled.

Value Source

Use the Value Source option to specify a custom set of values a parameter can accept. You can create a static list of values, load values from a data source, or specify a date range. Refer to the following topics for more details:

• Report Parameters with Predefined Static Values
• Report Parameters with Predefined Dynamic Values
• Date Range Report Parameters

Create a Report Parameter in Code

To create a parameter in code, initialize a Parameter class instance and specify its properties. Add the parameter to the report’s Parameters collection.

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.

C#

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

VB.NET

Imports DevExpress.XtraReports.UI
' ...
Imports DevExpress.XtraReports.Parameters
' ...
Imports DevExpress.XtraReports.Expressions
' ...
' Create a date report parameter.
' Use an expression to specify the parameter's default value.
Dim dateParameter = New Parameter() With {
    .Name = "date",
    .Description = "Date:",
    .Type = GetType(Date)
}

dateParameter.ExpressionBindings.Add(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.
Dim dateLabel = New XRLabel() With {.BoundsF = New RectangleF(0, 0, 200, 50)}

dateLabel.ExpressionBindings.Add(New ExpressionBinding("Text", "?date"))

' Create a report and add the label to the report's Detail band.
Dim report = New XtraReport()
Dim band = New DetailBand()
band.Controls.Add(dateLabel)
report.Bands.Add(band)

' 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:

C#

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

VB.NET

Imports DevExpress.XtraReports.UI
Imports System
Imports System.Linq
'...

Private report = New XtraReport()
report.LoadLayoutFromXml("../Path/To/Report.repx")

Dim paramName = "date"
Dim parameter = report.Parameters(paramName)
Dim paramValueExpression = parameter.ExpressionBindings.FirstOrDefault(Function(p) p.PropertyName = "Value")

' Remove an expression from the report's ExpressionBindings collection.
If paramValueExpression IsNot Nothing Then
    parameter.ExpressionBindings.Remove(paramValueExpression)
End If

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