Criteria Properties

• Jul 08, 2026
• 6 minutes to read

Use criteria properties to store filter expressions in your business objects. XAF displays these properties with a Filter Builder control or a pop-up filter editor. Filter expressions follow Criteria Language Syntax.

Tip

To see Criteria Property Editors in action, see the following module in the Feature Center demo: Property Editors | Criteria Properties.

Mark a Property as a Criteria Property

A criteria property is a string property in a business object that stores a filter expression. Apply CriteriaOptionsAttribute to such a property. XAF uses this attribute to generate an appropriate Property Editor.

ASP.NET Core Blazor

XAF’s ASP.NET Core Blazor UI supports multiple Property Editors that work with filter criteria.

In ASP.NET Core Blazor, BlazorPropertyEditorBase.ComponentModel returns an IComponentModel descendant that wraps properties and events of a corresponding ASP.NET Core Blazor Editor.

PopupCriteriaPropertyEditor

Component Model: DevExpress.ExpressApp.Blazor.Components.Models.DxFilterBuilderModel.

Component: DxFilterBuilder shipped with the DevExpress ASP.NET Core Blazor Library.

A Property Editor for string properties that store filter criteria. It creates a pop-up Detail View with a CriteriaPropertyEditor item.

To access the CriteriaPropertyEditor in the pop-up Detail View, implement a View Controller for the DevExpress.ExpressApp.Editors.CriteriaProvider type. For more information on how to access a Property Editor in a Detail View, refer to the following help topic: Access the Settings of a Property Editor in a Detail View.

CriteriaPropertyEditor

Component model: DevExpress.ExpressApp.Blazor.Components.Models.DxFilterBuilderModel.

Component: DxFilterBuilder shipped with the DevExpress ASP.NET Core Blazor Library.

CriteriaPropertyEditor supports expression validation. Knowledge of Criteria Language Syntax is required to work with this Property Editor.

Note

CriteriaPropertyEditor only supports Conditional Appearance rules that hide or disable editors.

FilterPropertyEditor

Component Model: DevExpress.ExpressApp.Blazor.Components.Models.FilterEditorModel.

Component: DevExpress.ExpressApp.Blazor.Components.FilterEditor. This internal component initializes and configures the JavaScript Filter Editor. It does not have public API.

The default Property Editor with tree-like and text-based criteria construction.

PopupFilterPropertyEditor

Component Model: DevExpress.ExpressApp.Blazor.Components.Models.DxTextBoxModel.

Component: DxTextBox shipped with the DevExpress ASP.NET Core Blazor Library.

A Property Editor for string properties that store filter criteria. It creates a pop-up Detail View with a FilterPropertyEditor item.

To access the FilterPropertyEditor in the pop-up Detail View, implement a View Controller for the DevExpress.ExpressApp.Editors.CriteriaProvider type. For more information on how to access a Property Editor in a Detail View, refer to the following help topic: Access the Settings of a Property Editor in a Detail View.

Customization in Filter Builder

CriteriaPropertyEditor.CustomizeFieldVisibility

Use this event to hide or show fields in the Filter Builder field list.

CriteriaPropertyEditor.CustomizeField

Use this event to customize a field caption and value template.

CriteriaPropertyEditor.CustomizeFieldEditSettings

Use this event to edit field settings.

DxFilterBuilderModel.CustomizeOperators

Use this event to customize the list of available operators.

The following example customizes the PopupCriteriaPropertyEditor in an EF Core application. FilteringCriterion is a sample business class, not a framework type.

SolutionName.Blazor.Server/Controllers/CriteriaPropertyEditorCustomizationController.cs

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Blazor.Components.Models;
using DevExpress.ExpressApp.Blazor.Editors;
using SolutionName.Module.BusinessObjects;

namespace SolutionName.Blazor.Server.Controllers;

public class PopupCriteriaPropertyEditorCustomizationController :
    ObjectViewController<DetailView, FilteringCriterion> {

    protected override void OnActivated() {
        base.OnActivated();

        // Targets both CriteriaPropertyEditor and PopupCriteriaPropertyEditor,
        // because PopupCriteriaPropertyEditor inherits from CriteriaPropertyEditor.
        View.CustomizeViewItemControl<CriteriaPropertyEditor>(this, editor => {
            if (editor.Id != nameof(FilteringCriterion.Criterion)) {
                return;
            }

            editor.CustomizeFieldVisibility += (s, e) => {
                if (e.MemberInfo.Owner.KeyMember == e.MemberInfo) {
                    e.Visible = false;
                }
            };

            editor.CustomizeField += (s, e) => {
                if (e.MemberInfo.Name == nameof(DemoTask.AssignedTo)) {
                    e.FieldModel.Caption = "Assigned to";
                    e.FieldModel.ValueDisplayTemplate = context => builder =>
                        builder.AddContent(0, $"Assigned to {context.Value}");
                }
            };

            editor.CustomizeFieldEditSettings += (s, e) => {
                if (e.MemberInfo.Name == nameof(DemoTask.AssignedTo) &&
                    e.EditSettings is DxComboBoxSettingsModel comboBoxSettings) {
                    comboBoxSettings.NullText = "Select an employee";
                }
            };

            editor.ComponentModel.CustomizeOperators += args => {
                // Customize args.Operators here.
            };
        }, nameof(FilteringCriterion.Criterion));
    }
}

SolutionName.Module/BusinessObjects/FilteringCriterion.cs

using DevExpress.ExpressApp.DC;
using DevExpress.ExpressApp.Editors;
using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl.EF;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations.Schema;

namespace SolutionName.Module.BusinessObjects;

