ModuleUpdater Class

A Module updater. Allows you to handle a database update when the application version changes.

Namespace: DevExpress.ExpressApp.Updating

Assembly: DevExpress.ExpressApp.v20.2.dll

NuGet Package: DevExpress.ExpressApp

Declaration

C#

public class ModuleUpdater

VB.NET

Public Class ModuleUpdater

Remarks

An XAF application automatically checks application and database version compatibility on each start. The application compares module versions stored in the database with actual module versions. If versions from the database are lower than the actual versions, the application collects persistent classes and automatically updates the database schema. However, you may need to convert the database data to reflect changes in your application.

When you add a new module via the New Module template, the Updater.cs (Updater.vb) file is automatically created in the module’s project. This file contains the declaration of the ModuleUpdater class’ descendant. To handle differences between versions of an application, override these descendant’s methods.

Method	Description
ModuleUpdater.UpdateDatabaseBeforeUpdateSchema	Override this method to specify the database update code, which should be performed before the database schema is updated.
ModuleUpdater.UpdateDatabaseAfterUpdateSchema	Override this method to specify the database update code which should be performed after the database schema is updated.

When overriding these methods, you can use the following protected properties.

Property	Description
ObjectSpace	This property provides you with access to an IObjectSpace object that can be used for database update operations. Do not use a custom Object Space to update the database. Instead, perform all the required operations via the Object Space returned by this property.
CurrentDBVersion	This property returns the current version of the database. If the database is not yet created, the version is 0.0.0.0. Use this information to determine what updates to the database are necessary.

The following code snippet contains a sample Updater class’ implementation. Note the use of the ObjectSpace and CurrentDBVersion properties.

C#

public class Updater : DevExpress.ExpressApp.Updating.ModuleUpdater {
    public Updater(IObjectSpace objectSpace, Version currentDBVersion) : 
        base(objectSpace, currentDBVersion) { }
    public override void UpdateDatabaseAfterUpdateSchema() {
        base.UpdateDatabaseAfterUpdateSchema();
        if(CurrentDBVersion < new Version("1.5.0.0")){
            Position developerPosition =
                ObjectSpace.FindObject<Position>(CriteriaOperator.Parse("Title == 'Developer'"));
            if(developerPosition == null) {
                developerPosition = ObjectSpace.CreateObject<Position>();
                developerPosition.Title = "Developer";
                developerPosition.Save();
            }
            Position managerPosition = 
                ObjectSpace.FindObject<Position>(CriteriaOperator.Parse("Title == 'Manager'"));
            if(managerPosition == null) {
                managerPosition = ObjectSpace.CreateObject<Position>();
                managerPosition.Title = "Manager";
                managerPosition.Save();
            }
        }
        ObjectSpace.CommitChanges();
    }
}

VB.NET

Public Class Updater
    Inherits DevExpress.ExpressApp.Updating.ModuleUpdater
    Public Sub New(ByVal objectSpace As IObjectSpace, ByVal currentDBVersion As Version)
        MyBase.New(objectSpace, currentDBVersion)
    End Sub
    Public Overrides Sub UpdateDatabaseAfterUpdateSchema()
        MyBase.UpdateDatabaseAfterUpdateSchema()
        If CurrentDBVersion < New Version("1.5.0.0") Then
            Dim developerPosition As Position = ObjectSpace.FindObject(Of Position) _
            (CriteriaOperator.Parse("Title == 'Developer'"))
            If developerPosition Is Nothing Then
                developerPosition = ObjectSpace.CreateObject(Of Position)()
                developerPosition.Title = "Developer"
                developerPosition.Save()
            End If
            Dim managerPosition As Position = ObjectSpace.FindObject(Of Position) _
            (CriteriaOperator.Parse("Title == 'Manager'"))
            If managerPosition Is Nothing Then
                managerPosition = ObjectSpace.CreateObject(Of Position)()
                managerPosition.Title = "Manager"
                managerPosition.Save()
            End If
        End If
        ObjectSpace.CommitChanges()
    End Sub
End Class

 

Methods to access and modify the database directly

You can use the following protected methods to execute custom SQL queries.

