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.

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

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 ASPNETCORE_ENVIRONMENT substitui DOTNET_ENVIRONMENT.

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"
  

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, escolha Variáveis de ambiente.
3. Na guia Configurações de aplicativo, escolha + Adicionar.
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

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 ConfigureWebHostDefaults é chamado. Os modelos padrão de aplicativo web ASP.NET Core fazem a chamada de ConfigureWebHostDefaults. O valor ASPNETCORE_ENVIRONMENT substitui DOTNET_ENVIRONMENT.

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:

• Faz a chamada de UseDeveloperExceptionPage quando ASPNETCORE_ENVIRONMENT é definido 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 o ajuste de Startup.Configure em 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ção de Ambiente usa o valor de Incluir.EnvironmentName para incluir ou excluir a 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, 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.

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. 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: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 no Visual Studio. 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. Por exemplo, na imagem abaixo, selecionar o nome do projeto inicia o Kestrel servidor Web.

  

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

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 Depurar das propriedades de projeto do Visual Studio fornece uma GUI para editar o arquivo launchSettings.json. 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: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 comando dotnet run em um shell de comando com a opção --launch-profile definida como o nome do perfil. Essa abordagem dá suporte apenas a perfis Kestrel.

  dotnet run --launch-profile "SampleApp"
  

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

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 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 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 folha 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

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

  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. Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.

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.

Arquivo de projeto ou perfil de publicação

Nas implantações do Windows 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>

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

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

Faça a chamada de UseEnvironment ao criar o host. Confira 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

Injetar IWebHostEnvironment um no construtor Startup. Essa abordagem é útil quando o aplicativo requer o ajuste de Startup em apenas alguns ambientes com diferenças mínimas de código por ambiente.

No exemplo a seguir:

• O ambiente é mantido no campo _env.
• _env é usado em ConfigureServices e Configure 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 classes Startup em ambientes diferentes. A classe apropriada Startup é selecionada em 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 o ajuste de inicialização em vários ambientes com muitas diferenças de código por ambiente. Os aplicativos típicos não precisarão dessa abordagem.

Para implementar classes Startup com base no ambiente, crie uma classe Startup{EnvironmentName} e uma classe Startup de fallback:

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 sobrecarga UseStartup(IWebHostBuilder, String) 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 são compatíveis com versões específicas do ambiente dos formatos Configure<EnvironmentName> e Configure<EnvironmentName>Services. Se um método Configure<EnvironmentName>Services ou Configure<EnvironmentName> correspondente não for encontrado, o método ConfigureServices ou Configure será usado, respectivamente. Essa abordagem é útil quando o aplicativo requer o ajuste de inicialização em 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

• 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