ASP.NET Ambientes de tempo de execução principais

ASP.NET Core configura o comportamento do aplicativo com base no ambiente de tempo de execução, que geralmente reflete onde o aplicativo está sendo executado.

Os aplicativos geralmente são executados no ambiente de desenvolvimento durante o desenvolvimento local e os testes na máquina de um desenvolvedor com um conjunto de comportamentos configurados. Por outro lado, eles são executados no ambiente de produção quando implantados em um servidor com um conjunto diferente de comportamentos configurados. Qualquer número de ambientes adicionais pode ser usado, como o ambiente de preparo fornecido pela estrutura para preparar um aplicativo antes da implantação ao vivo ou outros ambientes criados pelos desenvolvedores.

Este artigo descreve ambientes de tempo de execução do aplicativo, como usar o ambiente para controlar o comportamento do aplicativo e como definir o ambiente.

Para Blazor obter orientações sobre ambientes, que adicionam ou substituem a orientação neste artigo, consulte Ambientes ASP.NET CoreBlazor.

Environments

Embora o ambiente possa ser qualquer valor de cadeia de caracteres, os seguintes valores de ambiente são fornecidos pela estrutura:

• Development
• Staging
• Production

O ambiente de produção é configurado para maximizar a segurança, o desempenho e a confiabilidade do aplicativo. As configurações comuns do desenvolvedor que diferem do ambiente de desenvolvimento incluem:

• Ativar caching.
• Agrupar e minimizar os recursos do lado do cliente e potenciamente disponibilizá-los a partir de uma CDN.
• Desativar páginas de erro de diagnóstico e ativar páginas de erro amigáveis.
• Habilitando o registro e o monitoramento da produção. Por exemplo, o registo de logs está ativado para o Azure Application Insights.

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 estiver em execução.

Exploração Florestal

A saída na linha de comandos de uma aplicação em execução no arranque indica o ambiente da aplicação. No exemplo a seguir, o aplicativo está sendo executado no ambiente de preparo:

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Variáveis de ambiente que determinam o ambiente de tempo de execução

Para determinar o ambiente de tempo de execução, ASP.NET Core lê as seguintes variáveis de ambiente:

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Ao usar WebApplication, o valor de DOTNET_ENVIRONMENT tem precedência sobre ASPNETCORE_ENVIRONMENT. Ao usar WebHost, ASPNETCORE_ENVIRONMENT tem precedência.

Se as DOTNET_ENVIRONMENT variáveis e ASPNETCORE_ENVIRONMENT de ambiente não estiverem definidas, o ambiente de produção será o ambiente padrão.

No Windows e no macOS, os nomes das variáveis de ambiente não diferenciam maiúsculas de minúsculas. As variáveis de ambiente do Linux são sensíveis a maiúsculas e minúsculas.

Controle a execução do código por ambiente

Utilize WebApplicationBuilder.Environment ou WebApplication.Environment para adicionar condicionalmente serviços ou middleware, dependendo do ambiente atual.

O seguinte código no ficheiro Program do aplicativo:

• Usa WebApplication.Environment para distinguir o ambiente.
• Chama UseExceptionHandler, que adiciona o Middleware de Tratamento de Exceções ao pipeline de processamento de solicitações para lidar com exceções.
• Chama UseHsts, que adiciona Middleware HSTS para aplicar o Strict-Transport-Security cabeçalho.

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

O exemplo anterior verifica o ambiente atual para o pipeline de processamento de solicitação. Para verificar o ambiente atual durante a configuração de serviços, use builder.Environment em vez de app.Environment.

Dentro do aplicativo, o IHostEnvironment fornece informações gerais sobre o ambiente de hospedagem do aplicativo e a IHostEnvironment.EnvironmentName propriedade indica o ambiente atual do aplicativo.

Controlar o conteúdo renderizado

Injete IHostEnvironment num componente Razor renderizado pelo servidor e utilize os métodos de extensão do serviço e a propriedade EnvironmentName para determinar o ambiente para renderizar o conteúdo:

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Para Blazor Web Apps que exigem que o ambiente controle a renderização do lado do cliente, consulte pré-renderização de componentes ASP.NET CoreRazor.

Definir o ambiente em um shell de comando quando o aplicativo é executado (dotnet run)

Use a -e|--environment opção para definir o ambiente:

