Usar vários ambientes no ASP.NET Core

  • Artigo
  • 23 minutos para o fim da leitura

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, ASP.NET Core leituras das seguintes variáveis de ambiente:

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT quando o WebApplication.CreateBuilder método é chamado. A chamada WebApplication.CreateBuilderpadrão ASP.NET Core modelos de aplicativo Web . O ASPNETCORE_ENVIRONMENT valor substitui DOTNET_ENVIRONMENT.

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

O seguinte código:

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 de Ambiente usa o valor de IHostEnvironment.EnvironmentName para incluir ou excluir 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, variáveis de ambiente e valores não diferenciam maiúsculas de minúsculas. Por padrão, as variáveis de ambiente e os valores do Linux diferenciam maiúsculas de minúsculas.

Criar AmbientesSample

O código de exemplo usado neste artigo baseia-se em um Razor projeto de Páginas 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

Quando o aplicativo é executado, 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 ambiente na linha de comando

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

dotnet run --environment Production

O comando anterior define o ambiente Production como 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 de projeto 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. Valores de ambiente definidos em launchSettings.json valores de substituição definidos no ambiente do sistema.

O arquivo launchSettings.json:

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

O ON a seguir JSmostra o launchSettings.json arquivo de um projeto Web ASP.NET Core chamado EnvironmentsSample criado com o Visual Studio oudotnet 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 ON anterior JScontém dois perfis:

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

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

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

IIS Express iniciar no menu

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

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

A guia Depuração/Geral das propriedades do projeto do Visual Studio 2022 fornece um link de interface do usuário de perfis de inicialização do Open debug . Este link abre uma caixa de diálogo Iniciar Perfis que permite editar as configurações de variável de ambiente no launchSettings.json arquivo. 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. Kestrel deve ser reiniciado antes de detectar alterações feitas em seu ambiente.

Configurando variáveis de ambiente das propriedades do projeto

O arquivo a seguir launchSettings.json 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 dotnet run comando da CLI com a opção --launch-profile definida como o nome do perfil. Essa abordagem só dá suporte a Kestrel perfis.

    dotnet run --launch-profile "SampleApp"

Aviso

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

Ao usar Visual Studio Code, variáveis de ambiente podem ser definidas no .vscode/launch.json arquivo. O exemplo a seguir define várias variáveis de ambiente para valores de configuração do 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 .vscode/launch.json arquivo é usado apenas por 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.
  • Registro em log e monitoramento de produção habilitados. Por exemplo, usando o Application Insights.

Definir o ambiente definindo uma variável de ambiente

Geralmente, é útil definir um ambiente específico para teste com uma variável de ambiente ou configuração de plataforma. 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 é o valor padrão se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT não tiver sido definido. Os aplicativos implantados no Azure são Production por padrão.

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

  1. Selecione o aplicativo na página Serviços de Aplicativo .
  2. No grupo Configurações , selecione Configuração.
  3. Na guia Configurações do aplicativo , selecione Nova configuração do aplicativo.
  4. Na janela Adicionar/Editar configuração do aplicativo , forneça ASPNETCORE_ENVIRONMENT o Nome. Para Valor, forneça o ambiente (por exemplo, Staging).
  5. Selecione a caixa de seleção de configuração de slot de implantação se desejar que a configuração de ambiente permaneça com o slot atual quando os slots de implantação forem trocados. Para obter mais informações, consulte Configurar ambientes de preparo em 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 Configuração .

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

Windows – Definir variável de ambiente para um processo

Valores de ambiente em launchSettings.json valores de substituição definidos no ambiente do sistema.

Para definir a ASPNETCORE_ENVIRONMENT sessão atual quando o aplicativo for iniciado usando a execução dotnet, 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 ASPNETCORE_ENVIRONMENT apenas para processos iniciados a partir dessa janela de comando.

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

  • Abra asconfigurações do sistemaPainel de Controle>System> Advanced e adicione ou edite o ASPNETCORE_ENVIRONMENT valor:

    Propriedades avançadas do sistema

    Variável de ambiente do ASP.NET Core

  • 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

      A /M opção 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 Machine opção 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. Valores de ambiente em launchSettings.json valores de substituição definidos no ambiente do sistema.

Windows – Usar web.config

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

Windows – Implantações do IIS

