Update Application and Database Versions using the ModuleInfo Table
- 7 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.
#Update Database When Debugging
When running an application for the first time, the version of the modules in a database is set to the version of these modules in the application, so there will be no conflict between versions (see Create and Update the Application’s Database). Then, each time you run the application, the process defined above (see the image) is executed in case something has been changed in the application or database. The update process is provided by the built-in Database Updater’s Update method. To call this method, the XafApplication.DatabaseVersionMismatch event is handled in every XAF solution (see the code below). This event is raised when starting the application if the database version is older than the application version.
public partial class MySolutionWindowsFormsApplication : WinApplication {
private static void MySolutionWindowsFormsApplication_DatabaseVersionMismatch(object sender,
DatabaseVersionMismatchEventArgs e) {
if(System.Diagnostics.Debugger.IsAttached) {
e.Updater.Update();
e.Handled = true;
}
}
partial class MySolutionWindowsFormsApplication {
//...
private void InitializeComponent() {
//...
this.DatabaseVersionMismatch += this.MySolutionWindowsFormsApplication_DatabaseVersionMismatch;
// ...
}
// ...
}
This event handler is automatically generated in the Program.cs (Program.vb) and Global.asax.cs (Global.asax.vb) files in the Windows Forms and ASP.NET Web Forms application projects, respectively.
If you need to replace the mechanism illustrated in the image above with your own, handle the XafApplication.CustomCheckCompatibility event.
Note
There is the Xaf
#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. 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.1\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.