Create and Update the Application's Database
- 5 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 Core data model is in use. To synchronize your data model and database, follow the same approach you apply when developing regular non-XAF applications: Migrations Overview (EF Core)
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);
}
}
}
The CheckCompatibilityType setting specifies how the database’s compatibility with the application is checked. The DatabaseVersionMismatch event is raised when the database version does not match the application’s version.
When you connect to the database via the Middle Tier Application Server, the compatibility check is performed at the server side. Throw an exception when the XafApplication.DatabaseVersionMismatch event occurs.
public partial class MySolutionWindowsFormsApplication : WinApplication {
//...
private void MySolutionWindowsFormsApplication_DatabaseVersionMismatch(
object sender, DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs e) {
string message = "Application cannot connect to the specified database.";
CompatibilityDatabaseIsOldError isOldError = e.CompatibilityError as CompatibilityDatabaseIsOldError;
if (isOldError != null && isOldError.Module != null) {
message = "The client application cannot connect " +
"to the Middle Tier Application Server and its database. " +
"To avoid this error, ensure that both the client and the server " +
"have the same modules set. Problematic module: " + isOldError.Module.Name +
". For more information, see https://docs.devexpress.com/eXpressAppFramework/113439/concepts/" +
"security-system/middle-tier-security-wcf-service#troubleshooting";
}
if (e.CompatibilityError == null) {
message = "You probably tried to update the database in Middle Tier Security mode " +
"from the client side. In this mode, the server application updates " +
"the database automatically. To disable the automatic database update, set the " +
"XafApplication.DatabaseUpdateMode property to the DatabaseUpdateMode.Never value " +
"in the client application.";
}
throw new InvalidOperationException(message);
}
}
For information on how to provide a 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 and database version compatibility 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 (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.