[DefaultClassOptions]
public class FilteringCriterion : BaseObject {
    [Browsable(false)]
    public virtual string ObjectTypeName {
        get => ObjectType?.FullName ?? string.Empty;
        set {
            var typeInfo = DevExpress.ExpressApp.XafTypesInfo.Instance.FindTypeInfo(value);
            ObjectType = typeInfo?.Type;
        }
    }

    private Type objectType;

    [NotMapped, ImmediatePostData]
    public Type ObjectType {
        get => objectType;
        set {
            if (objectType == value) return;
            objectType = value;
            Criterion = string.Empty;
        }
    }

    [CriteriaOptions(nameof(ObjectType))]
    [FieldSize(FieldSizeAttribute.Unlimited)]
    [EditorAlias(EditorAliases.PopupCriteriaPropertyEditor)]
    public virtual string Criterion { get; set; }
}

Windows Forms

XAF’s Windows Forms UI supports multiple Property Editors that work with filter criteria.

Each Windows Forms Property Editor is available in two forms:

• A standalone control (displays property value in a Detail View)
• A repository item (displays property value in a List Editor that supports in-place editing)

AdvancedCriteriaPropertyEditor (Default)

Control: DevExpress.DataAccess.UI.FilterEditorControl.

Repository Item: None.

The default Property Editor with tree-like and text-based criteria construction.

To display AdvancedCriteriaPropertyEditor for criteria properties, set the static UseAdvancedFilterEditorControl property value to True or Default.

The following example activates AdvancedCriteriaPropertyEditor and accesses its control in a View Controller. FilteringCriterion is a sample business class, not a framework type.

SolutionName.Win/Program.cs

// Activate AdvancedCriteriaPropertyEditor application-wide.
DevExpress.XtraEditors.WindowsFormsSettings.UseAdvancedFilterEditorControl =
    DevExpress.Utils.DefaultBoolean.True;

SolutionName.Win/Controllers/AdvancedCriteriaEditorController.cs

using DevExpress.DataAccess.UI.FilterEditor;
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Editors;
using DevExpress.ExpressApp.Win.Editors;

namespace SolutionName.Win.Controllers;

public class AdvancedCriteriaEditorController :
    ObjectViewController<DetailView, FilteringCriterion> {

    protected override void OnActivated() {
        base.OnActivated();
        View.CustomizeViewItemControl<CriteriaPropertyEditor>(this, editor => {
            if (editor.Control is FilterEditorControl filterEditor) {
                // Customize FilterEditor here.
            }
        });
    }
}

SolutionName.Module/BusinessObjects/FilteringCriterion.cs

using DevExpress.ExpressApp.DC;
using DevExpress.ExpressApp.Editors;
using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl.EF;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations.Schema;

namespace SolutionName.Module.BusinessObjects;

[DefaultClassOptions]
public class FilteringCriterion : BaseObject {
    [Browsable(false)]
    public virtual string ObjectTypeName {
        get => ObjectType?.FullName ?? string.Empty;
        set {
            var typeInfo = DevExpress.ExpressApp.XafTypesInfo.Instance.FindTypeInfo(value);
            ObjectType = typeInfo?.Type;
        }
    }

    private Type objectType;

    [NotMapped, ImmediatePostData]
    public Type ObjectType {
        get => objectType;
        set {
            if (objectType == value) return;
            objectType = value;
            Criterion = string.Empty;
        }
    }

    [CriteriaOptions(nameof(ObjectType))]
    [FieldSize(FieldSizeAttribute.Unlimited)]
    [EditorAlias(EditorAliases.CriteriaPropertyEditor)]
    public virtual string Criterion { get; set; }
}

CriteriaPropertyEditor

Control: DevExpress.XtraFilterEditor.FilterEditorControl.

Repository Item: None.

This Property Editor displays a Filter Builder control with two tabs. The Filter tab allows users to construct conditions through an easy-to-use UI. The Text tab allows users to type the criteria.

To display CriteriaPropertyEditor for criteria properties, set the static UseAdvancedFilterEditorControl property value to False.

PopupCriteriaPropertyEditor

Control: DevExpress.ExpressApp.Win.Editors.PopupCriteriaEdit.

Repository Item: RepositoryItemPopupCriteriaEdit, a descendant of the RepositoryItemButtonEdit repository item from the XtraEditors Library.

Use this Property Editor to display a CriteriaPropertyEditor in a separate window and thus save space on the Detail form.

To use this Property Editor, assign it to the PropertyEditorType property of the BOModel | <Class> | OwnMembers | <Member> node or Views | <DetailView> | Items | <PropertyEditor> node.

PopupCriteriaPropertyEditor creates a pop-up Detail View with a CriteriaPropertyEditor item. The internal component used (DevExpress.DataAccess.UI.FilterEditorControl or DevExpress.XtraFilterEditor.FilterEditorControl) depends on the static UseAdvancedFilterEditorControl property value. To access the CriteriaPropertyEditor.Control property, implement a View Controller for the DevExpress.ExpressApp.Editors.CriteriaProvider Detail View. Use the approach described in the following help topic: Access the Settings of a Property Editor in a Detail View.

Examples

• Criteria Properties in XPO
• Criteria Properties in EF Core
• How to use Criteria Property Editors

Text Input in Criteria Property Editors

The tree-like criteria construction in Criteria Property Editors does not support advanced syntax elements, such as:

• Function Criteria Operators
• Object Parameters
• Current Object Parameter in XPO applications
• Free Joins

For example, the following expression uses the IsYearToDate function operator to return tasks where DueDate falls between January 1 of the current year and today. You cannot create this expression in the visual tree editor; you need to enter it in the text input field:

IsYearToDate([DueDate])

XAF validates the expression on the server side and applies the filter.