Update Application and Database Versions using the ModuleInfo Table
7 min 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 eXpressApp Framework uses to check application and database version compatibility, and to update the database, consists of the following steps.
You can prevent a specific module from updating the database by specifying a fixed version of this module's assembly (e.g., 188.8.131.52). For instance, it can be required to force version synchronization of your WinForms moduleand ASP.NET modules. 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
Private Shared Sub MySolutionWindowsFormsApplication_DatabaseVersionMismatch( _
ByVal sender As Object, _
ByVal e As DatabaseVersionMismatchEventArgs) Handles MyBase.DatabaseVersionMismatch
If System.Diagnostics.Debugger.IsAttached Then
e.Handled = True
Public Partial Class MySolutionWindowsFormsApplication
Private Sub InitializeComponent()
AddHandler 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 application projects, respectively.
When end-users run a deployed application, the database is not updated if the application's version in the database does not equal the actual application version and an exception is raised. So, when you deploy your XAF application (its release or updated version) for end-users, you should supply a database with the same version as the application. If the database version is higher than the actual application version, increment the application version. If the database version is lower, update the database. For this purpose, XAF comes with the special DBUpdater tool. To learn how to use it, refer to the Application Update deployment tutorial lesson.
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(x86)%\DevExpress 19.2\Components\%PROGRAMFILES(x86)%\DevExpress 19.2\.NET Core Desktop Libraries\Sources\DevExpress.ExpressApp.Tools\DevExpress.ExpressApp.Updater folder by default.
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(x86)%\DevExpress 19.2\Components\%PROGRAMFILES(x86)%\DevExpress 19.2\.NET Core Desktop Libraries\Tools\eXpressAppFramework\Application Updater\DevExpress.ExpressApp.Updater.exe by default.
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.