Production Database and Application Updates

• Mar 31, 2025
• 10 minutes to read

This topic describes how to update an application deployed on a user machine or on an application server.

Update an ASP.NET Core Blazor Application

Update Application Files

To update an application, you can use the same technique as when you deployed it: Deploy ASP.NET Core Blazor Server Apps to Azure, Linux with Nginx or Windows with IIS.

Update a Database

1. Launch the Command Prompt. Type “cd PathToMyBlazorApplication“, where “PathToMyBlazorApplication” is the path to an application on a workstation, and press ENTER. Type “MySolution.Blazor.ServerSide.exe -updateDatabase“ (for Windows machines) or “dotnet MySolution.Blazor.ServerSide.dll -updateDatabase“ (for Linux or MacOS machines), press ENTER, and follow the on-screen instructions.

   Console

   cd c:\MySolution
   MySolution.Blazor.Server.exe -updateDatabase
   

   You can also use the following -updateDatabase parameters:

   • -silent (the first parameter)
     Initiates a silent update. Does not require direct end-user interaction.
   • -forceUpdate (the last parameter)
     Forces a schema update on each run.
   Console

   cd c:\MySolution
   MySolution.Blazor.Server.exe -updateDatabase -silent -forceUpdate
   

   

2. Run the ASP.NET Core Blazor application to ensure that the update was successful.

Update a Windows Forms Application

Update a Database (DBUpdater Tool)

To run the DBUpdater with a project that targets .NET6+, build and publish the project according to the target platform (operating system and its architecture). Refer to the Microsoft documentation for more information:

• Deploy .NET Core apps with Visual Studio
• .NET application publishing overview (console)

Follow the steps below to update a database:

1. Install the DBUpdater tool to a workstation or the server you wish to update. For more information, refer to the following help topic: Set Up the Database Connection.

   Important

   The DBUpdater tool does not support a scenario when an application uses multiple Object Space Providers. The following help topic describes the workarounds for this scenario: Updating the database when multiple persistent Object Space Providers are used.

2. Launch the Command Prompt and run the DBUpdater:

   Console (.NET Framework)

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFramework\DBUpdater
   DBUpdater.v24.2.exe ..\MySolution\MySolution.Win.exe.config
   

   Console (.NET)

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFrameworkNetCore\DBUpdater
   DBUpdater.v24.2.exe ..\MySolution\MySolution.Win.dll.config
   

   You can also use the following DBUpdater parameters:

   • -silent (the first parameter)
     Initiates a silent update. Does not require direct end-user interaction.
   • -forceUpdate (the last parameter)
     Forces a schema update on each run.
   Console (.NET Framework)

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFramework\DBUpdater
   DBUpdater.v24.2.exe -silent ..\MySolution\MySolution.Win.exe.config -forceUpdate
   

   Console (.NET)

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFrameworkNetCore\DBUpdater
   DBUpdater.v24.2.exe -silent ..\MySolution\MySolution.Win.dll.config -forceUpdate
   

   The DBUpdater connects to the Database Server and first compares version information (determines whether the application database is older than the application). Press ENTER to force DBUpdater to update the database.

   

3. Optional: To obtain DBUpdater logs, edit its configuration file (DBUpdater.v24.2.exe.config in the .NET Framework projects or DBUpdater.v24.2.dll.config in .NET projects) and set the eXpressAppFramework switch value to 3 (Info):

   DBUpdater.v24.2.exe.config (.NET Framework)

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <startup>
       <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0" />
     </startup>
     <system.diagnostics>
       <switches>
         <!-- Use one of the following predefined values: 0-Off, 1-Errors, 2-Warnings, 3-Info, 4-Verbose. The default value is 0. -->
         <add name="eXpressAppFramework" value="3" />
       </switches>
     </system.diagnostics>
   </configuration>
   

   DBUpdater.v24.2.dll.config (.NET)

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <appSettings>
       <!-- Use one of the following predefined values: 0-Off, 1-Errors, 2-Warnings, 3-Info, 4-Verbose. The default value is 0. -->
       <add key="eXpressAppFrameworkTraceLevel" value="3"/>
     </appSettings>
   </configuration>
   

   Logs are written to the eXpressAppFramework.log file.

4. Run the WinForms application to ensure that the update was successful.

Note

If you encounter issues with your WinForms application update, refer to the following help topic: Deployment Troubleshooting Guide.

Update Application Files

To update an application, you can use the same technique as when you deployed it:

• Xcopy Method
• Setup Project Method
• Update ClickOnce applications

Note

Do not overwrite a user’s MySolution.Win.exe.config (in the .NET Framework projects) or MySolution.Win.dll.config (in the .NET projects) or Model.User.xafml files when you update an application.