Inclua a <EnvironmentName> propriedade 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 ASPNETCORE_ENVIRONMENT ambiente para um aplicativo em execução em um Pool de Aplicativos isolado (com suporte no IIS 10.0 ou posterior), consulte a seção de comandoAppCmd.exe de Environment Variables <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 ASPNETCORE_ENVIRONMENT variável de ambiente, use uma das seguintes abordagens para ter o novo valor captado 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

Para distribuições do Linux, use o export comando em um prompt de comando para configurações de variáveis baseadas em sessão e o arquivo bash_profile para 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();

Para saber mais, confira Host Genérico .NET no ASP.NET Core.

Configuração por ambiente

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

Configurar serviços e middleware por ambiente

Use WebApplicationBuilder.Environment ou WebApplication.Environment adicione condicionalmente serviços ou middleware dependendo do ambiente atual. O modelo de projeto inclui um exemplo de código que adiciona middleware somente quando o ambiente atual não é 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 verificar o ambiente atual ao configurar serviços, use builder.Environment em vez de app.Environment.

Recursos adicionais

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, ASP.NET Core leituras das seguintes variáveis de ambiente:

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT quando ConfigureWebHostDefaults é chamado. A chamada ConfigureWebHostDefaultspadrão ASP.NET Core modelos de aplicativo Web . O ASPNETCORE_ENVIRONMENT valor substitui DOTNET_ENVIRONMENT.

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

O seguinte código:

  • Chamadas UseDeveloperExceptionPage quando ASPNETCORE_ENVIRONMENT está definida como Development.
  • Chama UseExceptionHandler quando o valor de ASPNETCORE_ENVIRONMENT é definido como Staging, Productionou Staging_2.
  • IWebHostEnvironment Injeta em Startup.Configure. Essa abordagem é útil quando o aplicativo requer apenas ajuste Startup.Configure para alguns ambientes com diferenças mínimas de código por ambiente.
  • É semelhante ao código gerado pelos modelos de ASP.NET Core.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

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

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

<environment include="Development">
    <div>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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, variáveis de ambiente e valores não diferenciam maiúsculas de minúsculas. Por padrão, as variáveis de ambiente e os valores do Linux diferenciam maiúsculas de minúsculas.

Criar AmbientesSample

O código de exemplo usado neste documento baseia-se em um Razor projeto de Páginas chamado EnvironmentsSample.

O código a seguir cria e executa um aplicativo Web chamado EnvironmentsSample:

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

Quando o aplicativo é executado, ele exibe algumas das seguintes saídas:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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.

O ambiente de desenvolvimento do computador local pode ser definido no arquivo Properties\launchSettings.json do projeto. Valores de ambiente definidos em launchSettings.json valores de substituição definidos no ambiente do sistema.

O arquivo launchSettings.json:

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

O ON a seguir JSmostra o launchSettings.json arquivo de um projeto Web ASP.NET Core chamado EnvironmentsSample criado com o Visual Studio oudotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

A marcação anterior contém dois perfis:

  • IIS Express: o perfil padrão usado ao iniciar o aplicativo do Visual Studio. A "commandName" chave tem o valor "IISExpress", portanto, IISExpress é o servidor Web. Você pode definir o perfil de inicialização para o projeto ou qualquer outro perfil incluído. Por exemplo, na imagem abaixo, selecionar o nome do projeto inicia o Kestrel servidor Web.

    IIS Express iniciar no menu

  • EnvironmentsSample: o nome do perfil é o nome do projeto. Esse perfil é usado por padrão ao iniciar o aplicativo com dotnet run. A "commandName" chave tem o valor "Project", portanto, o Kestrel servidor Web é iniciado.

O valor de commandName pode especificar 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 : inicializa Kestrel.

A guia Depuração de propriedades do projeto do Visual Studio fornece uma GUI para editar o launchSettings.json arquivo. As alterações feitas nos perfis do projeto poderão não ter efeito até que o servidor Web seja reiniciado. Kestrel deve ser reiniciado antes de detectar alterações feitas em seu ambiente.

Configurando variáveis de ambiente das propriedades do projeto

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

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

Os perfis podem ser selecionados:

  • Na interface do usuário do Visual Studio.

  • Usando o dotnet run comando em um shell de comando com a opção --launch-profile definida como o nome do perfil. Essa abordagem só dá suporte a Kestrel perfis.

    dotnet run --launch-profile "SampleApp"

Aviso

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

