Usar vários ambientes no ASP.NET Core

Por Rick Anderson e Kirk Larkin

O ASP.NET Core configura o comportamento do aplicativo com base no ambiente de runtime usando uma variável de ambiente.

Ambientes

Para determinar o ambiente de runtime, o ASP.NET Core faza leitura das seguintes variáveis de ambiente:

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT quando o método WebApplication.CreateBuilder é chamado. Os modelos padrão de aplicativo web ASP.NET Core fazem a chamada de WebApplication.CreateBuilder. O valor DOTNET_ENVIRONMENT substitui ASPNETCORE_ENVIRONMENT quando WebApplicationBuilder é usado. Para outros hosts, como ConfigureWebHostDefaults e WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT tem precedência mais alta.

IHostEnvironment.EnvironmentName pode ser definido como qualquer valor, mas os seguintes valores são fornecidos pela estrutura:

• Development: o arquivo launchSettings.json define ASPNETCORE_ENVIRONMENT como Development no computador local.
• Staging
• Production: o padrão se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT não tiverem sido definidos.

O seguinte código:

• É semelhante ao código gerado pelos modelos de ASP.NET Core.
• Habilita a Página de Exceção do Desenvolvedor quando ASPNETCORE_ENVIRONMENT é definido Developmentcomo . Isso é feito automaticamente pelo método WebApplication.CreateBuilder.
• Chama UseExceptionHandler quando o valor de ASPNETCORE_ENVIRONMENT é algo diferente de Development.
• Fornece uma instância IWebHostEnvironment na propriedade Environment de WebApplication.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O Auxiliar de Marcação de Ambiente usa o valor de Incluir.EnvironmentName para incluir ou excluir a marcação no elemento:

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

A página Sobre do código de exemplo inclui a marcação anterior e exibe o valor de IWebHostEnvironment.EnvironmentName.

No Windows e no macOS, valores e variáveis de ambiente não diferenciam maiúsculas de minúsculas. Os valores e variáveis de ambiente do Linux diferenciam maiúsculas de minúsculas por padrão.

Criar EnvironmentsSample

O código de exemplo usado neste artigo baseia-se em um projeto do Razor Pages chamado EnvironmentsSample.

Os seguintes comandos da CLI do .NET criam e executam um aplicativo Web chamado EnvironmentsSample:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Ao executar o aplicativo, ele exibe uma saída semelhante à seguinte:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Definir o ambiente da linha de comando

Use o sinalizador --environment para definir o ambiente. Por exemplo:

dotnet run --environment Production

O comando anterior define o ambiente como Production e exibe uma saída semelhante à seguinte na janela de comando:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Desenvolvimento e launchSettings.json

O ambiente de desenvolvimento pode habilitar recursos que não devem ser expostos em produção. Por exemplo, os modelos do ASP.NET Core habilitam a Página de exceção do desenvolvedor no ambiente de desenvolvimento. Devido ao custo de desempenho, a validação de escopo e a validação de dependência só acontecem no desenvolvimento.

O ambiente de desenvolvimento do computador local pode ser definido no arquivo Properties\launchSettings.json do projeto. Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.

O arquivo launchSettings.json:

• É usado apenas no computador de desenvolvimento local.
• Não é implantado.
• Contém configurações de perfil.

O JSON a seguir mostra o arquivo launchSettings.json de um projeto Web ASP.NET Core chamado EnvironmentsSample criado com o Visual Studio ou dotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

O JSON anterior contém dois perfis:

• EnvironmentsSample: o nome do perfil é o nome do projeto. Como o primeiro perfil listado, esse perfil é usado por padrão. A chave "commandName" tem o valor "Project", portanto, o Kestrel servidor Web é iniciado.

• IIS Express: a chave "commandName" tem o valor "IISExpress", portanto, IISExpress é o servidor Web.

Você pode definir o perfil de inicialização do projeto ou qualquer outro perfil incluído no launchSettings.json. Por exemplo, na imagem abaixo, selecionar o nome do projeto inicia o Kestrel servidor Web.

