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. In addition, the DBUpdater tool intended for updating the database version externally is available with XAF. This tool is useful for application administrators when they deploy a new application version and need to update the database version as well. In this topic, you will learn how to update an application database in the application debug mode, directly in code and in the application release mode, by means of the DBUpdater tool. To learn 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 that the XAF uses to check application and database version compatibility, and to update the database, consists of the following steps.
Utilize the ModuleUpdater‘s ModuleUpdater.UpdateDatabaseBeforeUpdateSchema and ModuleUpdater.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 instance, it can be required to force version synchronization of your WinForms module (for .NET 6+ apps) and ASP.NET Web Forms modules (for .NET Framework apps). 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 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 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 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.
To run the DBUpdater with a project that targets .NET6+, build and publish the project according to the target platform (operating system and its architecture). Refer to the Microsoft documentation for more information:
For more information on how to use the DBUpdater tool, refer to the following section: Application Update.
Note
- If you are using a Middle Tier Application Server, there is no need for the DBUpdater. The Application Server automatically updates a database when the former is restarted. So, after you have updated your client application, you need to stop the server service, copy newly built assemblies to the application server, and start the server service. The server will automatically check compatibility and launch the update process.
- The DBUpdater tool can only be used if an XAF application uses the default Object Space Provider, and the database connection string is specified in the application configuration file. If your application connects to a data store using a custom Object Space Provider, the DBUpdater tool will not work. For example, suppose you are using the default Object Space provider with a custom data store provider to work with several databases simultaneously. In this case, you will need to update your databases manually or implement a custom database updater. When implementing the custom database updater, you can base it on the original DBUpdater tool. Its source code can be found in the %PROGRAMFILES%\DevExpress 23.2\Components\Sources\DevExpress.ExpressApp.Tools\DevExpress.ExpressApp.Updater folder by default.
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 23.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.