dotnet run -e Staging

Definir o ambiente com o arquivo de configurações de inicialização (launchSettings.json)

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

O ficheiro launchSettings.json

• É usado apenas na máquina de desenvolvimento local.
• Não é implementado quando a aplicação é publicada.
• Pode conter vários perfis, cada um configurando um ambiente diferente.

O exemplo a seguir define o ambiente de preparo para o https perfil de inicialização usando a ASPNETCORE_ENVIRONMENT variável de ambiente:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

No Visual Studio, há duas abordagens para definir o ambiente por meio de perfis de inicialização:

• Pressione Alt+Enter ou selecione Propriedades depois de clicar com o botão direito do mouse no projeto no Gerenciador de Soluções. Selecione Debug>General, seguido de selecionar o link Open debug launch profiles UI .

• Com o projeto selecionado no Gerenciador de Soluções, selecione {NOME DO PROJETO} Propriedades de depuração no menu Depurar , onde o espaço reservado {PROJECT NAME} é um nome de projeto.

As abordagens anteriores abrem a caixa de diálogo Perfis de Lançamento, onde é possível editar as configurações da variável de ambiente no arquivo launchSettings.json. As alterações feitas nos perfis do projeto podem não ter efeito até que o servidor Web seja reiniciado. Kestrel deve ser reiniciado antes que ele possa detetar alterações feitas em seu ambiente.

Os perfis podem ser selecionados na interface do usuário do Visual Studio ao lado do botão Iniciar (►).

Quando uma solução contém vários projetos, defina apenas o ambiente para o projeto de inicialização.

Como alternativa, use o dotnet run comando com a -lp|--launch-profile opção definida para o nome do perfil. Esta abordagem suporta apenas perfis de inicialização com base no Project comando.

dotnet run -lp "https"

Ao usar o Visual Studio Code com o C# Dev Kit for Visual Studio Code (Introdução ao C# no VS Code), os perfis de inicialização são coletados do arquivo do aplicativo launchSettings.json .

Caso não se use o C# Dev Kit, defina a variável de ambiente ASPNETCORE_ENVIRONMENT na seção .vscode/launch.json, juntamente com outras quaisquer variáveis de ambiente definidas na seção env.

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

Definir o ambiente com uma variável de ambiente

Muitas vezes, é útil definir um ambiente específico para teste com uma variável de ambiente ou configuração de plataforma. Se o ambiente não estiver definido, o padrão será o ambiente de produção, que desabilita a maioria dos recursos de depuração. O método para definir o ambiente depende do sistema operacional.

Serviço de Aplicações do Azure

Os aplicativos implantados no Serviço de Aplicativo do Azure adotam o ambiente de Produção por padrão.

Para definir a variável de ASPNETCORE_ENVIRONMENT ambiente, consulte os seguintes recursos na documentação do Azure:

• Configurar uma aplicação do Serviço de Aplicações
• Configurar ambientes de preparo no Serviço de Aplicativo do Azure

O Serviço de Aplicativo do Azure reinicia automaticamente o aplicativo depois que uma configuração de aplicativo é adicionada, alterada ou excluída.

Definir variável de ambiente para um processo

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT para a sessão atual (linha de comandos) quando o aplicativo for iniciado usando dotnet run, use os seguintes comandos. Depois que a variável de ambiente é definida, o aplicativo é iniciado sem um perfil de inicialização usando a --no-launch-profile opção.

1. No shell de comando, defina a variável de ambiente usando a abordagem apropriada para seu sistema operacional.

2. Execute o dotnet run comando sem usar um perfil de inicialização:

   dotnet run --no-launch-profile
   

Ao usar o PowerShell, as etapas anteriores podem ser combinadas nos dois comandos a seguir. O exemplo a seguir define o ambiente de preparo:

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

Definir variável de ambiente globalmente

Use a orientação apropriada para seu sistema operacional para definir a variável de ASPNETCORE_ENVIRONMENT ambiente.

Quando a ASPNETCORE_ENVIRONMENT variável de ambiente é definida globalmente, ela entra em vigor para o dotnet run comando em qualquer shell de comando aberto depois que o valor é definido. Os valores de ambiente definidos pelos perfis de inicialização no launchSettings.json arquivo substituem os valores definidos para o ambiente do sistema.

