ambientes de runtime do ASP.NET Core

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

Os aplicativos geralmente são executados no ambiente de desenvolvimento durante o desenvolvimento local e testes no computador 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 preparo de um aplicativo antes da implantação dinâmica ou de outros ambientes criados pelos desenvolvedores.

Este artigo descreve ambientes de runtime do aplicativo, como usar o ambiente para controlar o comportamento do aplicativo e como definir o ambiente.

Consulte as diretrizes de ambiente do Blazor, que adicionam ou se sobrepõem às diretrizes neste artigo, em Ambientes do ASP.NET Core Blazor.

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 típicas e a configuração comum de desenvolvedor que diferem do ambiente de desenvolvimento incluem:

• Habilitando o cache.
• Agrupar e minificar recursos do lado do cliente, além de potencialmente disponibilizá-los a partir de uma CDN.
• Desabilitando páginas de erro de diagnóstico e habilitando páginas de erro amigáveis.
• Habilitando o registro em log e o monitoramento de produção. Por exemplo, o registro de logs está habilitado 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 está em execução.

Registro em log

A saída no terminal de comando de um aplicativo em execução ao iniciar indica o ambiente do aplicativo. No exemplo a seguir, o aplicativo está em execução no ambiente de preparo:

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

Variáveis de ambiente que determinam o ambiente de runtime

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

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

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

Controlar a execução de código por ambiente

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

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Testing"))
    {
        app.UseExceptionHandler("/Error");
    }

    ...
}

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

Controlar o conteúdo renderizado

Injete IHostEnvironment em um componente Razor renderizado no servidor e use os métodos de extensão do serviço e a propriedade EnvironmentName para determinar o ambiente para a renderização de 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 Os componentes do Prerender ASP.NET CoreRazor.

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

Use a opção-e|--environment 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 Properties\launchSettings.json arquivo do projeto. Valores de ambiente definidos em launchSettings.json substituem os valores definidos pelo ambiente do sistema.

O arquivo launchSettings.json:

• É usado apenas no computador de desenvolvimento local.
• Não é implantado quando o aplicativo é publicado.
• Pode conter vários perfis, cada um configurando um ambiente diferente.

O exemplo a seguir define o ambiente de staging para o perfil de lançamento https usando a variável de ambiente ASPNETCORE_ENVIRONMENT.

"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 Depurar>Geral, seguido pela seleção do link Abrir IU de perfis de inicialização de depuração.

• Com o projeto selecionado no Gerenciador de Soluções, selecione {PROJECT NAME} 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 Inicialização , na qual você pode editar as configurações de variável de ambiente no launchSettings.json arquivo. 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.

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

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

Como alternativa, use o dotnet run comando com a opção-lp|--launch-profile definida como o nome do perfil. Essa abordagem só dá suporte a perfis de inicialização com base no Project comando.

dotnet run -lp "https"

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

Se o Kit de Desenvolvimento do C# não for usado, defina a ASPNETCORE_ENVIRONMENT variável de ambiente na .vscode/launch.jsonenv seção, juntamente com quaisquer outras variáveis de ambiente definidas na seção:

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

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

Definir o ambiente com 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 estiver definido, ele usará como padrão o ambiente de produção, que desabilita a maioria dos recursos de depuração. O método para configurar o ambiente depende do sistema operacional.

Serviço de Aplicativo do Azure

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

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

• Configurar um aplicativo do App Service
• 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 ASPNETCORE_ENVIRONMENT variável de ambiente para a sessão atual (shell de comando) quando o aplicativo for iniciado usando dotnet run, use os comandos a seguir. Depois que a variável de ambiente é definida, o aplicativo é iniciado sem um perfil de inicialização usando a opção --no-launch-profile .

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 as diretrizes apropriadas 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 após o valor ser definido. Valores de ambiente definidos por perfis de inicialização no launchSettings.json arquivo substituem valores definidos para o ambiente do sistema.

Definir o ambiente para aplicativos implantados no IIS

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

Para definir a variável de ambiente na implantação para o IIS, inclua a <EnvironmentName> propriedade no perfil de publicação (.pubxml) ou no arquivo de projeto. O exemplo a seguir define o ambiente em web.config para ambiente de preparo ao publicar o projeto:

<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 de 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 no Dockerfile usando a ENV instrução:

ENV ASPNETCORE_ENVIRONMENT=Staging

Utilize o Docker Compose

Para aplicativos de vários serviços 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 opção -e|--env :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Um ambiente definido em runtime com 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 opção --env-file ao executar o docker run comando:

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

Um ambiente definido em runtime com docker run substitui um ambiente definido pelo Dockerfile.

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

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.

Acesse o ambiente 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 Startup construtor para controlar a execução do 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 a seguir, 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

Um aplicativo pode definir várias Startup classes para diferentes ambientes com a convenção de nomenclatura Startup{EnvironmentName} de classes, onde o {ENVIRONMENT NAME} marcador é o nome do ambiente.

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

Para implementar classes no ambiente Startup, crie quantas classes Startup{EnvironmentName} sejam 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 Startup específicos do ambiente

Os métodos Configure e ConfigureServices dão suporte a versões do formulário Configure{ENVIRONMENT NAME} e Configure{ENVIRONMENT NAME}Services específicas para ambientes, em que 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 método ConfigureServices 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

• 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