Try our conversational search powered by Generative AI!

AI OnAI Off

Updating configuration and database schemas

This document describes how to manage configuration and database updates when updating Episerver using NuGet updates. Refer to Installing Episerver updates for information on how to update Episerver through NuGet. From versions 7.6 and higher, changes to configuration and database schemas are managed as transformation files when updating.

The EPiServer packages

The EPiServer NuGet updates consist of a set of packages for different parts of the platform, with dependencies between them. The NuGet Package Manager displays the dependency information for each package. When installing a package, the dependent packages are also installed. All updates are cumulative meaning that the latest update always include previous updates.

When new updates are released, the affected packages are listed on Episerver World. If you do not have any EPiServer NuGet packages installed, you can install the package EPiServer.CMS to get the latest version of all packages for Episerver CMS. Similar packages are available for other products such as EPiServer.Commerce for the Commerce product.

The transformation files

When Episerver makes changes to the configuration schema or the database schema, those changes are incorporated into the NuGet package as transformation files. The transformation syntax for configuration files is XDT (XML Document Transform) and the transformation syntax for database schema are ordinary SQL files.

Both types of transformation files are cumulative and can be executed on any version of an installed product, each file has logic to make sure it only runs when required. The transformation files are stored in the folder tools/epiupdates folder for each package (you can find all installed packages in the packages/ folder in the root folder of the Visual Studio solution). Transformation files have to be executed in order. Since keeping track of these files and running them may be tedious work performed at regular intervals, a set of tools are provided as described below.

The database schema transformation files are also included as embedded resources in the assemblies to allow for automatic updates from versions EPiServer.CMS.Core 8.7.0 and EPiServer.Commerce.Core 8.13.0.

Applying configuration transforms

Configuration transforms are applied automatically when updating a package so you only have to run this command if you for some reason want to re-apply configuration transforms or validate that all transforms were correctly applied:

  1. Open Package Manager Console.
  2. Make sure "Default project" points to the website.
  3. Write Update-EPiConfig in the console and press Enter.
  4. All configuration transforms are now applied.

Applying database schema transforms

Database schema transforms can be configured to run automatically as described in Automatic schema updates or applied manually (to avoid unintentional changes) when updating a package. Make sure you have a backup of the database before applying the update.

Automatic schema upgrade

By default, automatic schema updates are disabled. To enable them, add attribute updateDatabaseSchema="true" to the episerver.framework element in configuration. When the site starts up, Episerver compares the assembly version and the database version. If the database version is lower than the assembly version and automatic updates are enabled, it applies the sql schema updates (they are packed as embedded resources in the assembly).

Manual schema upgrade

The Update-EPiDatabase automatically detects all install packages that support the pattern for transformation used by Episerver and applies them against the configured database. Below are the steps to manually apply the database schema changes.

  1. Open Package Manager Console.
  2. Make sure "Default project" points to the website.
  3. Write Update-EPiDatabase in the console and press Enter.
  4. All configuration transforms are now applied.

Note: The database user connecting to SQL Server must be granted access to perform schema changes on the database. Members of the db_owner fixed database role can perform all configuration and maintenance activities on the database, including schema changes.

Applying transforms to a production environment

The recommended approach is that you re-deploy the whole site with updated files (including configuration files). Use configSource to split configuration into multiple files to avoid overwriting production-specific configuration when deploying new changes.

If automatic schema updates are enabled in the production environment, then the production database schema is upgraded when new assembly versions are deployed to production site. When automatic schema updates are not enabled, then database schema changes can be deployed using the following steps:

  1. Open Package Manager Console.
  2. Make sure "Default project" points to the website.
  3. Write Export-EPiUpdates and press Enter.
  4. Copy the exported files to the production machine (the path to the exported files should be obvious from the log messages).
  5. On the production machine: Open a command prompt as Administrators and execute update.bat c:\inetpub\mysite. The update.bat is just a simple readable batch file that executes the different transforms on a specific site. By default, only SQL transformations are executed, see note below.

Note: Although best practice is re-deploying configuration files to get the latest schema changes, it is also possible to run configuration transforms directly on a production configuration; use Export-EPiUpdates -Action sql,config to generate commands that execute both database and configuration transforms. Be aware that other changes made by NuGet, such as assembly redirects, are not applied so some manual steps are required unless you add custom transforms yourself.

Troubleshooting - under the covers of transforms

You can run transformations manually one-by-one or edit the update.bat file generated in the previous example to remove or include additional items. Transformations are applied using a command line tool epideploy.exe (available in the tools folder of the EPiServer.Framework NuGet package).

If you use the -Verbose switch with the cmdlets in Visual Studio, such as Update-EPiDatabase -Verbose:$true, you can see the actual command line parameters sent to epideploy.exe and view debug output printed to the console, for example:

epideploy.exe -a sql -s C:\inetpub\Solution\EPiServerSite -p C:\Solution\packages\EPiServer.CMS.Core.7.6.0\tools\epiupdates\* -c EPiServerDB

This command runs the action sql on the site C:\inetpub\Solution\EPiServerSite and scans for transformations in C:\Solution\packages\EPiServer.CMS.Core.7.6.0\tools\epiupdates\*, and then applies it to the database specified in the connection string EPiServerDB. If you add the -d true switch, it also prints additional debug information which can be useful in troubleshooting scenarios.

Run epideploy.exe without any parameters to see a full description of all options available.

Configure for CMS 12

The previous in Visual Studio (.NET Framework) .csproj model let you embed PowerShell with NuGet packages. You cannot do this in the new .csproj project model that is used for .NET Core projects.

For CMS 12, configure the following.

DataAccessOption.UpgradeDatabaseSchema = true

This is also the default value. Then the CMS application upgrades database schema automatically.

If you want or need to manually run the updates, unpack the NuGet packages EPiServer.Framework and EPiServer.CMS.Core.

If the packages are installed on a machine, you can find them in NuGet cache. The upgrade files are found in the EPiServer.CMS.Core package, such as:

C:\Users\jb\.nuget\packages\episerver.cms.core\12.19.0\tools\epiupdates\sql

There is also a CLI tool epideploy.exe available in the EPiServer.Framework package to execute the update files, as:

C:\Users\jb\.nuget\packages\episerver.framework\12.19.0\tools\epideploy.exe

See also