A Dynamic Menu Data Source is a list of key-value pairs that your application supplies at run time, and that the Rule Editor shows as a menu, as if the pairs were the members of an enumeration. Use one when the list is not fixed, such as the rows of a lookup table, and you do not want to recompile the application every time a row changes. Rule authors pick a name from the menu, and the rule stores the matching ID or key.
You can define as many data sources as you need, and use them as the values of fields, as the return values of in-rule methods, and as parameters of in-rule methods and rule actions. They also work for the items of collections of integers or strings.
This is also the way to work around some unsupported data types: a dictionary, a list of pairs, or a Guid is easy to present as a data source with a name for the rule author and an ID or a key for the rule.
How a Data Source Works
A data source has three parts:
- A method that returns the items. It must be public and parameterless, and it must return a collection of
DataSourceItem objects, such as List<DataSourceItem>. It can be static, or an instance method of a class that has a public parameterless constructor. Any class can declare it, including the source object.
- A name. The
Data attribute on the source object class (or interface) gives the method a unique name. You can declare as many as you need, and a derived class inherits those of its base.
- The members that use it. A field, a method's return value, or a parameter of a method or an action names the data source in its
DataSourceName property, in the Field, Return, or Parameter attribute.
Each DataSourceItem has a Name, which is what the rule author sees, and an identity that the rule stores:
- an integer
ID, for a data source used by members of integer types (byte, sbyte, short, ushort, int, uint, long, ulong, and their nullable forms), or
- a string
Key, for a data source used by string members.
A member of any other type ignores its DataSourceName. Decimal and floating-point types, dates, and Booleans cannot use a data source.
Example
Imagine that your organization has a lookup table, Role, with the IDs and names of user roles that rules should use, and that its rows change from time to time. Declare a class with a method that reads them:
using System.Collections.Generic;
using CodeEffects.Rule.Editor.Client;
public class Helper
{
// It can be an instance method as well, if its class has a public
// parameterless constructor
public static List<DataSourceItem> GetRoles()
{
// Hard-coded here; in your application it comes from the Role table
return new List<DataSourceItem>
{
new DataSourceItem(1, "Management"),
new DataSourceItem(2, "Network Admins"),
new DataSourceItem(3, "Developers"),
new DataSourceItem(4, "Designers")
};
}
// A data source of strings: the identity is a key
public static List<DataSourceItem> GetCountries()
{
return new List<DataSourceItem>
{
new DataSourceItem("US", "United States"),
new DataSourceItem("CA", "Canada"),
new DataSourceItem("MX", "Mexico")
};
}
}
The source object names both methods once, and then uses them where they are needed:
using CodeEffects.Rule.Common.Attributes;
[Data("Roles", typeof(Helper), "GetRoles")]
[Data("Countries", typeof(Helper), "GetCountries")]
public class User
{
public enum Status { Warning, Success, Error }
[Field(DisplayName = "Full Name", Max = 20)]
public string FullName { get; set; }
// An integer member: the stored value is a role ID
[Field(DisplayName = "Role", DataSourceName = "Roles", AllowCalculations = false, IncludeInCalculations = false)]
public int RoleID { get; set; }
// A string member: the stored value is a country key
[Field(DisplayName = "Country", DataSourceName = "Countries")]
public string CountryCode { get; set; }
// The return value of an in-rule method
[Method(DisplayName = "Default Role")]
[return: Return(DataSourceName = "Roles")]
public int DefaultRole() => 3;
// The parameter of a rule action
[Action(DisplayName = "Assign Role")]
public void AssignRole([Parameter(DataSourceName = "Roles")] int roleId) { /* ... */ }
}
The attribute on the class lets you name each data source once and use it for any number of fields, methods, and parameters of the source object. Set the class as the source object of the Rule Editor, and the roles appear as the values of Role:

A data source of strings works the same way, with the keys of the items behind the names:

The rule shows the name that the author picked:

...but the Rule XML holds the ID, and the Evaluator compares it with the value of the member during evaluation. For a string data source the XML holds the key:
<condition type="equal">
<property name="RoleID" />
<value type="System.Int32">3</value>
</condition>
<condition type="equal" stringComparison="OrdinalIgnoreCase">
<property name="CountryCode" />
<value>CA</value>
</condition>
Because the XML holds the ID and not the name, you can rename a role in the lookup table, and every rule that uses it shows the new name the next time the rule is loaded.
When the Items Change
The editor asks the data source method for its items on the server, when the page is loaded. A rule author who has the page open sees the new items after the page is loaded again, which is not an issue if the data does not change often.
IMPORTANT: Code Effects 6 also supported data sources declared as client-side JavaScript functions. They are not supported in v7, and the Location property of the Data attribute is gone. A source object that still sets it does not compile. A v6 source file that declares a client data source still loads, but the data source is read as a name with no method, and its menu is empty. Replace it with a server-side method as shown above.
When a Value No Longer Exists
If a rule uses an ID or a key that is no longer in the data, the Evaluator still evaluates the rule as if the value existed, and the condition is false, because the engine cannot tell whether the stored value is still valid.
When such a rule is loaded into the Rule Editor, the Rule Area marks the value with a red background. The rule is invalid until its author replaces the value:

Data Sources in an Adaptive Source
With an Adaptive Source, the source object does not carry the attributes. You describe the data source with a DataSource object, add it to the DataSources of the source, and name it in the DataSourceName of the Settings of the field, return value, or parameter that uses it:
using System.Collections.Generic;
using CodeEffects.Rule.Common.Models;
using CodeEffects.Rule.Editor.Client;
using CodeEffects.Rule.Editor.Models;
var source = new Source
{
DataSources = new List<DataSource>
{
// The editor calls Helper.GetRoles() for the items
new DataSource { Name = "Roles", Type = typeof(Helper), Method = "GetRoles" }
},
Fields = new List<Field>
{
new Field
{
Value = "RoleID",
DisplayName = "Role",
DataType = DataType.Numeric,
Settings = new Settings { DataSourceName = "Roles" }
}
}
};
For a rule editor that runs outside of the Rule Repository, a source provider can instead return the items in the Items property of the DataSource that its GetDataSource() method returns.
Data Sources in the Rule Repository
The Rule Repository stores a data source as a bare declaration, the name and the method, in the Source XML of a source version. It never stores the items, and it calls the method for them every time it needs them, in its own editor and in the source tree. This is why a change to the items of a data source does not create a new source version: only the name of a data source, and the members that use it, are part of a version.
Customizing the Items at Run Time
A data source method cannot take parameters, but the items it returns can depend on a value that you set in the class that declares it. Passing Parameters to Dynamic Menu Data Sources describes how to give the Rule Editor a delegate to such a method instead of naming the method in the Data attribute.