Update Application Files Automatically (Application Updater Utility)

Use this technique to automate the update process at multiple workstations.

Prerequisites

Ensure that applications on end-user workstations and the new application you want to deploy meet the following conditions:

1. The XafApplication.CheckCompatibilityType property is set to ModulesInfo.
2. NonPersistentObjectSpaceProvider is not the first registered Provider in your application. XAF uses the first registered Object Space Provider while an application updates.

Enable Auto Update

1. Choose a file server in the end-user network. On this server, create a shared folder that stores newer application versions (for example, the MySolutionUpdateSource folder).
2. Ensure that all end users have read permission to this folder and do not have write permission.

3. On all end-user workstations, open the MySolution.Win.exe.config (for the .NET Framework projects) or MySolution.Win.dll.config (for the .NET projects) file and set the NewVersionServer key to the UNC path to this folder:

   XML

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <!-- ... -->
     <appSettings>
       <!-- ... -->
       <add key="NewVersionServer" value="\\FILESERVER\MySolutionUpdateSource\" />
     </appSettings>
   </configuration>  
   

4. Copy the WinForms application folder contents from the end-user workstation to the MySolutionUpdateSource shared folder.
   The UNC path to the application executable should be “\FILESERVER\MySolutionUpdateSource\MySolition.Win.exe“.

5. Copy the %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFramework\Application Updater\DevExpress.ExpressApp.Updater.exe file from the developer workstation to the MySolutionUpdateSource shared folder.
   The UNC path to this file should be “\FILESERVER\MySolutionUpdateSource\DevExpress.ExpressApp.Updater.exe“.

6. When you run the WinForms application at an end-user workstation that was not updated, the following Updater progress bar is shown:

   

   If one of the error messages below is displayed instead, ensure the following:

   • the UNC path in the configuration file is correct;
   • the shared folder is readable;
   • the shared folder contains the DevExpress.ExpressApp.Updater.exe file.

   

   The application restarts automatically after updating.

To deploy a new application version, follow the steps below:

1. Replace the files located in the MySolutionUpdateSource shared folder with new application files.
2. Update the database version as described in the Update Database (DBUpdater Tool) section.

When an end user launches the WinForms application, it is instantly updated. The update process takes as much time as required to copy the MySolutionUpdateSource shared folder contents to the end-user workstation. Note that the update process will not be initiated if the database is not updated, even if the MySolutionUpdateSource folder contains a new version of the application.

Note

• The MySolutionUpdateSource folder should only store new application files. Do not store other files in this folder. Otherwise, they will be copied to each end-user workstation.
• If you want to change the Updater utility behavior, change and recompile its sources. The Updater tool sources are in the following folder: %PROGRAMFILES%\DevExpress 24.2\Components\Sources\DevExpress.ExpressApp.Tools\DevExpress.ExpressApp.Updater. For example, you can configure this tool to download files of a new version from a remote web server instead of using a shared folder in a local network.

Update an ASP.NET Web Forms Application

Update Application Files

To update an application, you can use the same technique as when you deployed it:

• Xcopy Method
• Publish Web Method
• Setup Project Method

Note

Do not overwrite a custom server-side Web.config file when you update an application.

Update a Database (DBUpdater Tool)

1. Install the DBUpdater tool to a workstation or the server you wish to update. For more information, refer to the following help topic: Set Up the Database Connection.

2. Launch the Command Prompt and run the DbUpdater:

   Console

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFramework\DBUpdater
   DBUpdater.v24.2.exe ..\MySolution\Web.config
   

   You can also use the following DBUpdater parameters:

   • -silent (the first parameter)
     Initiates a silent update. Does not require direct end-user interaction.
   • -forceUpdate (the last parameter)
     Forces a schema update on each run.
   Console

   cd %PROGRAMFILES%\DevExpress 24.2\Components\Tools\eXpressAppFramework\DBUpdater
   DBUpdater.v24.2.exe -silent ..\MySolution\Web.config -forceUpdate
   

   

3. Run the ASP.NET Web Forms application to ensure that the update was successful.

If you encounter issues with your ASP.NET Web Forms application update, do the following:

1. Create a new folder and place all built application assemblies into it.
2. Ensure that the assembly that contains your WebApplication descendant is in this folder. The default name of this assembly is the name of your application with the .Web postfix (for example, MySolution.Web).
3. Place the Web.config file into this folder.
4. Run the DBUpdater.v24.2.exe tool with the fully-qualified path to the Web.config file.

Update Database on Microsoft Azure

1. Install the DevExpress.ExpressApp.DBUpdater NuGet package on Azure. This step is not required for XAF Blazor UI Applications. A Blazor application can update its database without external tools.
2. In the Azure CLI, run DBUpdater or a Blazor application with the -silent key.

