Our What's New in v24.2 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.
When defining a Validation Rule, you can use it to validate a collection property. This topic describes collection validation specifics. For general information on the contextual validation concept, refer to the Validation Rules topic.
Built-in validation rules can be applied to a collection property involved in a relationship (marked with the Association attribute). In this instance, a validation rule is evaluated for all the collection elements rather than for the master object, ensuring that each collection element is valid. So, when specifying parameters of a rule applied to a collection property, you need to specify them in the context of a collection element. For instance, the rule’s RuleBaseAttribute.TargetCriteria should not contain references to the master object’s properties and should only include properties of the collection element. Additionally, you will need to specify a collection element’s property that must be checked via the TargetPropertyName named parameter. In the following code snippet, RuleUniqueValue is applied to the Collection property, to ensure that all the collection elements’ StringProperty property values are unique:
When applied to collection properties, certain validation rules, such as the RuleRange and RuleValueComparison rules, can use aggregate functions. The attributes corresponding to these rules expose the TargetCollectionAggregate property that specifies the aggregate function. When a value is assigned to this property (by setting the corresponding named parameter or via the Application Model), the validation rule does not check the collection property’s elements. Instead, it checks the specified aggregate function. For example, the following code snippet illustrates the RuleValueComparison rule applied to the Collection property. In this example, the rule ensures that the sum of the collection elements’ IntegerProperty property values does not equal zero:
ImportsDevExpress.Data.Filtering'...
<DefaultClassOptions> _
PublicClass AggregateFunction
Inherits BaseObject
PublicSubNew(ByVal session As Session)
MyBase.New(session)
EndSub
<RuleValueComparison("RuleWithAggregateFunction", _
DefaultContexts.Save, ValueComparisonType.NotEquals, 0, _
TargetPropertyName:=NameOf(AggregateFunctionCollectionElement.IntegerProperty), _
TargetCollectionAggregate:=Aggregate.Sum), _
Association("AggregateFunction-AggregateFunctionCollectionElements"), _
Aggregated()> _
PublicReadOnlyProperty Collection() As XPCollection( _
Of AggregateFunctionCollectionElement)
GetReturn GetCollection( _
Of AggregateFunctionCollectionElement)(NameOf(Collection))
EndGetEndPropertyEndClassPublicClass AggregateFunctionCollectionElement
Inherits BaseObject
Private owner_Renamed As AggregateFunction
Private integerProperty_Renamed AsIntegerPublicSubNew(ByVal session As Session)
MyBase.New(session)
EndSubPublicProperty IntegerProperty() AsIntegerGetReturn integerProperty_Renamed
EndGetSet(ByVal value AsInteger)
integerProperty_Renamed = value
EndSetEndProperty
<Association("AggregateFunction-AggregateFunctionCollectionElements")> _
PublicProperty Owner() As AggregateFunction
GetReturn owner_Renamed
EndGetSet(ByVal value As AggregateFunction)
owner_Renamed = value
EndSetEndPropertyEndClass
If the RuleBaseAttribute.TargetCriteria property has been specified, then the demonstrated rule would calculate the sum over the suitable elements only.
The following aggregate functions are available:
Aggregate Function
Description
Avg
Evaluates the average of the collection elements’ property values. Requires the TargetPropertyName to be specified.
Count
Evaluates the number of elements contained in the collection. Does not require the TargetPropertyName to be specified.
Exists
Evaluates whether a collection element exists, which has a valid TargetPropertyName property’s value (the validity is defined by the actual validation rule).
Max
Evaluates the maximum of the collection elements’ property values. Requires the TargetPropertyName to be specified.
Min
Evaluates the minimum of the collection elements’ property values. Requires the TargetPropertyName to be specified.
Sum
Evaluates the sum of the collection elements’ property values. Requires the TargetPropertyName to be specified.
Note
RuleValueComparison is not checked if the collection property is empty. Use the RuleRequiredFieldAttribute instead.
#Aggregate Function Values in Custom Message Templates
When customizing validation message templates, you can include the aggregate function value in the template. For this purpose, use the {AggregatedTargetValue} parameter. The following code snippet illustrates this:
usingDevExpress.Data.Filtering;
usingSystem.Collections.ObjectModel;
//...
[DefaultClassOptions]
publicclassMessageTemplate : BaseObject {
[RuleRange("RuleWithCustomMessageTemplate", DefaultContexts.Save, 0, 50,
TargetPropertyName = nameof(MessageTemplateCollectionElement.DecimalProperty), TargetCollectionAggregate = Aggregate.Sum,
CustomMessageTemplate = "The sum of the {TargetPropertyName} values must be " +
"within {MinimumValue} and {MaximumValue} range. The current value is" +
" {AggregatedTargetValue}")]
publicvirtualIList<MessageTemplateCollectionElement> Collection { get; set; } = new ObservableCollection<MessageTemplateCollectionElement>();
}
publicclassMessageTemplateCollectionElement : BaseObject {
publicvirtualdecimal DecimalProperty { get; set; }
publicvirtual MessageTemplate Owner { get; set; }
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
usingDevExpress.Data.Filtering;
//...
[DefaultClassOptions]
publicclassMessageTemplate : BaseObject {
publicMessageTemplate(Session session) : base(session) { }
[RuleRange("RuleWithCustomMessageTemplate", DefaultContexts.Save, 0, 50,
TargetPropertyName = nameof(MessageTemplateCollectionElement.DecimalProperty), TargetCollectionAggregate = Aggregate.Sum,
CustomMessageTemplate = "The sum of the {TargetPropertyName} values must be " +
"within {MinimumValue} and {MaximumValue} range. The current value is" +
" {AggregatedTargetValue}")]
[Association("MessageTemplate-MessageTemplateCollectionElements"), Aggregated]
public XPCollection<MessageTemplateCollectionElement> Collection {
get { return GetCollection<MessageTemplateCollectionElement>(nameof(Collection)); }
}
}
publicclassMessageTemplateCollectionElement : BaseObject {
privatedecimal decimalProperty;
private MessageTemplate owner;
publicMessageTemplateCollectionElement(Session session) : base(session) { }
publicdecimal DecimalProperty {
get { return decimalProperty; }
set { decimalProperty = value; }
}
[Association("MessageTemplate-MessageTemplateCollectionElements")]
public MessageTemplate Owner {
get { return owner; }
set { SetPropertyValue(nameof(Owner), ref owner, value); }
}
}
ImportsDevExpress.Data.Filtering'...
<DefaultClassOptions> _
PublicClass MessageTemplate
Inherits BaseObject
PublicSubNew(ByVal session As Session)
MyBase.New(session)
EndSub
<RuleRange("RuleWithCustomMessageTemplate", DefaultContexts.Save, _
0, 50, TargetPropertyName:=NameOf(MessageTemplateCollectionElement.DecimalProperty), _
TargetCollectionAggregate:=Aggregate.Sum, _
CustomMessageTemplate:= _
"The sum of the {TargetPropertyName} values must be " & _
"within {MinimumValue} and {MaximumValue} range. The current value is" & _
" {AggregatedTargetValue}"), _
Association("MessageTemplate-MessageTemplateCollectionElements"), Aggregated()> _
PublicReadOnlyProperty Collection() As XPCollection( _
Of MessageTemplateCollectionElement)
GetReturn GetCollection( _
Of MessageTemplateCollectionElement)(NameOf(Collection))
EndGetEndPropertyEndClassPublicClass MessageTemplateCollectionElement
Inherits BaseObject
Private decimalProperty_Renamed AsDecimalPrivate owner_Renamed As MessageTemplate
PublicSubNew(ByVal session As Session)
MyBase.New(session)
EndSubPublicProperty DecimalProperty() AsDecimalGetReturn decimalProperty_Renamed
EndGetSet(ByVal value AsDecimal)
decimalProperty_Renamed = value
EndSetEndProperty
<Association("MessageTemplate-MessageTemplateCollectionElements")> _
PublicProperty Owner() As MessageTemplate
GetReturn owner_Renamed
EndGetSet(ByVal value As MessageTemplate)
SetPropertyValue(NameOf(Owner), owner_Renamed, value)
EndSetEndPropertyEndClass