Skip to main content

DevExpress v25.1 Update — Your Feedback Matters

Our What's New in v25.1 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

Range Report Parameters

  • 9 minutes to read

This topic describes how to create date range and time range parameters and filter a report’s data by the specified date or time values.

#Create a Range Parameter in the Report Designer

Follow the steps below to add a range parameter to a report in Visual Studio Report Designer:

  1. Create a report parameter.
  2. In the Add New Parameter dialog, specify parameter options:

    • Parameter type: Date and Time, Date, or Time
    • Value Source: Range Parameters

    The Start Parameter and End Parameter sections that appear allow you to configure options to create a date or time range:

    The "Add new parameter" dialog for a range parameter

  3. You can change the Name and initial static Value for the Start Parameter and End Parameter. To specify an expression instead of a static value, click the Value option’s ellipsis button and use the Expression Editor dialog:

    The "Add new parameter" dialog for a range parameter - Expression

  4. Reference the created range 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.

    We recommend that you use the following functions with range parameters in expressions and filter strings:

    The image below filters the report’s data by the following filter string:

    InDateRange([ShippedDate], ?paramDateRange_Start, ?paramDateRange_End)

    Reference the created range parameter in the filter string

When you switch to the report’s Print Preview tab, the Parameters Panel displays the newly created range parameter. Click the editor to set a range. The editor type depends on the parameter type:

An editor for “Date” and “Date and Time” range parameters:
A date range parameter's editor on Print Preview.
An editor for “Time” range parameters
A time range parameter's editor on Print Preview.

After you submit start and end values, the report document shows filtered data. The report below shows the ShippedDate field filtered by the date range parameter:

The report data is filtered by the date range

#Create a Range Parameter in Code

  1. Initialize a RangeParametersSettings class instance and set up its properties.
  2. Create a parameter and set its Type to a DateTime, DateOnly, or TimeOnly value.
  3. Assign the created RangeParametersSettings object to the parameter’s ValueSourceSettings property.
  4. Add the parameter to the report’s Parameters collection.

The following code sample creates a date range parameter in code and uses this parameter to filter the report’s data:

View Example: Create a Date Range Report Parameter

using System;
using System.IO;
using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DataAccess.Sql;
using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.UI;
// ...
            // Create a date range parameter.
            var dateRangeParam = new Parameter();
            dateRangeParam.Name = "dateRange";
            dateRangeParam.Description = "Date Range:";
            dateRangeParam.Type = typeof(System.DateTime);

            // Create a RangeParametersSettings instance and set up its properties.
            var dateRangeSettings = new RangeParametersSettings();

            // Specify the start date and end date parameters.
            dateRangeSettings.StartParameter.Name = "dateRangeStart";
            dateRangeSettings.StartParameter.ExpressionBindings.Add(
                new BasicExpressionBinding("Value", "AddYears(Today(), -1)")
            );

            dateRangeSettings.EndParameter.Name = "dateRangeEnd";
            dateRangeSettings.EndParameter.ExpressionBindings.Add(
                new BasicExpressionBinding("Value", "AddYears(Today(), 0)")
            );

            // Assign the settings to the parameter's ValueSourceSettings property.
            dateRangeParam.ValueSourceSettings = dateRangeSettings;

            // Create a report instance and add the parameter to the report's Parameters collection.
            var report = new XtraReport1();
            report.Parameters.Add(dateRangeParam);

            // Use the parameter to filter the report's data.
            report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)";

#Customize Predefined Ranges

Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.

The date and time range parameter editor allows you to select a range from a list of predefined ranges. You can remove items from the list or add a custom range.

#WinForms and WPF Reporting

The set of predefined date ranges is stored in the RangeParameterEditorOptions static class and is available in all date range parameter editors when they are displayed in the Preview tab. Use the RegisterDateRange(String, Func<DateTime>, Func<DateTime>) to add a new predefined date range to the collection.

predefined date ranges

The following code sample removes all predefined date ranges and creates two new ranges:

using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.Expressions;
// ...
// Remove all predefined ranges and add two new date ranges.
RangeParameterEditorOptions.PredefinedDateRanges.Clear();
RangeParameterEditorOptions.RegisterDateRange("September", () => new DateTime(2019,9,1), () => new DateTime(2019,9,30));
RangeParameterEditorOptions.RegisterDateRange("October", () => new DateTime(2019,10,1), () => new DateTime(2019,10,31));

If you want to customize time ranges, use the RangeParameterEditorOptions.RegisterTimeRange methods to add a new predefined time range to the collection.

The following code adds two new time ranges to the existing collection:

A user specifies start time and end time. The custom **Night Shift** and **Last Two Hours** time ranges are added.

using DevExpress.XtraReports.Parameters;
// ...
// Uncomment the line below if you want to clear the collection before adding new time ranges:
//RangeParameterEditorOptions.PredefinedTimeRanges.Clear();
string timeRangeNightShift = "Night Shift";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeNightShift)) {
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeNightShift,() => new TimeOnly(23,0),() => new TimeOnly(5,0),SvgImage.FromFile("time.svg"));
}
string timeRangeLastTwoHours = "Last Two Hours";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeLastTwoHours)) {
    TimeOnly previousHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(-2));
    TimeOnly currentHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(0));
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeLastTwoHours, () => previousHour,() => currentHour);
}

#Web Reporting

Warning

  • Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.

  • The Native Report Viewer for Blazor does not display support predefined date ranges for date range report parameters.

Predefined date ranges are stored in the client-side collection of the Document Viewer widgets. The set of predefined date ranges is available in all date range parameter editors when they are displayed in the Preview tab.

web-predefined-date-ranges

The following code removes built-in predefined ranges and adds two custom predefined ranges.

<script type="text/javascript" id="script">
    function CustomizePredefinedRanges(s, e) {
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);

        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2023, 8, 1),
                new Date(2023, 8, 30)
            ]
        })
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2023, 9, 1),
                new Date(2023, 9, 31)
            ]
        })
    }
</script>

<dx:ASPxWebDocumentViewer ClientInstanceName="WebDocumentViewer1" ID="ASPxWebDocumentViewer1" runat="server">
    <ClientSideEvents BeforeRender ="CustomizePredefinedRanges" />
</dx:ASPxWebDocumentViewer>

#Limitations

See Also