Configure environments

Environment-specific configurations

When you deploy to a production environment, ensure 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 ecommerce 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.

Add 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 them based on the environment name by adding the specific configurations for the environments (integration, preproduction, production) where you want them to apply.

Identify 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.

Use 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                
}

Define site context

The following example defines and uses specific payment gateways and shipping methods for environments in an Optimizely Commerce (PaaS) 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 {
      get {
        return _environment;
      }
    }
  }

  public enum DxcEnvironment {
    Integration,
    Preproduction,
    Production
  }
}

Define 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 align with the enum defined in previous steps for easier matching.

Get 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);
}

🚧

Caution

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

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 the appsettings.Production.json and appsettings.Development.json files, the environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. 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, such as 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 environments.

Example:

1. The 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 displayed during the deployment. See Create a custom maintenance page for instructions on how to work with maintenance pages.

Related topics

• Configuration in ASP.NET Core
• Use multiple environments in ASP.NET Core
• appsettings.json Transformation Tester