XafApplication.DatabaseVersionMismatch Event

Occurs when the database should be synchronized with the application version.

Namespace: DevExpress.ExpressApp

Assembly: DevExpress.ExpressApp.v25.2.dll

NuGet Package: DevExpress.ExpressApp

Declaration

C#

public event EventHandler<DatabaseVersionMismatchEventArgs> DatabaseVersionMismatch

VB.NET

Public Event DatabaseVersionMismatch As EventHandler(Of DatabaseVersionMismatchEventArgs)

Event Data

The DatabaseVersionMismatch event's data class is DatabaseVersionMismatchEventArgs. The following properties provide information specific to this event:

Property	Description
CompatibilityError	Returns the database and application compatibility error.
Handled	Gets or sets a value that indicates whether the event handler has completely handled the event or whether the system should continue its own processing. Inherited from HandledEventArgs.
Updater	Provides access to the Database Updater. Use the object returned by this property to update the application database.

Remarks

XAF checks database and application compatibility when the application accesses the database. After checking, the DatabaseVersionMismatch event fires in the following cases:

• The database cannot be opened.
  The CompatibilityError property returns CompatibilityUnableToOpenDatabaseError.
• The database version is older than the application version.
  The CompatibilityError property returns CompatibilityDatabaseIsOldError.
• The DatabaseUpdateMode property is set to UpdateDatabaseAlways.
  The CompatibilityError property returns null.

Handle this event to update the database. Use the Updater parameter to access the Database Updater object. Set the Handled parameter to true, to prevent other database version updates.

The DevExpress Template Kit handles the DatabaseVersionMismatch event in new Blazor, Web API, and WinForms projects to keep the application and database versions synchronized. If the database version is older than the application’s version, the event triggers at startup, and the handler runs the Database Updater’s Update method. Rewrite this event handler if you need to implement custom logic.

SolutionName.Blazor.Server\BlazorApplication.cs

public class SolutionNameBlazorApplication : BlazorApplication {
    public SolutionNameBlazorApplication() {
       DatabaseVersionMismatch += SolutionNameBlazorApplication_DatabaseVersionMismatch;
       // ...
    }
    void SolutionNameBlazorApplication_DatabaseVersionMismatch(object sender, DatabaseVersionMismatchEventArgs e) {
       e.Updater.Update();
       e.Handled = true;
       // ...

SolutionName.WebApi\Startup.cs

public class Startup {
   public void ConfigureServices(IServiceCollection services) {
      services.AddXafWebApi(builder => {
            builder.AddBuildStep(application => {
               // ...
               if(System.Diagnostics.Debugger.IsAttached && application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
                  application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;
                  application.DatabaseVersionMismatch += (s, e) => {
                        e.Updater.Update();
                        e.Handled = true;
                  };
               }
            });
         // ...

SolutionName.Win\WinApplication.cs

public class SolutionNameWindowsFormsApplication : WinApplication {
   public SolutionNameWindowsFormsApplication() {
      DatabaseVersionMismatch += SolutionNameWindowsFormsApplication_DatabaseVersionMismatch;
      // ...
   }
   void SolutionNameWindowsFormsApplication_DatabaseVersionMismatch(object sender, DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs e) {
      e.Updater.Update();
      e.Handled = true;
      // ...

Important

If the application includes the Middle Tier Server Application, the compatibility check must be performed at the server side. Client applications (Blazor, Web API, and WinForms) should throw an exception when the DatabaseVersionMismatch event occurs.

When you use the Template Kit to create an application with a Middle Tier Security server, the kit handles the DatabaseVersionMismatch event in the Middle Tier Application.

MiddleTier

// File: SolutionName.MiddleTier\Startup.cs
builder.AddBuildStep(application => {
   application.CheckCompatibilityType = DevExpress.ExpressApp.CheckCompatibilityType.DatabaseSchema;
   if (application.CheckCompatibilityType == CheckCompatibilityType.DatabaseSchema) {
      application.DatabaseUpdateMode = DatabaseUpdateMode.UpdateDatabaseAlways;
      application.DatabaseVersionMismatch += (s, e) => {
            e.Updater.Update();
            e.Handled = true;
      };
   }
   //...

The DatabaseVersionMismatch event does not occur if you handle the CustomCheckCompatibility event.

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the DatabaseVersionMismatch event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

xaf-how-to-import-data-in-xaf/CS/WinWebSolution.Web/ApplicationCode/WebApplication.cs#L76

this.Security = this.securitySimple1;
this.DatabaseVersionMismatch += new System.EventHandler<DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs>(this.WinWebSolutionAspNetApplication_DatabaseVersionMismatch);
((System.ComponentModel.ISupportInitialize)(this)).EndInit();

xaf-how-to-implement-a-custom-attribute-to-customize-the-application-model/CS/DXExample.Web/ApplicationCode/WebApplication.cs#L41

this.Modules.Add(this.module3);
this.DatabaseVersionMismatch += new System.EventHandler<DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs>(this.DXExampleAspNetApplication_DatabaseVersionMismatch);
((System.ComponentModel.ISupportInitialize)(this)).EndInit();

xaf-how-to-dynamically-change-mask-settings-based-on-the-current-object/CS/ChangeEditMask.Web/WebApplication.cs#L64

this.Modules.Add(this.module4);
this.DatabaseVersionMismatch += new System.EventHandler<DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs>(this.ChangeEditMaskAspNetApplication_DatabaseVersionMismatch);
((System.ComponentModel.ISupportInitialize)(this)).EndInit();

xaf-how-to-use-the-file-attachment-module-with-a-legacy-database/CS/CustomFileDataSolution.Web/WebApplication.cs#L73

this.Modules.Add(this.validationModule);
this.DatabaseVersionMismatch += new System.EventHandler<DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs>(this.CustomFileDataSolutionAspNetApplication_DatabaseVersionMismatch);
((System.ComponentModel.ISupportInitialize)(this)).EndInit();

xaf-how-to-prevent-altering-the-legacy-database-schema-when-creating-an-xaf-application/CS/WinWebSolution.Web/WebApplication.cs#L38

this.Modules.Add(this.module3);
this.DatabaseVersionMismatch += new System.EventHandler<DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs>(this.WinWebSolutionAspNetApplication_DatabaseVersionMismatch);
((System.ComponentModel.ISupportInitialize)(this)).EndInit();

VB.NET

xaf-separate-employees-data-in-different-departments-using-security-permissions/VB/MainDemo.Web/WebApplication.vb#L59

Me.Security = Me.securityStrategyComplex1
AddHandler Me.DatabaseVersionMismatch, New System.EventHandler(Of DevExpress.ExpressApp.DatabaseVersionMismatchEventArgs)(AddressOf Me.MainDemoAspNetApplication_DatabaseVersionMismatch)
CType((Me), System.ComponentModel.ISupportInitialize).EndInit()