HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Environment Configurations

This topic describes various environment-specific configuration options in Optimizely Digital Experience Platform (DXP), such as restricting access, or applying specific configurations or configuration transforms, when deploying.

Environment-specific configurations

When you deploy to a production environment, ensure that the correct configurations are applied. In a Production environment, you should never use credentials, tokens, or endpoints from a Preproduction environment.

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 appSettings.json for your web application. Alternatively, you can store the settings in the database and retrieve the settings based on environment name by adding the specific configurations for the environments (integration, preproduction, production) where you want them to apply.

Identifying the environment

To apply a specific configuration, you need to identify the environment name at runtime using ASPNETCORE_ENVIRONMENT variable. 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:

var environment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")

Applying this where needed picks the correct configuration for the running environment.

var environmentName = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT");
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

The following example defines and uses specific payment gateways and shipping methods for environments in an Optimizely Commerce solution based on Optimizely Digital Experience Platform (DXP).

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 = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT");
            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(),
        .Select(c => (ShippingMethodDto.ShippingMethodRow)c);



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

Events and BLOB providers

You need to change some configurations for the website to work with Azure. The container attribute for the BLOB provider and topic for the event provider should be unique per site, within the same storage or service bus account. Therefore you need to update the mapping for BLOBs and event providers.



Do not skip this step! If you do skip this step, assets are stored locally, and will not deploy properly to the Azure BLOB storage.



Adding Custom Application Settings and/or Custom Connection Strings is supported only through client code. Optimizely DXP does not support custom settings within the Azure Portal.

  1. In Visual Studio, open Startup file and add the following.

    Do not change the values for connectionStringName, because these are overwritten with the correct environment-specific values during deployment. Optionally, you can change the container and topic names mysitemedia and MySiteEvents to names of your choice on AzureBlobProviderOptions. and AzureEventProviderOptions. The storage container name must be in lowercase, for example mysitemedia, for DNS compatibility.

public void ConfigureServices(IServiceCollection services)



For later releases of EPiServer.CloudPlatform.Cms, you must use services.AddCmsCloudPlatformSupport(_config) and services.AddCommerceCloudPlatformSupport() to correctly set up configurations for CMS and Commerce respectively.

  1. Compile the solution (Build > Build Solution) and run it.



Your local site displays an error message because the site is pointing to Azure after the configuration changes. This is corrected when you publish the project to Azure.



When you deploy a website, you may want settings in the deployed application's appSettings.json to be different from your local_development _appsettings.json. Instead of changing these settings for your local installation (as done here), you can apply a transformation of the appSettings.json file when you deploy to Azure to avoid breaking your local site.

Configuration transforms

DXP supports the use of configuration transforms to make changes to appSettings.json when deploying between environments.

The default JsonConfigurationProvider loads configuration in the following order:

  1. appSettings.json
  2. appSettings.Environment.json
    For example, the appSettings.Production.json and appSettings.Development.json files. The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. For more information, see Use multiple environments in ASP.NET Core.

appSettings.Environment.json values override keys in appSettings.json. For example, by default:

  • In development, appSettings.Development.json configuration overwrites values found in appSettings.json.
  • In production, appSettings.Production.json configuration overwrites values found in appSettings.json. For example, when deploying the app to Azure.

Code package configuration transform

The base configuration file is taken from the code package and transformations are applied to all environments.


  1. Code package is uploaded to Optimizely storage. It contains web.config, appSettings.Integration.json, appSettings.preproduction.json and appSettings.production.json.
  2. The application is deployed to the Integration environment. Use appSettings.json  as a base for transformations which a appSettings .Integration.json are applied to override the base configuration.
  3. The application is deployed to Preproduction and the appSettings .preproduction.json transformation file is applied to appSettings .json from the code package,  overriding the base configuration.
  4. The application gets deployed to Production, and the appSettings .production.json file gets applied to appSettings .json from the code package, overriding the base configuration.

Custom maintenance page

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

Related topics

Did this page help you?