O valor de commandName especifica o servidor Web a ser iniciado. commandName pode ser qualquer um dos seguintes:

• IISExpress: inicia IIS Express.
• IIS : nenhum servidor Web iniciado. Espera-se que o IIS esteja disponível.
• Project: inicia Kestrel.

A guia Depuração/Geral das propriedades de projeto do Visual Studio 2022 fornece um link da Interface do usuário Abrir perfis de inicialização de depuração. Esse link abre uma caixa de diálogo Iniciar Perfis que permite editar as configurações de variável de ambiente no arquivo launchSettings.json. Você também pode abrir a caixa de diálogo Iniciar Perfis no menu Depurar selecionando <o nome do projeto> Propriedades de Depuração. As alterações feitas nos perfis do projeto poderão não ter efeito até que o servidor Web seja reiniciado. O Kestrel precisa ser reiniciado antes de detectar as alterações feitas ao seu ambiente.

O arquivo launchSettings.json a seguir contém vários perfis:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Os perfis podem ser selecionados:

• Na interface do usuário do Visual Studio.

• Usando o comando dotnet run da CLI com a opção --launch-profile definida como o nome do perfil. Essa abordagem dá suporte apenas a perfis Kestrel.

  dotnet run --launch-profile "EnvironmentsSample"
  

Aviso

launchSettings.json não deve armazenar segredos. A ferramenta Secret Manager pode ser usado para armazenar segredos de desenvolvimento local.

Ao usar o Visual Studio Code, as variáveis de ambiente podem ser definidas no arquivo .vscode/launch.json. O exemplo a seguir define várias variáveis de ambiente para valores de configuração de host:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

O arquivo .vscode/launch.json é usado apenas pelo Visual Studio Code.

Produção

O ambiente de produção deve ser configurado para maximizar a segurança, o desempenho e a robustez do aplicativo. Algumas configurações comuns que são diferentes do desenvolvimento incluem:

• Cache.
• Recursos do lado do cliente são agrupados, minimizados e potencialmente atendidos por meio de uma CDN.
• Páginas de erro de diagnóstico desabilitadas.
• Páginas de erro amigáveis habilitadas.
• Log e monitoramento de produção habilitados. Por exemplo, usar o Application Insights.

Definir o ambiente definindo uma variável de ambiente

Geralmente, é útil definir um ambiente específico para teste com uma configuração de plataforma ou variável de ambiente. Se o ambiente não for definido, ele usará Production como padrão, o que desabilitará a maioria dos recursos de depuração. O método para configurar o ambiente depende do sistema operacional.

Quando o host é criado, a última configuração de ambiente lida pelo aplicativo determina o ambiente do aplicativo. O ambiente do aplicativo não pode ser alterado enquanto o aplicativo está em execução.

A página Sobre do código de exemplo exibe o valor de IWebHostEnvironment.EnvironmentName.

Serviço de aplicativo do Azure

Production será o valor padrão se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT não tiverem sido definidos. Os aplicativos implantados no Azure são Production por padrão.

Para definir o ambiente em um aplicativo do Serviço de Aplicativo do Azure usando o portal:

1. Selecione o aplicativo na página Serviços de Aplicativos.
2. No grupo Configurações, selecione Configuração.
3. Na aba Configurações do aplicativo, selecione Novas configurações do aplicativo.
4. Na janela Adicionar/Editar configuração do aplicativo , forneça ASPNETCORE_ENVIRONMENT o Nome. Para Inserir um valor, forneça o ambiente (por exemplo, Staging).
5. Marque a caixa de seleção Configuração do Slot de Implantação se desejar que a configuração do ambiente permaneça no slot atual quando os slots de implantação forem trocados. Para obter mais informações, consulte Configurar ambientes de preparo no Serviço de Aplicativo do Azure na documentação do Azure.
6. Selecione OK para fechar a caixa de diálogo Adicionar/Editar configuração do aplicativo .
7. Selecione Salvar na parte superior da página de Configuração.

