Use Metadata to Customize Business Classes Dynamically
- 8 minutes to read
This topic describes how to alter an existing XPO or Entity Framework (EF) business model without modifying its code. In the Model Editor, end-users (application administrators) can add custom fields to business objects without recompiling their application. XAF application developers can also add custom fields to objects implemented in external libraries. Custom fields can be calculated (an expression used to compute the field value should be provided), or persistent (a new column is added to a database table automatically).
Custom fields declared in the Application Model are automatically collected and registered within the Types Info subsystem. Pay attention at the following peculiarities of the runtime custom fields usage.
- Generally, persistent fields should be added at design time only. It is not good practice to allow end-users to alter the database schema - allow this only as a last resort measure.
- It is strongly recommended to restart the application after a custom field is deleted at runtime.
- Custom fields added to the user differences (Model.User.xafml file) are not supported when the ThreadSafeDataLayer Data Access Layer is in use. In XAF, this Data Layer is enabled when you instantiate an XPObjectSpaceProvider using the constructor that takes the threadSafe parameter and set this parameter to true. The SecuredObjectSpaceProvider used in Integrated Mode of the Security System uses the ThreadSafeDataLayer by default, when the threadSafe parameter is not specified. As a workaround, copy a custom field to the administrator’s differences (Model.xafml) by using the Model Merge feature.
- Calculated fields are always evaluated on the client side. So, sorting, grouping, filtering and summary calculation do not work for calculated columns in Server and InstantFeedback modes. If you use XPO and create a new calculated field by one of the approaches described in this topic, the PersistentAliasAttribute is automatically added to this newly created field, thus, these operations are available for the corresponding column.
- You cannot add custom persistent fields to the EF data model.
- You cannot add non-calculated fields to non-persistent classes.
Note that if you change a Mobile Application Model, you need to rebuild an application.
This topic includes the following sections:
- Add a Custom Calculated Field in the Model Editor
- Add a Custom Persistent Field in the Model Editor in Visual Studio
- Add a Custom Persistent Field in the Model Editor at Runtime
- Add Custom Fields in Code
- Access Custom Fields in Code
- Create Associations in Code
Note
To see custom fields in action, refer to the Custom Fields section in the Feature Center demo installed with XAF. The Feature Center demo is installed in %PUBLIC%\Documents\DevExpress Demos 19.1\Components\eXpressApp Framework\FeatureCenter by default. The ASP.NET version of this demo is available online at https://demos.devexpress.com/XAF/FeatureCenter/.
Add a Custom Calculated Field in the Model Editor
To add a custom calculated field, invoke the Model Editor at design time or in a WinForms application at runtime, or use the standalone Model Editor tool (e.g., to add a field to an ASP.NET application). Then follow the steps below.
Right-click the BOModel | <Class> | OwnMembers node and choose Add… | Member.
- Focus the new member node. In the property grid to the right, specify the IModelMember.Name and IModelMember.Type values.
- Pass the expression to be used to compute the field value to the IModelMember.Expression property. You can click the ellipsis button located to the right of the property value to invoke the Expression Editor dialog. In this editor, you can select functions, operators and operands using editor controls.
- If you are creating a custom field at runtime, specify the IModelCommonMemberViewItem.PropertyEditorType value. Choose an appropriate Property Editor from the combo box. At design time, the PropertyEditorType value is optional - an appropriate Property Editor is determined automatically. Note that platform-specific Property Editors are not available in the common module.
- Save your changes and restart the Model Editor.
- Create a Detail View item or List View column mapped to the newly added custom field (see Add an Editor to a Detail View and Change Field Layout and Visibility in a List View).
The image below illustrates the member node settings described above.
Add a Custom Persistent Field in the Model Editor in Visual Studio
Creating a custom persistent field is very similar to creating the calculated field described in the previous section. The only difference is that you should set the IModelMember.IsCalculated property to false instead of specifying the Expression value.
Note
The following combination of features is not supported when used together.
- SecuredObjectSpaceProvider or XPObjectSpaceProvider created using the constructor with the threadSafe parameter set to true (this parameter enables the ThreadSafeDataLayer).
- Application-wide model differences are stored in the database using the XafApplication.CreateCustomModelDifferenceStore event (you can still store user-specific differences in the database using the XafApplication.CreateCustomUserModelDifferenceStore event).
- Custom Persistent Fields declared in the application-level model differences.
In this configuration, your application loads information on custom persistent fields from the database and then updates the database schema. However, a thread-safe data layer does not support altering the data model after the database connection is established.
Add a Custom Persistent Field in the Model Editor at Runtime
By default, the creation of custom persistent fields is allowed at design time only (the IsCalculated value is not editable). To allow end-users to add custom persistent fields in the Model Editor at runtime, set the static ModelMemberReadOnlyCalculator.AllowPersistentCustomProperties property to true. The created field should then be merged to the application-level model differences (see Model Merge Tool). To allow updating of the database schema after a field is added at runtime, set the XafApplication.DatabaseUpdateMode property to DatabaseUpdateMode.UpdateDatabaseAlways. Also, consider the note about ThreadSafeDataLayer from the previous section. A column mapped to the current field will automatically be added to the database table.
Important
- If you store the Application Model Differences in the database, you should additionally override the XafApplication.OnSetupComplete protected virtual method and call the XafApplication.CheckCompatibilityCore method from the overridden method.
Middle Tier Security - WCF Service, Workflow Server Service, or any other appllication that creates and configures a ServerApplication/XafApplication cannot access custom fields added in the client XAF application project (in code or in XAFML), or by customizing the application model at runtime. You should add a custom field in a common module and reference it in all applications where you are going to use it.
Add Custom Fields in Code
To extend an existing business class from an external class library, you can add a custom field in code. Edit the Module.cs (Module.vb) file and override the ModuleBase.CustomizeTypesInfo method. The code below demonstrates how to add a persistent field (PersistentField1), a persistent field with the ImmediatePostDataAttribute applied (PersistentField2) and a calculated field (CalculatedField).
using DevExpress.ExpressApp.DC;
using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl;
// ...
public override void CustomizeTypesInfo(ITypesInfo typesInfo) {
base.CustomizeTypesInfo(typesInfo);
TypeInfo personTypeInfo = typesInfo.FindTypeInfo(typeof(Person)) as TypeInfo;
if (personTypeInfo != null) {
personTypeInfo.CreateMember("PersistentField1", typeof(int));
personTypeInfo.CreateMember("PersistentField2", typeof(int)).AddAttribute(new ImmediatePostDataAttribute());
personTypeInfo.CreateMember("CalculatedField", typeof(int), "PersistentField1 + PersistentField2");
}
}
Access a Custom Field in Code
The following snippet illustrates how to access a custom field in a Controller context using the IMemberInfo.GetValue method.
Person person = this.View.CurrentObject as Person;
ITypeInfo personInfo = this.Application.TypesInfo.FindTypeInfo(typeof(Person));
int? value = personInfo.FindMember("CalculatedField").GetValue(person) as int?;
The following snippet illustrates how to access a custom field in a Controller context from the PropertyEditor.ControlValue property.
ViewItem viewItem = ((DetailView)View).FindItem("CalculatedField");
decimal? value = ((PropertyEditor)viewItem).ControlValue as decimal?;
Create Associations in Code
The following snippet illustrates how to declare an association between two class’ properties when you have no access to these classes code and cannot apply the AssociationAttribute directly.
public override void CustomizeTypesInfo(ITypesInfo typesInfo) {
base.CustomizeTypesInfo(typesInfo);
ITypeInfo typeInfo1 = typesInfo.FindTypeInfo(typeof(DomainObject1));
ITypeInfo typeInfo2 = typesInfo.FindTypeInfo(typeof(DomainObject2));
IMemberInfo memberInfo1 = typeInfo1.FindMember("Object2");
IMemberInfo memberInfo2 = typeInfo2.FindMember("Object1s");
if(memberInfo1 == null) {
memberInfo1 = typeInfo1.CreateMember("Object2", typeof(DomainObject2));
memberInfo1.AddAttribute(new DevExpress.Xpo.AssociationAttribute("A", typeof(DomainObject2)), true);
}
if(memberInfo2 == null) {
memberInfo2 = typeInfo2.CreateMember("Object1s", typeof(XPCollection<DomainObject1>));
memberInfo2.AddAttribute(new DevExpress.Xpo.AssociationAttribute("A", typeof(DomainObject1)), true);
memberInfo2.AddAttribute(new DevExpress.Xpo.AggregatedAttribute(), true);
}
((XafMemberInfo)memberInfo1).Refresh();
((XafMemberInfo)memberInfo2).Refresh();
}
As you can see in the code above, the IMemberInfo.AddAttribute method’s second parameter is true. In this case, Types Info does not reload information from XPDictionary immediately After adding all required attributes, call the XafMemberInfo.Refresh method for each updated member. Alternatively, you can call XafTypesInfo.RefreshInfo for each type containing updated members:
public override void CustomizeTypesInfo(ITypesInfo typesInfo) {
// ...
typesInfo.RefreshInfo(typeof(DomainObject1));
typesInfo.RefreshInfo(typeof(DomainObject2));
}
Tip
To access the XPDictionary directly, use the XpoTypesInfoHelper.GetXpoTypeInfoSource method.