Definir o ambiente para aplicativos implantados no IIS

Para definir a ASPNETCORE_ENVIRONMENT variável de ambiente com o web.config ficheiro, consulte o ficheiro web.config.

Para definir a variável de ambiente na implantação para o IIS, inclua a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no arquivo de projeto. O exemplo a seguir configura o ambiente em web.config para o ambiente de preparação quando o projeto é publicado.

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Para definir a ASPNETCORE_ENVIRONMENT variável de ambiente para um aplicativo em execução em um Pool de Aplicativos isolado (com suporte no IIS 10.0 ou posterior), consulte Variáveis <de ambiente environmentVariables>. Quando a ASPNETCORE_ENVIRONMENT variável de ambiente é 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 ASPNETCORE_ENVIRONMENT variável de ambiente, use uma das seguintes abordagens para que o novo valor entre em vigor para executar aplicativos:

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

Docker

Defina o ambiente do aplicativo usando qualquer uma das abordagens nesta seção.

Usar um Dockerfile

Defina a ASPNETCORE_ENVIRONMENT variável de ambiente dentro do Dockerfile usando a ENV instrução:

ENV ASPNETCORE_ENVIRONMENT=Staging

Usar o Docker Compose

Para aplicativos multisserviço gerenciados com o Docker Compose, defina ASPNETCORE_ENVIRONMENT variáveis de ambiente dentro do docker-compose.yml arquivo:

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Um ambiente definido em tempo de execução com o Docker Compose substitui um ambiente definido pelo Dockerfile.

Use o comando docker run

Ao executar o contêiner do Docker com o docker run comando, defina a variável de ASPNETCORE_ENVIRONMENT ambiente com a -e|--env opção:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Um ambiente definido em tempo de execução docker run substitui um ambiente definido pelo Dockerfile.

Arquivo de ambiente do Docker

Defina a variável de ASPNETCORE_ENVIRONMENT ambiente usando um arquivo de ambiente do Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Carregue o arquivo com a --env-file opção ao executar o docker run comando:

docker run --env-file ./env_variables.env aspnet_core_image

Um ambiente definido em tempo de execução docker run substitui um ambiente definido pelo Dockerfile.

Definir o ambiente no código de inicialização do aplicativo

Para configurar 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
}); 

Carregar configuração por ambiente

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

Acessar o ambiente a partir de uma Startup classe

O uso de uma Startup classe (Startup.cs) com Configure e ConfigureServices métodos era necessário antes do lançamento do .NET 6 e permanece com suporte.

Injete IWebHostEnvironment no construtor para controlar a execução do Startup código. Essa abordagem é útil quando o aplicativo requer a configuração do código de inicialização para apenas alguns ambientes com diferenças mínimas de código por ambiente.

No exemplo seguinte, o ambiente é mantido no campo _env e controla a execução de código com base no ambiente do aplicativo.

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Classe Startup específica do ambiente

Uma aplicação pode definir várias Startup classes para diferentes ambientes com a convenção de nomenclatura Startup{EnvironmentName}, onde o parâmetro {ENVIRONMENT NAME} é o nome do ambiente.

A classe cujo sufixo de nome corresponde ao ambiente atual é priorizada. Se uma classe correspondente Startup{EnvironmentName} não for encontrada, a Startup classe será usada.

Para implementar classes baseadas em Startup ambiente, crie quantas Startup{EnvironmentName} classes forem necessárias e uma classe de fallback Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Onde o construtor de host é criado, chame HostingAbstractionsWebHostBuilderExtensions.UseStartup, que aceita um nome de assembly para carregar a classe correta Startup :

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Métodos de classe específicos Startup do ambiente

Os Configure métodos e ConfigureServices suportam versões específicas do ambiente do formulário Configure{ENVIRONMENT NAME} e Configure{ENVIRONMENT NAME}Services, onde o espaço reservado {ENVIRONMENT NAME} é o nome do ambiente. Se um nome de ambiente correspondente não for encontrado para os métodos nomeados, o ConfigureServices método ou Configure será usado, respectivamente.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

Recursos adicionais

• Visualizar ou descarregar amostra de código (como descarregar)
• Inicialização do aplicativo no ASP.NET Core
• Configuração no ASP.NET Core
• ASP.NET Core Blazor ambientes