XafApplication.CheckCompatibilityType Property

Specifies how database and application compatibility is checked.

Namespace : DevExpress.ExpressApp

Assembly : DevExpress.ExpressApp.v25.2.dll

NuGet Package : DevExpress.ExpressApp

Declaration

• C#
• VB.NET

[DefaultValue(CheckCompatibilityType.ModuleInfo)]
public CheckCompatibilityType CheckCompatibilityType { get; set; }

<DefaultValue(CheckCompatibilityType.ModuleInfo)>
Public Property CheckCompatibilityType As CheckCompatibilityType

Property Value

A value that specifies how database and application compatibility is checked.

|

Available values:

XAF ensures that the database schema matches the business model: all required tables, columns and databases should exist.

| | ModuleInfo |

XAF ensures that the database version matches the application version. The module versions stored in the ModuleInfo table are compared with their actual assembly versions.

|

Remarks

The XAF application template is designed to create a database when the application is run for the first time and to update it as the application’s version increases. Use the CheckCompatibilityType property to specify how the database and application compatibility is checked.

You can use the following properties to specify the compatibility type individually for each Object Space Provider, for instance, if you use multiple databases:

• IObjectSpaceProvider.CheckCompatibilityType
• EFCoreObjectSpaceProvider.CheckCompatibilityType
• XPObjectSpaceProvider.CheckCompatibilityType

DatabaseSchema Type

When the CheckCompatibilityType property is set to DatabaseSchema, XAF ensures that the database schema matches the business model. In particular XAF checks that:

• The database exists
• All required tables exist
• All required columns exist

The DatabaseVersionMismatch event occurs if any of these checks fails. The DevExpress Template Kit handles this event in new Blazor, Web API, and WinForms projects to keep the application and database versions synchronized as follows:

• If the database does not exist, XAF creates the database and required tables.
• If the database exists, but it is empty, XAF creates the tables.
• If a column does not exist, XAF adds it to the table.

The Template Kit sets the CheckCompatibilityType property to DatabaseSchema in new applications:

• Blazor
• WinForms
• WebApi
• MiddleTier

// File: SolutionName.Blazor.Server\BlazorApplication.cs
public class SolutionNameBlazorApplication : BlazorApplication {
    public SolutionNameBlazorApplication() {
        CheckCompatibilityType = DevExpress.ExpressApp.CheckCompatibilityType.DatabaseSchema;
        // ...

// File: SolutionName.Win\WinApplication.cs
public class SolutionNameWindowsFormsApplication : WinApplication {
    public SolutionNameWindowsFormsApplication() {
        CheckCompatibilityType = DevExpress.ExpressApp.CheckCompatibilityType.DatabaseSchema;
        // ...

// File: SolutionName.WebApi\Startup.cs
builder.AddBuildStep(application => {
    application.CheckCompatibilityType = DevExpress.ExpressApp.CheckCompatibilityType.DatabaseSchema;
    // ...

// File: SolutionName.MiddleTier\Startup.cs
builder.AddBuildStep(application => {
    application.CheckCompatibilityType = DevExpress.ExpressApp.CheckCompatibilityType.DatabaseSchema;
    // ...

ModuleInfo Type

When the CheckCompatibilityType property is set to ModuleInfo, XAF ensures that the database version matches the application version. In this mode, XAF creates a ModuleInfo table in the database to check the compatibility of an application and its database. This table stores information on the module versions used in the application. When XAF checks compatibility of the database and application, versions stored in the ModuleInfo table are compared with actual module versions. The DatabaseVersionMismatch event occurs in case of a mismatch.

If your application uses Entity Framework Core ORM, register the ModuleInfo type in DbContext.

• SolutionName.Module\BusinessObjects\SolutionNameDbContext.cs

public class SolutionNameEFCoreDbContext : DbContext {
    public DbSet<ModuleInfo> ModulesInfo { get; set; }
    // ...

Each module’s default version value is “1.0.*“ (specified by the AssemblyVersion attribute in the Properties\AssemblyInfo.cs file). The asterisk in the version number indicates that build and revision numbers are incremented automatically. XAF updates the version number with each new build. As a result, module versions may become unsynchronized if you build Windows Forms or ASP.NET Core Blazor applications separately (for example, when you create a ClickOnce installation or deploy to IIS).

This mode is more complicated compared to DatabaseSchema, but it helps you ensure both business logic compatibility and data model compatibility.

Compatibility Check Steps

The mechanism XAF uses to check application and database version compatibility, and update the database, consists of the following steps:

1. Compare the application name in the database with actual application name.
   If they are not equal, the following error message appears: Database is designed for the ‘A’ application while you are running the ‘B’ application.
2. Compare module versions in the database with actual module versions.
   If the database version is greater than the application version, the following error message appears: The database version is greater than the application version. The application needs to be updated.
3. Call the UpdateDatabaseBeforeUpdateSchema() method.
4. Collect all persistent classes. Update database schema.
5. Call the UpdateDatabaseAfterUpdateSchema() method.
6. Set new module versions in the database.

You can override UpdateDatabaseBeforeUpdateSchema() and UpdateDatabaseAfterUpdateSchema() methods to modify module database tables, both before and after updating the database schema. For instance, this can be necessary when applying the Security System in the application. A user with administrative rights should be added to a database using the UpdateDatabaseAfterUpdateSchema method. For details, refer to the following help topics:

• Using the Security System
• Supply Initial Data

You can use the ModuleUpdater to implement complex updating logic that takes into account the differences between application versions.

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the CheckCompatibilityType 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.

• C#
• VB.NET

xaf-how-to-change-connection-to-the-database-at-runtime/CS/XPO/NET_Framework/RuntimeDbChooser.Win/Program.cs#L43

#if DEBUG
            if(System.Diagnostics.Debugger.IsAttached && winApplication.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                winApplication.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;

xaf-how-to-show-a-custom-form-as-the-winforms-dashboard-designer/CS/XPO/DashBoardCustomForm/DashBoardCustomForm.Win/Startup.cs#L39

#if DEBUG
            if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;

xaf-how-to-access-the-master-detailview-information-from-a-nested-listview-controller/CS/XPO/GetMasterFrame/GetMasterFrame.Win/Startup.cs#L29

#if DEBUG
            if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;

xaf-how-to-extend-the-application-model/CS/XPO/ExtendModel/ExtendModel.Win/Startup.cs#L29

#if DEBUG
            if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;

xaf-save-and-share-custom-view-settings/CS/XPO/ViewSettings/ViewSettings.Win/Startup.cs#L43

#if DEBUG
            if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;

XAF-CRUD-for-Non-Persistent-Objects-Stored-Remotely/VB/NonPersistentObjectsDemo.Win/Program.vb#L46

#If DEBUG Then
            If System.Diagnostics.Debugger.IsAttached AndAlso winApplication.CheckCompatibilityType = CheckCompatibilityType.DatabaseSchema Then
                winApplication.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways

XAF_how-to-store-file-attachments-in-the-file-system-instead-of-the-database/VB/E965.Web/Global.asax.vb#L45

#If DEBUG Then
            If System.Diagnostics.Debugger.IsAttached AndAlso WebApplication.Instance.CheckCompatibilityType = CheckCompatibilityType.DatabaseSchema Then
                WebApplication.Instance.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways

See Also

How Database is Updated in Debug Mode

XafApplication Class

XafApplication Members

DevExpress.ExpressApp Namespace