Update Database in Multi-Tenant Application

Using DBUpdater for Windows Apps and the –updateDatabase Switch for Blazor Apps

The DBUpdater tool and the functionality to automatically update the database with the --updateDatabase key have a limitation in multi-tenant applications. Only the host database can be updated, as the specific tenant database is identified only after user login. These tools cannot be used for creating or updating the database structure or data in tenant databases.

These tools can be useful for the following actions in a multi-tenant application:

• Initially create the host database (if you need to create a database before the first application launch).
• Update data in the host database (for instance, create new tenants or administrator users for the host database).  

How to Use ModuleUpdater to Update Database in Multi-Tenant Applications

Since a multi-tenant application works with several databases of different structures, ModuleUpdater runs in the application in the following cases:

• When logging into the host interface
• When logging into a tenant interface for the first time

It is essential to consider whether the update applies to a tenant database or the host database.

The XAF Solution Wizard generates projects with DevExpress.ExpressApp.MultiTenancy.ITenantProvider.TenantId and TenantName properties to identify the current tenant. These properties return null when the host database is being updated.

The following code outlines the recommended structure of the updater class in multi-tenant applications:

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.MultiTenancy;
using DevExpress.ExpressApp.Updating;
using Microsoft.Extensions.DependencyInjection;

namespace MySolution.Module.DatabaseUpdate;
public class Updater :ModuleUpdater {
    public Updater(IObjectSpace objectSpace, Version currentDBVersion) :
          base(objectSpace, currentDBVersion) {
    }
    public override void UpdateDatabaseAfterUpdateSchema() {
        base.UpdateDatabaseAfterUpdateSchema();

        if (TenantName == null) {
            // Update data in the host database
        } else {
            // Update data in tenant databases
            if (TenantName == "company1.com") {
                // Update data in the company1.com tenant database
            }
        }
        // Update data in any database—host or tenant
    }

    // Returns the current tenant identifier or `null` if the application runs in Host User Interface mode
    Guid? TenantId {
        get { return ObjectSpace.ServiceProvider.GetRequiredService<ITenantProvider>().TenantId; }
    }

    // Returns the current tenant name or `null` if the application runs in Host User Interface mode
    string TenantName {
        get { return ObjectSpace.ServiceProvider.GetRequiredService<ITenantProvider>().TenantName; }
    }
}

Register Predefined Dashboards in a Multi-Tenant Application

In a multi-tenant application, the host database cannot store Dashboards Module data. When you register a predefined dashboard in the Module Updater, call the DashboardsModule.AddDashboardData<T> method only if a tenant database is being updated. You can implement ModuleUpdater as described in the previous section.

Refer to the following help topic for more information about predefined Dashboards: Create a Predefined Dashboard and Add it to the Navigation.

Register Predefined Reports in a Multi-Tenant Application

In a multi-tenant application, the host database cannot store Reports Module data. When you register a predefined report in the Module Updater, run the Reports Module Updater only if a tenant database is being updated. You can implement ModuleUpdater as follows:

C#

public override IEnumerable<ModuleUpdater> GetModuleUpdaters(IObjectSpace objectSpace, Version versionFromDB) {

    // Adds Module Updaters required to update tenant and host databases
    ModuleUpdater updater = new DatabaseUpdate.Updater(objectSpace, versionFromDB);
    var updaters = new List<ModuleUpdater>() { updater };

    // Returns the current tenant identifier or `null` if the application runs in Host User Interface mode
    Guid? tenantId = objectSpace.ServiceProvider.GetRequiredService<ITenantProvider>().TenantId;

    // Adds Updaters that are required for tenant databases only
    if (tenantId != null) {
        PredefinedReportsUpdater predefinedReportsUpdater =
            new PredefinedReportsUpdater(Application, objectSpace, versionFromDB);
        predefinedReportsUpdater.AddPredefinedReport<XtraReport1>("Report Name", typeof(ApplicationUser));
        updaters.Add(predefinedReportsUpdater);
    }
    return updaters;
}

Refer to the following help topic for more information about predefined Reports: Create Predefined Static Reports.

Important Notes

• If you encounter issues with your application update, refer to the following help topic: Deployment Troubleshooting Guide.

• To prevent a specific module from updating the database, specify a fixed version of this module assembly (for example, 1.0.0.0). It can be required to force version synchronization of your WinForms, ASP.NET Core Blazor, and ASP.NET Web Forms modules. The default build and revision numbers are specified with the asterisk (*), and Visual Studio automatically increments these numbers (see AssemblyVersionAttribute). This leads to a database version mismatch on each module update.