Create and Update the Application's Database
- 6 minutes to read
The template of an XAF application is implemented so that a database is created when running the application for the first time, and updated when the application’s version grows. This topic details the reasons for this behavior, along with ways to modify it.
Note
XAF doesn’t update an existing database schema when the Entity Framework data model is in use. To synchronize your data model and database, follow the same approach you apply when developing regular non-XAF applications: Code First Migrations.
An application runs successfully when its version equals to the database version. So, each time an application starts, version compatibility is checked. During this process, the system is trying to access the database. When running an application for the first time, the database does not yet exist. So, an exception is raised. This exception is not thrown, but the XafApplication.DatabaseVersionMismatch event is raised to give you an opportunity to create a database. So that you do not have to deal with proper database creation, this event is handled in an XAF application template. See the XXXApplication.cs (XXXApplication.vb) file in your application projects. The event handler looks like this:
public partial class MySolutionWindowsFormsApplication : WinApplication {
//...
private void MySolutionWindowsFormsApplication_DatabaseVersionMismatch(
object sender, DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs e) {
if(System.Diagnostics.Debugger.IsAttached) {
e.Updater.Update();
e.Handled = true;
}
else {
string message = "The application cannot connect to the specified database, " +
"because the database doesn't exist, its version is older " +
"than that of the application or its schema does not match " +
"the ORM data model structure. To avoid this error, use one " +
"of the solutions from the https://www.devexpress.com/kb=T367835 KB Article.";
if(e.CompatibilityError != null && e.CompatibilityError.Exception != null) {
message += "\r\n\r\nInner exception: " + e.CompatibilityError.Exception.Message;
}
throw new InvalidOperationException(message);
}
}
}
According to this code, an exception will be raised, if you run the application in a release mode. In a debug mode, the DatabaseUpdater.Update method is called. This method creates the database, if it does not exist. In the database, the ModulesInfo table is created, in addition to the tables corresponding to persistent classes. The ModulesInfo table is designed to store the modules version. When running the application for the first time, the current version of the application’s modules (see in MSDN) is saved to this table. So, the process of checking the application and database versions will pass successfully, and the application will be loaded.
Then, each time the application is started, the DatabaseVersionMismatch event is raised when the database version is older than the application’s version. That is, the module versions stored in the ModulesInfo table are lower than the actual module versions. In this instance, the DatabaseUpdater.Update method updates the database version, and the application runs successfully. If the database version is bigger than the application’s version, the DatabaseVersionMismatch event is raised, and the DatabaseUpdater.Update method throws an exception.
This technique allows you to build an XAF application easily. You do not have to think about database creation, update and compatibility with the application. At the same time, there are methods in the ModuleBase class that allow you to make changes in the database when it is updated (see Supply Initial Data (XPO)).
When you connect to the database via the Middle Tier Application Server, the compatibility check is performed at the server side. You should unconditionally throw an exception when the XafApplication.DatabaseVersionMismatch event occurs.
public partial class MySolutionWindowsFormsApplication : WinApplication {
//...
private void MySolutionWindowsFormsApplication_DatabaseVersionMismatch(
object sender, DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs e) {
throw new InvalidOperationException(
"The application cannot connect to the specified database, " +
"because the latter does not exist or its version is older " +
"than that of the application.\r\n" +
"The automatic update is disabled, because the application " +
"was started without debugging.\r\n" +
"You should start the application under Visual Studio, or modify the " +
"source code of the 'DatabaseVersionMismatch' event handler " +
"to enable automatic database update, " +
"or manually create a database using the 'DBUpdater' tool.");
}
}
}
To learn how to provide the required connection string to your application’s database, refer to the Connect an XAF Application to a Database Provider topic.
You can find more information on the process of checking the application, as well database version compatibility, useful when deploying an application, in the Update Application and Database Versions using the ModuleInfo Table topic.
Note
You can prevent a specific module from updating the database by specifying a fixed version of this module’s assembly (e.g., 1.0.0.0). For instance, it can be required to force version synchronization of your WinForms and 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.