O Serviço de Aplicativo do Azure reinicia automaticamente o aplicativo após uma configuração de aplicativo ser adicionada, alterada ou excluída no portal do Azure.

Windows – Definir variáveis de ambiente em um processo

Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.

Para definir o ASPNETCORE_ENVIRONMENT para a sessão atual quando o aplicativo for iniciado usando dotnet run, use os seguintes comandos em um prompt de comando ou no PowerShell:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Windows – Definir variável de ambiente globalmente

Os comandos anteriores são definidos como ASPNETCORE_ENVIRONMENT apenas nos processos iniciados nessa janela de comando.

Para definir o valor globalmente no Windows, use uma das seguintes abordagens:

• Abra o Painel de Controle>Sistema>Configurações avançadas do sistema e adicione ou edite o valor ASPNETCORE_ENVIRONMENT:

  

  

• Abra um prompt de comando administrativo e use o comando setx ou abra um prompt de comando administrativo do PowerShell e use [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    O comutador /M define a variável de ambiente no nível do sistema. Se o comutador /M não for usado, a variável de ambiente será definida para a conta de usuário.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    A opção Machine define a variável de ambiente no nível do sistema. Se o valor da opção for alterado para User, a variável de ambiente será definida para a conta de usuário.

Quando a variável de ambiente ASPNETCORE_ENVIRONMENT é definida globalmente, ela entra em vigor para dotnet run em qualquer janela de comando aberta depois que o valor é definido. Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.

Windows – Usar web.config

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT com web.config, consulte a seção Definindo variáveis de ambiente do arquivo de configuração web.config.

Windows - Implantações de IIS

Inclua a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no arquivo de projeto. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT de um aplicativo em execução em um Pool de Aplicativos isolado (compatível com IIS 10.0 ou posterior), consulte a seção Comando AppCmd.exe do tópico Variáveis de ambiente <environmentVariables>. Quando a variável de ambiente ASPNETCORE_ENVIRONMENT é definida para um pool de aplicativos, seu valor substitui uma configuração no nível do sistema.

Ao hospedar um aplicativo no IIS e adicionar ou alterar a variável de ambiente ASPNETCORE_ENVIRONMENT, use qualquer uma das abordagens a seguir para que o novo valor seja escolhido pelos aplicativos:

• Execute net stop was /y seguido por net start w3svc em um prompt de comando.
• Reinicie o servidor.

macOS

A configuração do ambiente atual para macOS pode ser feita em linha ao executar o aplicativo:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Como alternativa, defina o ambiente com export antes de executar o aplicativo:

export ASPNETCORE_ENVIRONMENT=Staging

As variáveis de ambiente no nível do computador são definidas no arquivo .bashrc ou .bash_profile. Edite o arquivo usando qualquer editor de texto. Adicione a seguinte instrução:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Em distribuições Linux, use o comando export no prompt de comando nas configurações de variáveis baseadas na sessão e o arquivo bash_profile nas configurações de ambiente no nível do computador.

Definir o ambiente no código

Para definir o ambiente no código, use WebApplicationOptions.EnvironmentName ao criar WebApplicationBuilder, conforme mostrado no exemplo a seguir:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Configuração por ambiente

Para carregar a configuração por ambiente, consulte Configuração no ASP.NET Core.

Configurar serviços e middleware por ambiente

Use WebApplicationBuilder.Environment ou WebApplication.Environment para adicionar condicionalmente serviços ou middlewares, dependendo do ambiente atual. O modelo de projeto inclui um exemplo de código que adiciona middlewares somente quando o ambiente atual não é o de Desenvolvimento:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código realçado verifica o ambiente atual durante a criação do pipeline de solicitação. Para marcar o ambiente atual ao configurar serviços, use builder.Environment em vez de app.Environment.

Recursos adicionais

• Exibir ou baixar código de exemplo (como baixar)
• Inicialização de aplicativo no ASP.NET Core
• Configuração no ASP.NET Core
• Ambientes Blazor do ASP.NET Core