Unable to initialize/update EPiserver database with user secrets enabled

I suppose all of you know the importance of not storing secrets for connections to databases, APIs, identity providers etc. in the repositories alongside with the code. There are many ways to keep them away from the source code in .NET Core and in .NET Framework.

To avoid storing secrets in code for EPiserver, the user secrets feature can be leveraged (provided by Microsoft.Configuration.ConfigurationBuilders.UserSecrets NuGet package). However, there is an issue when upgrading/initializing Episerver database using Initialize-EPiDatabase and Update-EPiDatabase in the Visual Studio Package Manager when the UserSecrets package is referenced.

Enabling UserSecrets

UserSecrets can be enabled by right-clicking on the project in Visual Studio and then clicking Manage User Secrets. When it’s clicked for the first time, it prompts the additional NuGet packages to be installed. When approved, it installs Configuration.ConfigurationBuilders.UserSecrets NuGet package. After the package is installed, it creates an XML file under the %APPDATA% folder, opens it in Visual Studio for editing and references it in Web.config.

After installation of UserSecrets package, following entries are added into Web.config:

• Secrets config builder

  <configBuilders>
      <builders>
          <add name="Secrets" userSecretsFile="<path to secrets file>" type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.UserSecrets, Version=2.0.0.0, Culture=neutral" />
      </builders>
  </configBuilders>
  

• configBuilders="Secrets" attribute to appSettings section:

  <appSettings configBuilders="Secrets">
      ...
  </appSettings>
  

Problem

When UserSecrets is enabled in the project and you attempt to run either Update-EPiDatabase or Initialize-EPiDatabase, you will get the following error in the console:

epideploy.exe :
At C:\Development\EPiServer\Secrets\AlloySecrets\packages\EPiServer.Framework.11.16.0\tools\upgrade.psm1:263 char:3
+         &$epideploy  -a "sql" -s $sitePath  -p $sqlFilePattern -c  $c ...
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError
EPiDeploy was stopped due to an exception, more details:
System.Configuration.ConfigurationErrorsException: An error occurred loading a configuration file: Could not load file or assembly 'Microsoft.Configuration.ConfigurationBuilders.UserSecrets, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. 
The system cannot find the file specified. (C:\Development\EPiServer\Secrets\AlloySecrets\AlloySecrets\web.config line 21) ---> System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Configuration.ConfigurationBuilders.UserSecrets, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies.

Solution(s)

Even though I haven’t found a proper solution for this, there are two workarounds that allow to overcome the issue.

Disable secrets in appConfig section

Before running Update-EPiDatabase or Initialize-EPiDatabase commands, remove configBuilders="Secrets" from appSettings element and save Web.config file:

    <appSettings>
        ...
    </appSettings>

Once it’s done, run the update/initialize command and it should complete without any issues.

Update/initialize database on startup

The second solution is not using Update-EPiDatabase or Initialize-EPiDatabase commands but let the EPiserver deal with the database updates on startup by setting updateDatabaseSchema attribute on <episerver.framework> node in Web.config like this:

<episerver.framework updateDatabaseSchema="true">