Update Application and Database Versions using the ModuleInfo Table

• Jan 21, 2026
• 6 minutes to read

When working with a business application, one important area of concern is application and database version compatibility. XAF provides a version compatibility checking mechanism, allowing the application to run only when the application and database are of the same version. By default, this mechanism works in a simplified mode, when the presence of all required tables, columns and the database itself is checked. In this simple mode, you cannot track changes with business logic, only changes with the business model are detected (e.g., when a new business class or property is declared). However, you can switch to a more complicated mode, when versions of your modules are stored in the ModuleInfo table and are compared with their actual assembly versions. As the assembly versions are incremented on each rebuild, any changes with the modules code are detected. To change the mode, you can set the XafApplication.CheckCompatibilityType property to CheckCompatibilityType.ModuleInfo. This topic describes how the application and database compatibility is checked in the ModuleInfo mode.

In application debug mode, the database version update mechanism is triggered when the database version is lower than the application version. This topic explains how to update an application database in the application debug mode directly in code and in the application release mode. For information on how and when the application’s database is created, refer to the Create and Update the Application’s Database topic.

Application and Database Versions Policy Overview

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

Utilize the ModuleUpdater‘s UpdateDatabaseBeforeUpdateSchema() and UpdateDatabaseAfterUpdateSchema() methods. Override them to modify a module’s database tables, both before and after updating the database schema. For example, this may 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 Using the Security System and Supply Initial Data topics. Note that you can implement complex updating logic that takes into account the differences between application versions. For details, refer to the ModuleUpdater class description.

Note

You can prevent a specific module from updating the database by specifying a fixed version of this module’s assembly (for example, 1.0.0.0). For example, it can be required to force version synchronization of your WinForms module. By default, the build and revision numbers are specified by using the asterisk (*), and Visual Studio auto-increments these numbers (see AssemblyVersionAttribute). This leads to a database version mismatch on each module update.

Update Database During Debugging

When you run the application for the first time, the version compatibility checking mechanism sets the version of the modules in a database to version of these modules in the application (see Create and Update the Application’s Database).

The DevExpress Template Kit adds the DatabaseVersionMismatch event handler in new Blazor, Web API, and WinForms projects to keep the application and database versions synchronized. If the database version is older than the application’s version, the event triggers at startup, and the handler runs the Database Updater’s Update method.

SolutionName.Blazor.Server\BlazorApplication.cs

public class SolutionNameBlazorApplication : BlazorApplication {
    public SolutionNameBlazorApplication() {
       DatabaseVersionMismatch += SolutionNameBlazorApplication_DatabaseVersionMismatch;
       // ...
    }
    void SolutionNameBlazorApplication_DatabaseVersionMismatch(object sender, DatabaseVersionMismatchEventArgs e) {
       e.Updater.Update();
       e.Handled = true;
       // ...

SolutionName.WebApi\Startup.cs

public class Startup {
   public void ConfigureServices(IServiceCollection services) {
      services.AddXafWebApi(builder => {
            builder.AddBuildStep(application => {
               // ...
               if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                  application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;
                  application.DatabaseVersionMismatch += (s, e) => {
                        e.Updater.Update();
                        e.Handled = true;
                  };
               }
            });
         // ...

SolutionName.Win\WinApplication.cs

public class SolutionNameWindowsFormsApplication : WinApplication {
   public SolutionNameWindowsFormsApplication() {
      DatabaseVersionMismatch += SolutionNameWindowsFormsApplication_DatabaseVersionMismatch;
      // ...
   }
   void SolutionNameWindowsFormsApplication_DatabaseVersionMismatch(object sender, DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs e) {
      e.Updater.Update();
      e.Handled = true;
      // ...

If you need to replace the mechanism illustrated in the image above with your own, handle the XafApplication.CustomCheckCompatibility event.

Note

There is the XafApplication.DatabaseUpdateMode property, which specifies whether the database is updated on every application run or only when its version is older than the application version. In VB solution templates, this property is set to the DatabaseUpdateMode.UpdateDatabaseAlways value, because of the difficulty in incrementing versions in VB projects. So, the XafApplication.DatabaseVersionMismatch event is raised each time the application starts, but this value is set in debug mode only.

Update Database When Deploying

When users run a deployed application, the database is not updated if the application’s version in the database does not match the actual application version, and an exception is raised. When you deploy your XAF application (its release or updated version), you should supply a database with the same version as the application. If the database version is newer than the actual application version, update the application version. If the database version is older, update the database. For this purpose, XAF includes the special DBUpdater tool for WinForms or ASP.NET Web Forms applications. To update WinForms, ASP.NET Core Web API Service, or Blazor Server applications, run them with the “–updateDatabase“ command line argument. For more information, refer to the following topic: Production Database and Application Updates.

For details on the deployment of XAF applications, refer to the deployment tutorial.

Automatic Updates of Windows Forms Applications

When starting a Windows Forms application whose version is older than the database version, the application can be updated automatically. For this purpose, the following conditions must be met.

• The path to the server with the new application version should be specified.

  In the App.config file, specify the folder containing the updated application version using the NewVersionServer key.

  If the specified server or folder is not found, an exception will be raised.

  If the NewVersionServer key value is not specified, the mechanism defined above (see the first image) will be applied.

• The DevExpress.ExpressApp.Updater.exe file should be placed in the folder with the executable file.

  This tool will update the application version to the new version located on the specified server. However, the update will be performed only if the new application version equals the current database version. Otherwise, an exception will be raised.

  The Application Updater location is %PROGRAMFILES%\DevExpress 25.2\Components\Tools\eXpressAppFramework\Application Updater\DevExpress.ExpressApp.Updater.exe.

The process to check application and database version compatibility (see the first image above) will then be run if no exceptions were raised during the attempt to update the application version.