---
title: Configure environments
slug: dxp/docs/environment-configurations
docTags: 
createdAt: 2026-07-30T20:33:07.109Z
---

## 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:

```csharp
var environment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")
```

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

```csharp
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.

```csharp
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

```csharp
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);
}
```

:::hint{type="warning"}
**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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-5.0).

`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](docId:2DexogTyynl8v4Zvz1jHH) for instructions on how to work with maintenance pages.

## Related topics

- [Configuration in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0#json-configuration-provider)
- [Use multiple environments in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-5.0)
- [appsettings.json Transformation Tester](https://elmah.io/tools/appsettings-transformation-tester/)