Log In
[Expand]Welcome to DevExpress .NET Documentation
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Collapse]eXpressApp Framework
 [Expand]Getting Started
  [Expand]Application Solution Components
  [Collapse]Business Model Design
    Business Model Design Basics
    Built-in Business Classes for Most Popular Scenarios
   [Expand]Business Model Design with Entity Framework
   [Expand]Business Model Design with XPO
    Non-Persistent Objects
    PropertyChanged Event in Business Classes
   [Expand]Data Types Supported by built-in Editors
    Mapping Complex Types to the Database
   [Expand]Types Info Subsystem
    Connect an XAF Application to a Database Provider
    Data Annotations in Data Model
    Create and Update the Application's Database
  [Expand]Application Model
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging, Testing and Error Handling
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Task-Based Help
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Create and Update the Application's Database

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.


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:

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.

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.


You can prevent a specific module from updating the database by specifying a fixed version of this module's assembly (e.g., 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.

Is this topic helpful?​​​​​​​