Skip to main content
BuyLog In
.NET Reporting Tools
Search in…
Docs > Detailed Guide to DevExpress Reporting > Use Report Parameters > Create a Report Parameter > Range Report Parameters
All docs
V25.2
    • Reporting
    Product Information
    What's New
    .NET Support
    Get Started with DevExpress Reporting
    Create Different Report Types (Walkthroughs)
    Detailed Guide to DevExpress Reporting
    Introduction to Banded Reports
    Bind Reports to Data
    Use Report Controls
    Use Report Parameters
    Create a Report Parameter
    Report Parameters with Predefined Static Values
    Report Parameters with Predefined Dynamic Values
    Multi-Value Report Parameters
    Cascading Report Parameters
    Range Report Parameters
    Report Parameters of Custom Types
    Reference Report Parameters
    Register Custom Report Parameter Types
    Specify Parameter Values
    The Parameters Panel
    Shape Report Data
    Use Custom Fonts
    Arrange Dynamic Report Contents
    Customize Appearance
    Add Navigation
    Provide Interactivity
    Add Extra Information
    Merge Reports
    Use Expressions
    Store and Distribute Reports
    Globalize and Localize Reports
    Reporting API
    Security Considerations
    AI-powered Extensions
    Report Designer for Visual Studio
    Report Designer for VS Code
    Report Designer for JetBrains Rider
    Reporting for Desktop
    Reporting for .NET MAUI
    Reporting for Web
    Localize Reporting Applications
    Memory Usage in Reporting - Best Practices
    Cloud Integration
    .NET Aspire Integration
    Cross-Platform .NET App UI
    Backend Web API Service / REST API for Reporting
    WCF Report Service
    End-User Documentation
    API Reference
    ASP.NET Core API Reference
    Blazor API Reference
    Client API Reference
    Client API Reference (Web Forms & MVC)

    Range Report Parameters

    • 15 minutes to read

    This topic describes how to create date range and time range parameters and filter report data by specified 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

      Start Parameter and End Parameter sections appear. They specify range options:

      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 an expression, or 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 report 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

    For information on how to add a range parameter to a report in End-User Report Designers, refer to the following topics:

    Create a Range Parameter in Code

    1. Create a parameter and set its Type to a DateTime, DateOnly, or TimeOnly value.
    2. Initialize a RangeParametersSettings class instance and set up its properties.
    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 report 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

    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.

    Date Range Parameters

    Use the RangeParameterEditorOptions.RegisterDateRange method to add a new predefined date range to the collection.

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

    Desktop Reporting - Customized Predefined Date 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));

    Time Range Parameters

    Use the RangeParameterEditorOptions.RegisterTimeRange method 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 Document Viewer/Preview

    The Document Viewer allows you to access predefined ranges on the client-side. Predefined ranges are available in all date/time range parameter editors when they are displayed in the Preview tab or in the Document Viewer.

    Date Range Parameters

    Predefined date ranges are stored in the DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges object. Each predefined date range has the following properties:

    range
    A two-element array of Date objects (startDate, endDate).
    displayName
    The caption displayed to users.

    Web Report Preview - Customized Predefined Date Ranges

    The following code removes built-in 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>

@{
    var viewerRender = Html.DevExpress().WebDocumentViewer("DocumentViewer")
        .Height("1000px")
        .ClientSideEvents(configure =>
        {
            configure.BeforeRender("CustomizePredefinedRanges");
        })
        .Bind("XtraReport1");
    @viewerRender.RenderHtml()
}

    Time Range Parameters

    Predefined time ranges are stored in the DevExpress.Reporting.Viewer.Widgets.predefinedTimeRanges object. Each predefined time range has the following properties:

    range
    A two-element array of Date objects (startDate, endDate).
    displayName
    The caption displayed to users.
    iconTemplate
    The name of the HTML template that displays the icon.

    The following code adds two custom predefined time ranges:

    Web Report Preview - Customized Predefined Time Ranges

    <script type="text/javascript" id="script">
    function CustomizePredefinedRanges(s, e) {
        // Uncomment the following line to remove all predefined time ranges.
        // DevExpress.Reporting.Viewer.Widgets.predefinedTimeRanges.splice(0,
        //     DevExpress.Reporting.Viewer.Widgets.predefinedTimeRanges.length);

        DevExpress.Reporting.Viewer.Widgets.predefinedTimeRanges.push({
            displayName: 'Night Shift',
            iconTemplate: 'nightShiftIcon',
            range: () => {
                const today = new Date();
                const end = new Date(today);
                end.setHours(5, 0, 0, 0);         
                const start = new Date(end);
                start.setDate(end.getDate() - 1);
                start.setHours(23, 0, 0, 0);
                return [start, end];
            }
        });
        DevExpress.Reporting.Viewer.Widgets.predefinedTimeRanges.push({
              displayName: 'Last 2 Hours',
              iconTemplate: 'lastTwoHoursIcon',
              range: () => {
                const end = new Date();
                const start = new Date(end.getTime() - 2 * 60 * 60 * 1000);
                return [start, end];
              }
        });
    }
</script>

<script type="text/html" id="nightShiftIcon">
    <!--...SVG content for nightShiftIcon...-->
</script>
<script type="text/html" id="lastTwoHoursIcon">
    <!--...SVG content for lastTwoHoursIcon...-->
</script>

@{
    var viewerRender = Html.DevExpress().WebDocumentViewer("DocumentViewer")
        .Height("1000px")
        .ClientSideEvents(configure => { 
            configure.BeforeRender("CustomizePredefinedRanges");})
        .Bind("XtraReport1");
    @viewerRender.RenderHtml()
}

    Native Report Viewer for Blazor

    Important

    The Native Report Viewer for Blazor does not support predefined date ranges.

    To access predefined time ranges in Blazor Report Viewer, use the RangeParameterEditorOptions.PredefinedTimeRanges property. To add a new predefined time range to the collection, use RangeParameterEditorOptions.RegisterTimeRange methods.

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

    Blazor Report viewer - Customized Predefined Time Ranges

    @page "/reportviewer/"

@using DevExpress.Blazor.Reporting
@using DevExpress.Blazor.Reporting.Models
@using DevExpress.Utils.Svg
@using DevExpress.XtraReports.Parameters
@using DevExpress.XtraReports.UI
@using BlazorServer.PredefinedReports

<DxReportViewer @ref="reportViewer" Report="Report" RootCssClasses="w-100 h-100" OnCustomizeParameters="OnCustomizeParameters" />

@code {
    DxReportViewer reportViewer;
    XtraReport Report = new TestReport();

    void OnCustomizeParameters(ParametersModel parametersModel) {
        // Uncomment the following line to remove all predefined time ranges.
        // RangeParameterEditorOptions.PredefinedTimeRanges.Clear();
        var svgMoon = SvgImage.FromFile("moon.svg");
        string timeRangeNightShift = "Night Shift";
        if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeNightShift)) {
            RangeParameterEditorOptions.RegisterTimeRange(timeRangeNightShift, () => new TimeOnly(23, 0), () => new TimeOnly(5, 0), svgMoon);
        }
        var svgBack = SvgImage.FromFile("back.svg");
        string timeRangeLastTwoHours = "Last 2 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, svgBack);
        }
    }

}
    See Also