Production Database and Application Updates
- 8 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 a Database
- Launch a command line interpreter, for instance, Command Prompt.
- Run your application with the
-updateDatabase
command. You can use the following additional parameters:-silent
initiates a silent update without direct user interaction.-forceUpdate
forces a schema update on each run.
- Follow the on-screen instructions.
C:\Users\Public\MyApplication\MySolution.Blazor.Server.exe -updateDatabase -silent -forceUpdate
Run the application to ensure the update was successful.
#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 Windows Forms Application
#Update a Database
- Launch a command line interpreter, for instance, Command Prompt.
- Run your application with the
-updateDatabase
command. You can use the following additional parameters:-silent
initiates a silent update without direct user interaction.-forceUpdate
forces a schema update on each run.
- Follow the on-screen instructions.
C:\Users\Public\MyApplication\MySolution.Win.exe -updateDatabase -silent -forceUpdate
Run the application to ensure that the update was successful.
#Update Application Files
To update an application, you can use the same technique as when you deployed it:
Note
Do not overwrite a user’s My
#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:
- The XafApplication.CheckCompatibilityType property is set to ModulesInfo.
- 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
- 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).
- Ensure that all end users have read permission to this folder and do not have write permission.
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 version="1.0" encoding="utf-8"?> <configuration> <!-- ... --> <appSettings> <!-- ... --> <add key="NewVersionServer" value="\\FILESERVER\MySolutionUpdateSource\" /> </appSettings> </configuration>
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“.- Copy the %PROGRAMFILES%\DevExpress 25.1\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“. 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:
- Replace the files located in the MySolutionUpdateSource shared folder with new application files.
- Update the database version as described in the Update Database section.
When a user launches the WinForms application, it is instantly updated. The update process cannot be initiated if the database is not updated, even if the MySolutionUpdateSource folder contains a new version of the application.
Note
- The My
Solution 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.Update Source - 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 25.
1 \Components\Sources\DevExpress.Express . 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.App. Tools\Dev Express. Express App. Updater
#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:
Note
Do not overwrite a custom server-side Web.
#Update a Database (DBUpdater Tool)
- 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.
Launch the Command Prompt and run the DbUpdater:
cd %PROGRAMFILES%\DevExpress 25.1\Components\Tools\eXpressAppFramework\DBUpdater DBUpdater.v25.1.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.
cd %PROGRAMFILES%\DevExpress 25.1\Components\Tools\eXpressAppFramework\DBUpdater DBUpdater.v25.1.exe -silent ..\MySolution\Web.config -forceUpdate
- -silent (the first parameter)
- 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:
- Create a new folder and place all built application assemblies into it.
- 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).
- Place the Web.config file into this folder.
- Run the DBUpdater.v25.1.exe tool with the fully-qualified path to the Web.config file.
#Update Database on Microsoft Azure
For a Blazor application, in the Azure CLI, run the application with the -updateDatabase -silent
key.
#Update Database in Multi-Tenant Application
#Using –updateDatabase Switch for Blazor and WinForms Apps
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:
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:
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.