Last updated: Oct 11 2018

Area: Episerver DXC Service Applies to versions: Not applicable

Environment configurations

This topic describes various environment-specific configuration options in Episerver Digital Experience Cloud Service, for example to restrict access, or to apply specific configurations or configuration transforms, when deploying.

In this topic

Environment-specific configurations

When deploying to a production environment, you should always ensure that the correct configurations are applied. You should never use credentials, tokens or endpoints from a Preproduction environment, in Production. Environment-specific configurations are also useful if you have an e-commerce site with payment provider methods that you do not want to run in a test environment, or if you want to apply specific log rules for an environment.

Adding the configuration

Add the environment-specific configuration in web.config for your web application. Alternatively, the settings can be stored in the database and retrieved based on environment name. You need to add the specific configurations for all the environments (integration, preproduction, production) where you want them to apply.

Note: See the Azure portal to identify the environment names, see Accessing Azure information to get access.

Identifying the environment

To apply a specific configuration, you need to identify the environment name at runtime using episerver:EnvironmentName. The defined name for each environment setting can be retrieved from Application settings in Azure Portal.

Add the configuration for each environment requiring a specific configuration.

Using the configuration

To apply a specific configuration and identify the environment at runtime, use the following code:


Applying this where needed will pick the correct configuration for the running environment. 

var appSettings = ConfigurationManager.AppSettings;
var environmentName = appSettings["episerver:EnvironmentName"];
if (environmentName == null || environmentName.Equals("Integration"))
    // TODO: use Integration configuration parameters
else if (environmentName.Equals("Preproduction"))
    // TODO: use Preproduction configuration parameters
else if (environmentName.Equals("Production"))
    // TODO: use Production configuration parameters                

Defining site context

This example shows how to define and use specific payment gateways and shipping methods for environments in an Episerver Commerce solution based on Digital Experience Cloud (DXC).

Create a class to act as a global context for the site.

using EPiServer.ServiceLocation;
using System;
using System.Configuration;
namespace EPiServer.DxcSite
    [ServiceConfiguration(Lifecycle = ServiceInstanceScope.Singleton)]
    public class DxcApplicationContext
        private DxcEnvironment _environment;
        public DxcApplicationContext()
            var setting = ConfigurationManager.AppSettings.Get("DXCEnvironment");
            if(!Enum.TryParse<DxcEnvironment>(setting, true, out _environment))
                //Default environment is integration;
                _environment = DxcEnvironment.Integration;
        public DxcEnvironment CurrentEnvironment
                return _environment;
    public enum DxcEnvironment

Defining environment-specific payment gateways and shipping methods

Currently, the best way to separate payment gateways and shipping methods is to use a specific prefix for their system names. For example, you can set Integration- for the payment gateways and shipping methods used in Integration, Preproduction- for Preproduction and so on. The prefix should be in line with the enum defined in previous steps, for easier matching.

Getting payment gateways and shipping methods

public IEnumerable<ShippingMethodDto.ShippingMethodRow> FilterShippingMethods(ShippingMethodDto dto)
    var environment = ServiceLocator.Current.GetInstance<DxcApplicationContext>().CurrentEnvironment;
    return dto.ShippingMethod.Select().Where(c => c["Name"].ToString().StartsWith(environment.ToString(), StringComparison.OrdinalIgnoreCase))
        .Select(c => (ShippingMethodDto.ShippingMethodRow)c);

Note: The code which displays the shipping method name to the user in the production environment might need modification to remove the prefix part.

Configuration transforms

DXC Service supports the use of configuration transforms to be able to make changes to .config-files when deploying between environments. Note that even though the example below is for a web.config file, DXC Service supports this feature on any *.config file as long as the transform file follows the naming convention (OriginalFileName.episerver:EnvironmentName.config) described below.

Adding transform files

Add a file called Web.episerver:EnvironmentName.config (see Identifying the environment for naming conventions) at the same level/folder as the web.config file you want to transform. If you have Web.config files at multiple levels/folders that needs transformation, just make sure you add a transform file next to each one.

The "episerver:EnvironmentName"-part should correspond to the value of the application setting with the same name of the target environment for the deployment. For example, to apply a transformation file to Web.config when deploying to the Preproduction environment, you add a file called Web.Preproduction.config that contains the transformation you need.

Note: Be aware that if you need to do configuration transforms in multiple environments (for example both Preproduction and Production), you need to add multiple transformation files. These will all be applied one after the other as the deployment moves towards the production environment.


  1. The application is deployed to the Integration environment. It contains a web.config for that environment (no transformation is done in Integration), a web.Preproduction.config and a web.Production.config.
  2. The application is deployed to Preproduction and the web.Preproduction.config transformation file is applied to the web.config used in Integration, creating a new Web.config in Preproduction.
  3. The application gets deployed to Production, and the Web.Production.config file gets applied to the Web.config from Preproduction.

The Production web.config is therefore the result of both web.Preproduction.config and web.Production.config being applied to the original web.config file that was used in the Integration environment. The transformation files need to follow the syntax described in Web.config Transformation Syntax (Microsoft)

To make this work from Visual Studio you need to make sure you add the transformation files as content files so they are actually deployed together with the rest of the site.

Adding transform files for Commerce Manager link

When deploying Commerce Manager between different environments, the link will remain the same across these. Therefore in some cases it will be pointing to the wrong one. As previously explained, you have the possibility to use transform files, which will take care of updating Commerce Manager links specifically for each environment.

For example, for deploying to Preproduction a transform file could look like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
		<add key="CommerceManagerLink" value="{LinkToCommerceManager}" xdt:Transform="SetAttributes" xdt:Locator="Match(key)" />

Custom maintenance page

During deployments where the site needs to be taken offline, you have the option to add a custom maintenance page that will be displayed during the deploy. See Custom maintenance page how to work with maintenance pages.

Related topics

Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/