xtrareports-devexpress-dot-xtrareports-dot-ui-dot-xtrareportbase-2020f999.md
Specifies the criteria used to filter data in a report.
Namespace : DevExpress.XtraReports.UI
Assembly : DevExpress.XtraReports.v25.2.dll
NuGet Package : DevExpress.Reporting.Core
[DefaultValue("")]
[SRCategory(ReportStringId.CatData)]
public virtual string FilterString { get; set; }
<DefaultValue("")>
<SRCategory(ReportStringId.CatData)>
Public Overridable Property FilterString As String
| Type | Default | Description |
|---|---|---|
| String | String.Empty |
A String value that specifies the filter criteria.
|
Important
A filter expression may become invalid and reset due to internal errors because client-side filtering only applies to loaded data. In multi-tenant environments, use filtering at the data source level to retrieve accurate data from the server.
Use the FilterString property to invoke the FilterString Editor that enables you to specify filter criteria.
At runtime, the FilterString property must be set before calling the XtraReport.CreateDocument method or any other method that calls it internally (for example, PrintTool.ShowPreview, PrintTool.ShowPreviewDialog, PrintToolBase.Print, PrintTool.PrintDialog, and all export methods). It is appropriate to set this property in the following event handlers:
You can also handle the XRControl.BeforePrint event of a specific report band (for example, the DetailBand). In this event handler, you can do the following:
e.Cancel property to cancel printing of the band under a specific condition.Note that FilterString filters data at the report level (on the client side). This means that the report loads all data first and then filters it based on the FilterString value. We do not recommend that you use the FilterString property when working with large amounts of data because you may encounter performance issues.
See the following help topic for information on how to filter data:
This example demonstrates how to create a report with a parameter at runtime.
After a parameter is added to a report, its value can be used in the report’s filter string or displayed in a Label control.
In Preview, users can modify the parameter value in the Parameters panel.
using System;
using System.Windows.Forms;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Parameters;
// ...
// Create a report instance.
XtraReport report = new XtraReport();
// Create a parameter and specify its name.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryID";
// Specify other parameter properties.
parameter1.Type = typeof(System.Int32);
parameter1.Value = 1;
parameter1.Description = "Category: ";
parameter1.Visible = true;
// Add the parameter to the report.
report.Parameters.Add(parameter1);
// Specify the report's filter string.
report.FilterString = "[CategoryID] = ?CategoryID";
// Force the report creation without previously
// requesting the parameter value from end users.
report.RequestParameters = false;
// To access a parameter from the report's Parameters collection,
// you can either use the parameter's ID
// or the parameter name.
// Both lines below have the same effect: the parameter value is set to 5.
report.Parameters[0].Value = 5;
report.Parameters["CategoryID"].Value = 5;
// Show the parameter's value on a Report Header band.
XRLabel label = new XRLabel();
label.ExpressionBindings.Add(new ExpressionBinding("Text", "'Category: ' + ?CategoryID"));
ReportHeaderBand reportHeader = new ReportHeaderBand();
reportHeader.Controls.Add(label);
report.Bands.Add(reportHeader);
// Assign the report to a ReportPrintTool,
// to hide the Parameters panel,
// and show the report's print preview.
ReportPrintTool reportPrintTool = new ReportPrintTool(report);
reportPrintTool.ShowPreviewDialog();
Imports System
Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Parameters
' ...
' Create a report instance.
Private report As New XtraReport()
' Create a parameter and specify its name.
Private parameter1 As New Parameter()
parameter1.Name = "CategoryID"
' Specify other parameter properties.
parameter1.Type = GetType(System.Int32)
parameter1.Value = 1
parameter1.Description = "Category: "
parameter1.Visible = True
' Add the parameter to the report.
report.Parameters.Add(parameter1)
' Specify the report's filter string.
report.FilterString = "[CategoryID] = ?CategoryID"
' Force the report creation without previously
' requesting the parameter value from end users.
report.RequestParameters = False
' To access a parameter from the report's Parameters collection,
' you can either use the parameter's ID
' or the parameter name.
' Both lines below have the same effect: the parameter value is set to 5.
report.Parameters(0).Value = 5
report.Parameters("CategoryID").Value = 5
' Show the parameter's value on a Report Header band.
Dim label As New XRLabel()
label.ExpressionBindings.Add(New ExpressionBinding("Text", "'Category: ' + ?CategoryID"))
Dim reportHeader As New ReportHeaderBand()
reportHeader.Controls.Add(label)
report.Bands.Add(reportHeader)
' Assign the report to a ReportPrintTool,
' to hide the Parameters panel,
' and show the report's print preview.
Dim reportPrintTool As New ReportPrintTool(report)
reportPrintTool.ShowPreviewDialog()
The following online examples illustrate how to create multi-value parameters in code:
View Example: How to assign multiple values to a report parameterView Example: How to assign multiple values to a report parameter from a connected data source
The following code snippets (auto-collected from DevExpress Examples) contain references to the FilterString property.
Note
The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.
asp-net-mvc-grid-create-report-based-on-grid-layout/CS/E4755/Models/ReportHelperMVC.cs#L102
void InitFilters(MVCxGridViewState gridViewState) {
report.FilterString = gridViewState.FilterExpression;
}
reporting-winforms-parameter-daterange/CS/Program.cs#L48
// Use the parameter to filter the report's data.
report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)";
reporting-winforms-parameter-multivalue/CS/Program.cs#L52
// Use the parameter to filter the report's data.
report.FilterString = "CategoryID in (?CategoryIDs)";
asp-net-web-forms-grid-create-report-based-on-grid-layout/CS/WebApplication1/ReportHelper.cs#L143
void InitFilters(ASPxGridView aspxGridView1) {
report.FilterString = aspxGridView1.FilterExpression;
}
reporting-winforms-add-report-parameters/CS/ReportParameterExample/Form1.cs#L29
// Specify the report's filter string.
report.FilterString = "[CategoryID] = [Parameters.CatID]";
asp-net-mvc-grid-create-report-based-on-grid-layout/VB/E4755/Models/ReportHelperMVC.vb#L98
Private Sub InitFilters(ByVal gridViewState As MVCxGridViewState)
report.FilterString = gridViewState.FilterExpression
End Sub
reporting-winforms-parameter-daterange/VB/Program.vb#L40
' Use the parameter to filter the report's data.
report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)"
ConfigureDataSource(report)
reporting-winforms-parameter-multivalue/VB/Program.vb#L56
' Use the parameter to filter the report's data.
report.FilterString = "CategoryID in (?CategoryIDs)"
reporting-winforms-parameter-static-list/VB/Form1.vb#L67
' Use the created parameter to filter the report's data.
report.FilterString = "GetDate([OrderDate]) >= ?dateParameter"
#End Region
asp-net-web-forms-grid-create-report-based-on-grid-layout/VB/WebApplication1/ReportHelper.vb#L146
Private Sub InitFilters(ByVal aspxGridView1 As ASPxGridView)
report.FilterString = aspxGridView1.FilterExpression
End Sub
See Also