Ao usar Visual Studio Code, as variáveis de ambiente podem ser definidas no .vscode/launch.json arquivo. O exemplo a seguir define várias variáveis de ambiente de 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 .vscode/launch.json arquivo só é usado por 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.
  • Registro em log e monitoramento de produção habilitados. Por exemplo, usando o Application Insights.

Definir o ambiente

Geralmente, é útil definir um ambiente específico para testes com uma variável de ambiente ou uma configuração de plataforma. 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 é o valor padrão se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT não tiver sido definido. Os aplicativos implantados no azure são Production por padrão.

Para definir o ambiente no Serviço de Aplicativo do Azure, execute as seguintes etapas:

  1. Selecione o aplicativo na folha Serviços de Aplicativos.
  2. No grupo Configurações , selecione a folha Configuração .
  3. Na guia Configurações do aplicativo , selecione Nova configuração de aplicativo.
  4. Na janela Adicionar/Editar configuração do aplicativo , forneça ASPNETCORE_ENVIRONMENT o Nome. Para Valor, forneça o ambiente (por exemplo, Staging).
  5. Selecione a caixa de seleção de configuração do slot de implantação se desejar que a configuração do ambiente permaneça com o slot atual quando os slots de implantação forem trocados. Para obter mais informações, consulte Configurar ambientes de preparo em Serviço de Aplicativo do Azure na documentação do Azure.
  6. Selecione OK para fechar a janela Adicionar/Editar configuração do aplicativo .
  7. Selecione Salvar na parte superior da folha Configuração .

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

Windows

Valores de ambiente em launchSettings.json valores de substituição definidos no ambiente do sistema.

Para definir o ASPNETCORE_ENVIRONMENT para a sessão atual quando o aplicativo for iniciado usando dotnet run, os comandos a seguir serão usados:

Prompt de comando

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

PowerShell

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

Os conjuntos de comandos anteriores ASPNETCORE_ENVIRONMENT somente para processos iniciados a partir dessa janela de comando.

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

  • Abra asconfigurações do sistemaPainel de Controle>System> Advanced e adicione ou edite o ASPNETCORE_ENVIRONMENT valor:

    Propriedades avançadas do sistema

    Variável de ambiente do ASP.NET Core

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

    Prompt de comando

    setx ASPNETCORE_ENVIRONMENT Staging /M

    O comutador /M indica para definir 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.

    PowerShell

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

    O valor da opção Machine indica para definir 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. Valores de ambiente em launchSettings.json valores de substituição definidos no ambiente do sistema.

web.config

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

Arquivo de projeto ou perfil de publicação

Para implantações do Windows IIS: Inclua a <EnvironmentName> propriedade 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>

Por pool de aplicativos do IIS

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT para 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 por 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

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

Definir o ambiente no código

Chame UseEnvironment ao criar o host. Consulte o Host Genérico do .NET no ASP.NET Core.

Configuração por ambiente

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

Métodos e classe Startup baseados no ambiente

Injetar IWebHostEnvironment na classe startup

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

No exemplo a seguir:

  • O ambiente é mantido no _env campo.
  • _env é usado e ConfigureServicesConfigure para aplicar a configuração de inicialização com base no ambiente do aplicativo.
public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Convenções da classe Startup

Quando um aplicativo ASP.NET Core é iniciado, a classe Startup inicia o aplicativo. O aplicativo pode definir várias Startup classes para ambientes diferentes. A classe apropriada Startup é selecionada no runtime. 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. Essa abordagem é útil quando o aplicativo requer a configuração da inicialização para vários ambientes com muitas diferenças de código por ambiente. Aplicativos típicos não precisarão dessa abordagem.

Para implementar classes baseadas em Startup ambiente, crie uma classe de fallback e classes Startup{EnvironmentName} de fallback Startup :

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Use a UseStartup(IWebHostBuilder, String) sobrecarga que aceita um nome de assembly:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Convenções do método Startup

Configure e ConfigureServices dão suporte a versões específicas do ambiente do formulário Configure<EnvironmentName> e Configure<EnvironmentName>Services. Se uma correspondência Configure<EnvironmentName>Services ou Configure<EnvironmentName> método não for encontrado, o método ou Configure o ConfigureServices método será usado, respectivamente. Essa abordagem é útil quando o aplicativo requer a configuração da inicialização para vários ambientes com muitas diferenças de código por ambiente:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

Recursos adicionais