Manage the configurations

Your Sitefinity Cloud website is configured in a Continuous Delivery (CD) pipeline setup. This way, code changes are deployed to non-Production environments like Staging first, and then to Production. In such setup, the code base does not change, but your website configurations may need to vary to reflect different environment settings, such as connection strings and SMTP settings.

This option is best suited for configuration changes that do not vary from one environment to another and do not contain any values that must be secret (for example, API keys, secrets or passwords).

You can apply the changes through the Advanced Settings of Sitefinity backend on your local development environment, or by directly editing the files on the file system.
Only configuration values that are different from the default ones will be persisted on the file system. If you want to make changes to a configuration that does not exist on the file system yet, it is best to edit the values through the Advanced Settings screen. Sitefinity ensures that the config file on the file system is created and the values that differ from the default ones are persisted there.

If a new config file is created on the file system because of your changes, make sure that the file is included in the project. Files that are not included in the project will not get deployed, because of the way the publish command of MSBuild works.
To include files in the project, use the Show All Files option in the Visual Studio File Explorer, then right-click on the file and select Include In Project.

This option is best suited for configuration changes that need to vary from one environment to another and do not contain any values that must be secret (for example, API keys, secrets or passwords).

The configuration transformation files must:

• follow the naming pattern {configuration file name}.{environment name}.config, where {environment name} does not contain any whitespaces;
• be located in the same folder as the original configuration file;
• be included in the project.
  Files that are not included in the project will not get deployed, because of the way the publish command of MSBuild works. To include files in the project, use the Show All Files option in the Visual Studio File Explorer, then right-click on the file and select Include In Project.

For more information about configuration transformation files, see Microsoft documentation » Web.config File Transformations.

This option is best suited for configuration values that must be secret (for example, API keys, secrets or passwords).

This approach takes advantage of the ability for configuration values to be overridden by App Settings. Specifying the path to the configuration value (sf-env:pathToConfigurationProperty) as key and the value as value forces Sitefinity to override the existing value for this configuration. This takes precedence over any other value that is set in the file system or the Database. The value becomes immutable and is not displayed in the Advanced Settings screen, which makes it perfect for storing secrets.

Sitefinity Cloud uses Azure DevOps variable groups to allow customers to specify the App Settings and Connection Strings that must be configured in the Azure App Service on deployment. These App Settings and Connection Strings override the existing ones in the web.config and appsettings.json files.

Settings transformation

To create custom app settings for different environments, perform the following:

1. Login to Sitefinity Cloud Management Portal.
2. Navigate to Pipelines » Library.
3. Open Custom <Environment name> AppSettings variable group.
   
4. For each setting, fill out the following:
   
   • Key - the path to the configuration property (sf-env:pathToConfigurationProperty)
     For more information about finding out the path to the property, see Manage configurations in Continuous delivery pipeline.
     
   • Value - the required configuration setting value
     In case you want to use Key Vault secrets for the value, enter the name of the secret using this pattern: $(<NameofSecretinKeyVault>)
     Secrets can also be used for parts of the value and you can use multiple secrets in one value:
     DefaultEndpointsProtocol=https;AccountName=$(MediaLibraryStorageName);AccountKey=
     $(MediaLibraryStorageKey)
     
     For information about using Key Vault secrets, see Azure Key Vault.

NOTE: If you want your app settings to apply for all environments, add the settings in Custom Release AppSettings variable group.

Connection strings transformations

To create different connection strings for different environments, perform the following:

1. Login to Sitefinity Cloud Management Portal.
2. Navigate to Pipelines » Library.
3. Open Custom <Environment name> ConnectionStrings variable group.
4. For each string, fill out its Key and Value.
   In case you want to use Key Vault secrets for the value, enter the name of the secret using this pattern: $(<NameofSecretinKeyVault>)
   Secrets can also be used for parts of the value and you can use multiple secrets in one value:
   data source=tcp:$(SqlServerName).database.windows.net,1433;User ID=$(SqlServerUserName);
   Password=$(SqlServerPassword);initial catalog=$(DatabaseName);Persist Security Info=False;
   MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection
   Timeout=30;Backend=SqlAzure;SF_ignoreDowngradeExceptions=true;
   
   For information about using Key Vault secrets, see Azure Key Vault.

NOTE: If you want your connection strings to apply for all environments, add the settings in Custom Release ConnectionStrings variable group.

Settings transformation for .NET Core Renderer

To utilize app settings transformations, the .NET Core Renderer application uses the approach of configuring the app settings in the Azure App Service, which override the ones in the appsettings.json file.

To create custom app settings for different environments, perform the following:

1. Login to Sitefinity Cloud Management Portal.
2. Navigate to Pipelines » Library.
3. Open Custom DotNetCoreRenderer <Environment name> AppSettings variable group.
4. For each setting, fill out the following:
   • Key - the required configuration setting key
   • Value - the required configuration setting value

NOTE: Because the .NET Core Renderer Application is deployed on Linux Web Apps, any nested JSON key structure in the app setting name, such as ApplicationInsights:InstrumentationKey needs to be configured in App Service as ApplicationInsights__InstrumentationKey for the key name. The convention is that each : (colon) must be replaced with __ (double underscore).

NOTE: If you want your app settings to apply for all environments, add the settings in Custom Release DotNetCoreRenderer AppSettings variable group.

This option is best suited for runtime configuration changes that do not contain any values which must be secret (for example, API keys, secrets or passwords).

To facilitate the need for easily changing runtime configuration through the Advanced Settings screen, Sitefinity Cloud customers who have upgraded to Sitefinity version 14.3.8022 (or higher) can take advantage of enhanced configuration editing capabilities. These capabilities allow you to specify which configurations, sections, or properties should be made fully editable on Sitefinity Cloud environments.
As part of the Sitefinity Cloud deployment process, some configuration files are included in a dedicated list and are made editable out-of-the-box. The current list includes the configuration file for Sitefinity Insight, which makes it editable through the Advanced Settings screen.

To make a configuration, section or property fully editable on Sitefinity Cloud environments, you need to add it to the SiteSpecificProperties list of the SiteSettings config on your local environment and deploy the changes.

NOTE: This functionality was available prior to Sitefinity version 14.3.8022, but the editing capabilities in the Advanced Settings screen were not complete. For example, there was no option to add configuration items to a list, which is now available. The config files that are not editable are no longer visible on the user interface. 

Perform the following:

1. Navigate to the Advanced Settings screen on your local development environment.
2. Expand SiteSettings » SiteSpecificProperties and click Create new.
3. Using Path, you scope what part of the config you want to be editable.
   For example, entering:
   
   • toolboxesConfig makes the whole Toolboxes config editable
   • toolboxesConfig/toolboxes/PageControls makes only the PageControls section editable
   • toolboxesConfig/toolboxes/PageControls:title makes only the Title property editable
     
4. Enable the AllowPerSite checkbox only when your custom configuration supports this setting.
   The AllowPerSite setting allows you to specify whether the configuration file must be editable separately for each multisite website, or it should have one version for all multisite websites. The out-of-the-box Sitefinity configurations do not support AllowPerSite, if enabled. For more information, see Site-specific settings.
5. Save your changes.

Below is an example when the PageControls section of the Toolboxes config is made editable.

NOTE: If you restore the Database from one environment to another (DB.RestoreBetweenEnvironments pipeline) or import a Database (DB.Import pipeline), the default option is to persist Sitefinity config values on the target environment. This means that Sitefinity config values that are stored on the target Database will NOT be replaced with the ones from the source Database. If you want to override the configurations on the target environment, you can disable this option when you run the pipeline.