Method	Description
int ExecuteNonQueryCommand(string commandText, bool silent)	Executes the SQL statement specified by the first parameter. If the second parameter is false and an error occurs when executing the statement, the exception is thrown. If the second parameter is true and an error occurs when executing the statement, the return value is -1. On success, returns the number of rows affected.
object ExecuteScalarCommand(string commandText, bool silent)	Executes the SQL query specified by the first parameter. If the second parameter is false and an error occurs when querying, the exception is thrown. If the second parameter is true and an error occurs when querying, the return value is -1. On success, returns the first column of the first row in the result set, returned by the query.
IDataReader ExecuteReader(string commandText, bool silent)	Executes the SQL command specified by the first parameter. If the second parameter is false and an error occurs when executing the command, the exception is thrown. If the second parameter is true and an error occurs when querying, the return value is null (Nothing in VB). On success, returns the IDataReader object.

You can also use a number of protected methods that wrap up frequently used queries. The following table lists these methods. Note however, that currently, these method implementations are specific to MS SQL Server, and may not work with different database engines. If you run into an exception when using these methods with non-MS SQL Server databases, you can use the ExecuteNonQueryCommand, ExecuteScalarCommand and ExecuteReader commands, and pass an appropriate query as a parameter.

Method	Description
bool TableExists(string name)	Checks if the specified table exists. Returns true if the table exists, otherwise, returns false.
void DropTable(string name, bool silent)	Removes the table specified by the first parameter. If the second parameter is false and an error occurs during removal, the exception is thrown. If the second parameter is true and an error occurs during removal, the execution is not interrupted.
void DropColumn(string tableName, string columnName)	Removes the specified column on the specified table.
void DropIndex(string tableName, string indexName)	Removes the specified index on the specified table.
void DropConstraint(string tableName, string constraintName)	Removes the specified constraint on the specified table.
void RenameTable(string sourceTableName, string destinationTableName)	Renames the specified table. The first parameter is the old name and the second is the new name.
void RenameColumn(string tableName, string currentColumnName, string newColumnName)	Renames the specified column. The first parameter is the table name, the second is the old column name and the third is the new column name.
void UpdateXPObjectType(string oldTypeName, string newTypeName, string assemblyName)	Updates the XPObjectType table. Finds the row where the TypeName column value equals to the first parameter. In this row, changes the TypeNamecolumn to the value specified by the second parameter and changes the AssemblyNamecolumn to the value specified by the third parameter. The UpdateXPObjectType method only updates the database. You should manually reload changed XPObjectType instances using the Session.Reload method.
void DeleteObjectType(string typeName)	Deletes the row on the XPObjectType table where the TypeName column value equals the string parameter passed.

The protected methods described above log their activities in the application log file. To see use examples of these methods, refer to the How to: Handle Renamings and Deletions of Business Classes and their Properties topic.

Important

These methods cannot be used when the application is connected with the database via a Middle-tier Application Server, a Data Store Pool (XpoDefault.GetConnectionPoolString) or a Cached Data Store. In these scenarios (except for the Middle-tier Application Server), another approach can be used: cast the object space to XPObjectSpace, access its XPObjectSpace.Session member, and use corresponding methods of the Session class. Refer to the Direct SQL Queries help topic.

To learn more about updating the database, refer to the Update Application and Database Versions using the ModuleInfo Table topic.

Note

You can have multiple module updaters per module. To register extra updaters, edit the ModuleBase.GetModuleUpdaters method implementation located in the Module.cs (Module.vb) file. You can return ModuleUpdater.EmptyModuleUpdaters in this method override if your module does not require database updating. When this method is not overridden, the module updaters are automatically collected via the reflection.

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the ModuleUpdater class.

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_validation-how-to-highlight-invalid-properties-when-the-view-is-shown-e1524/CS/DXSample.Module.Win/Updater.cs#L8

namespace DXSample.Module.Win {
    public class Updater : ModuleUpdater {
        public Updater(IObjectSpace objectSpace, Version currentDBVersion) : base(objectSpace, currentDBVersion) { }

VB.NET

XAF_validation-how-to-highlight-invalid-properties-when-the-view-is-shown-e1524/VB/DXSample.Module.Win/Updater.vb#L10

Public Class Updater
    Inherits ModuleUpdater
    Public Sub New(ByVal objectSpace As IObjectSpace, ByVal currentDBVersion As Version)

Inheritance

Object

ModuleUpdater

PredefinedReportsUpdater