Usar vários ambientes no ASP.NET CoreUse multiple environments in ASP.NET Core

Por Rick AndersonBy Rick Anderson

O ASP.NET Core configura o comportamento do aplicativo com base no ambiente de runtime usando uma variável de ambiente.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

AmbientesEnvironments

ASP.NET Core lê a variável de ambiente ASPNETCORE_ENVIRONMENT na inicialização do aplicativo e armazena o valor em IWebHostEnvironment. environmentname.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IWebHostEnvironment.EnvironmentName. ASPNETCORE_ENVIRONMENT pode ser definido como qualquer valor, mas três valores são fornecidos pela estrutura:ASPNETCORE_ENVIRONMENT can be set to any value, but three values are provided by the framework:

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

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

    app.UseStaticFiles();
    app.UseMvc();
}

O código anterior:The preceding code:

O Auxiliar de Marcação de Ambiente usa o valor de IHostingEnvironment.EnvironmentName para incluir ou excluir a marcação no elemento:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

No Windows e no macOS, valores e variáveis de ambiente não diferenciam maiúsculas de minúsculas.On Windows and macOS, environment variables and values aren't case sensitive. Valores e variáveis de ambiente do Linux diferenciam maiúsculas de minúsculas por padrão.Linux environment variables and values are case sensitive by default.

DesenvolvimentoDevelopment

O ambiente de desenvolvimento pode habilitar recursos que não devem ser expostos em produção.The development environment can enable features that shouldn't be exposed in production. Por exemplo, os modelos do ASP.NET Core habilitam a Página de exceção do desenvolvedor no ambiente de desenvolvimento.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

O ambiente de desenvolvimento do computador local pode ser definido no arquivo Properties\launchSettings.json do projeto.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.Environment values set in launchSettings.json override values set in the system environment.

O seguinte JSON mostra três perfis de um arquivo launchSettings.json:The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Observação

A propriedade applicationUrl no launchSettings.json pode especificar uma lista de URLs de servidores.The applicationUrl property in launchSettings.json can specify a list of server URLs. Use um ponto e vírgula entre as URLs na lista:Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Quando o aplicativo é inicializado com dotnet run, o primeiro perfil com "commandName": "Project" é usado.When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. O valor de commandName especifica o servidor Web a ser iniciado.The value of commandName specifies the web server to launch. commandName pode ser qualquer um dos seguintes:commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (que inicia o Kestrel)Project (which launches Kestrel)

Quando um aplicativo for iniciado com dotnet run:When an app is launched with dotnet run:

  • launchSettings.json é lido, se está disponível.launchSettings.json is read if available. As configurações de environmentVariables em launchSettings.json substituem as variáveis de ambiente.environmentVariables settings in launchSettings.json override environment variables.
  • O ambiente de hospedagem é exibido.The hosting environment is displayed.

A saída a seguir mostra um aplicativo iniciado com dotnet run:The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

A guia Depurar das propriedades do projeto do Visual Studio fornece uma GUI para editar o arquivo launchSettings.json:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

Configurando variáveis de ambiente das propriedades do projeto

As alterações feitas nos perfis do projeto poderão não ter efeito até que o servidor Web seja reiniciado.Changes made to project profiles may not take effect until the web server is restarted. O Kestrel precisa ser reiniciado antes de detectar as alterações feitas ao seu ambiente.Kestrel must be restarted before it can detect changes made to its environment.

Aviso

launchSettings.json não deve armazenar segredos.launchSettings.json shouldn't store secrets. A ferramenta Secret Manager pode ser usado para armazenar segredos de desenvolvimento local.The Secret Manager tool can be used to store secrets for local development.

Ao usar Visual Studio Code, variáveis de ambiente podem ser definidas no arquivo .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. O exemplo a seguir define o ambiente como Development:The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Um arquivo .vscode/launch.json do projeto não é lido ao iniciar o aplicativo com dotnet run da mesma maneira que Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Ao inicializar um aplicativo em desenvolvimento que não tem um arquivo launchSettings.json, defina o ambiente com uma variável de ambiente ou um argumento de linha de comando para o comando dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProductionProduction

O ambiente de produção deve ser configurado para maximizar a segurança, o desempenho e a robustez do aplicativo.The production environment should be configured to maximize security, performance, and app robustness. Algumas configurações comuns que são diferentes do desenvolvimento incluem:Some common settings that differ from development include:

  • Cache.Caching.
  • Recursos do lado do cliente são agrupados, minimizados e potencialmente atendidos por meio de uma CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Páginas de erro de diagnóstico desabilitadas.Diagnostic error pages disabled.
  • Páginas de erro amigáveis habilitadas.Friendly error pages enabled.
  • Log de produção e monitoramento habilitados.Production logging and monitoring enabled. Por exemplo, Application Insights.For example, Application Insights.

Definir o ambienteSet the environment

Geralmente, é útil definir um ambiente específico para teste com uma variável de ambiente ou configuração de plataforma.It's often useful to set a specific environment for testing with an environment variable or platform setting. Se o ambiente não for definido, ele usará Production como padrão, o que desabilitará a maioria dos recursos de depuração.If the environment isn't set, it defaults to Production, which disables most debugging features. O método para configurar o ambiente depende do sistema operacional.The method for setting the environment depends on the operating system.

Quando o host é criado, a última configuração de ambiente lida pelo aplicativo determina o ambiente do aplicativo.When the host is built, the last environment setting read by the app determines the app's environment. O ambiente do aplicativo não pode ser alterado enquanto o aplicativo está em execução.The app's environment can't be changed while the app is running.

Configuração de plataforma ou variável de ambienteEnvironment variable or platform setting

Serviço de Aplicativo do AzureAzure App Service

Para definir o ambiente no Serviço de Aplicativo do Azure, execute as seguintes etapas:To set the environment in Azure App Service, perform the following steps:

  1. Selecione o aplicativo na folha Serviços de Aplicativos.Select the app from the App Services blade.
  2. No grupo configurações , selecione a folha configuração .In the Settings group, select the Configuration blade.
  3. Na guia configurações do aplicativo , selecione nova configuração de aplicativo.In the Application settings tab, select New application setting.
  4. Na janela Adicionar/Editar configuração de aplicativo , forneça ASPNETCORE_ENVIRONMENT para o nome.In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. Para valor, forneça o ambiente (por exemplo, Staging).For Value, provide the environment (for example, 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 com o slot atual quando os slots de implantação forem trocados.Select the Deployment slot setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Para obter mais informações, consulte configurar ambientes de preparo no serviço de Azure app na documentação do Azure.For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Selecione OK para fechar a janela Adicionar/Editar configuração de aplicativo .Select OK to close the Add/Edit application setting window.
  7. Selecione salvar na parte superior da folha de configuração .Select Save at the top of the Configuration blade.

O Serviço de Aplicativo do Azure reinicia automaticamente o aplicativo após uma configuração de aplicativo (variável de ambiente) ser adicionada, alterada ou excluída no portal do Azure.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

PortalWindows

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:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Prompt de comandoCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Esses comandos somente têm efeito para a janela atual.These commands only take effect for the current window. Quando a janela é fechada, a configuração ASPNETCORE_ENVIRONMENT é revertida para a configuração padrão ou o valor de computador.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Para definir o valor globalmente no Windows, use uma das seguintes abordagens:To set the value globally in Windows, use either of the following approaches:

  • Abra o painel de controle > sistema > Configurações avançadas do sistema e adicione ou edite o valor ASPNETCORE_ENVIRONMENT:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    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:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Prompt de comandoCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    O comutador /M indica para definir a variável de ambiente no nível do sistema.The /M switch indicates to set the environment variable at the system level. Se o comutador /M não for usado, a variável de ambiente será definida para a conta de usuário.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

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

    O valor da opção Machine indica para definir a variável de ambiente no nível do sistema.The Machine option value indicates to set the environment variable at the system level. Se o valor da opção for alterado para User, a variável de ambiente será definida para a conta de usuário.If the option value is changed to User, the environment variable is set for the user account.

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.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT com web.config, consulte a seção Definindo variáveis de ambiente de Módulo do ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Módulo do ASP.NET Core.

Arquivo de projeto ou perfil de publicaçãoProject file or publish profile

Para implantações do Windows IIS: Inclua a propriedade <EnvironmentName> no perfil de publicação (. pubxml) ou no arquivo de projeto.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:This approach sets the environment in web.config when the project is published:

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

Por pool de aplicativos do IISPer IIS Application Pool

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>.To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. 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.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Importante

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:When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Execute net stop was /y seguido por net start w3svc em um prompt de comando.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Reinicie o servidor.Restart the server.

macOSmacOS

A configuração do ambiente atual para macOS pode ser feita em linha ao executar o aplicativo:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

Como alternativa, defina o ambiente com export antes de executar o aplicativo:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

As variáveis de ambiente no nível do computador são definidas no arquivo .bashrc ou .bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Edite o arquivo usando qualquer editor de texto.Edit the file using any text editor. Adicione a seguinte instrução:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

Para distribuições Linux, use o comando export no prompt de comando para as configurações de variável baseadas na sessão e o arquivo bash_profile para as configurações de ambiente no nível do computador.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Definir o ambiente no códigoSet the environment in code

Chame UseEnvironment ao compilar o host.Call UseEnvironment when building the host. Consulte Host Genérico .NET.See Host Genérico .NET.

Configuração por ambienteConfiguration by environment

Para carregar a configuração por ambiente, recomendamos:To load configuration by environment, we recommend:

Métodos e classe Startup baseados no ambienteEnvironment-based Startup class and methods

Injetar IWebHostEnvironment na inicialização. configurarInject IWebHostEnvironment into Startup.Configure

Injetar IWebHostEnvironment em Startup.Configure.Inject IWebHostEnvironment into Startup.Configure. Essa abordagem é útil quando o aplicativo requer apenas o ajuste de Startup.Configure para alguns ambientes com diferenças mínimas de código por ambiente.This approach is useful when the app only requires adjusting Startup.Configure for a few environments with minimal code differences per environment.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Development environment code
    }
    else
    {
        // Code for all other environments
    }
}

Injetar IWebHostEnvironment na classe de inicializaçãoInject IWebHostEnvironment into the Startup class

Injeta IWebHostEnvironment no construtor de Startup.Inject IWebHostEnvironment into the Startup constructor. Essa abordagem é útil quando o aplicativo requer a configuração de Startup apenas para alguns ambientes com diferenças mínimas de código por ambiente.This approach is useful when the app requires configuring Startup for only a few environments with minimal code differences per environment.

No exemplo a seguir:In the following example:

  • O ambiente é mantido no campo _env.The environment is held in the _env field.
  • _env é usado em ConfigureServices e Configure para aplicar a configuração de inicialização com base no ambiente do aplicativo._env is used in ConfigureServices and Configure to apply startup configuration based on the app's environment.
public class Startup
{
    private readonly IWebHostEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else if (_env.IsStaging())
        {
            // Staging environment code
        }
        else
        {
            // Code for all other environments
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else
        {
            // Code for all other environments
        }
    }
}

Convenções da classe StartupStartup class conventions

Quando um aplicativo ASP.NET Core é iniciado, a classe Startup inicia o aplicativo.When an ASP.NET Core app starts, the Startup class bootstraps the app. O aplicativo pode definir classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment).The app can define separate Startup classes for different environments (for example, StartupDevelopment). A classe de Startup apropriada está selecionada em tempo de execução.The appropriate Startup class is selected at runtime. A classe cujo sufixo do nome corresponde ao ambiente atual é priorizada.The class whose name suffix matches the current environment is prioritized. Se uma classe Startup{EnvironmentName} correspondente não for encontrada, a classe Startup será usada.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used. 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.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

Para implementar classes Startup com base em ambiente, crie uma classe Startup{EnvironmentName} para cada ambiente no uso e classe Startup de fallback:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

Use a sobrecarga UseStartup (IWebHostBuilder, String) que aceita um nome de assembly:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

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

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Convenções do método StartupStartup method conventions

Configurar e configuraservices oferecem suporte a versões específicas do ambiente do formulário Configure<EnvironmentName> e Configure<EnvironmentName>Services.Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services. 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.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

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

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Recursos adicionaisAdditional resources

Por Rick AndersonBy Rick Anderson

O ASP.NET Core configura o comportamento do aplicativo com base no ambiente de runtime usando uma variável de ambiente.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

AmbientesEnvironments

O ASP.NET Core lê a variável de ambiente ASPNETCORE_ENVIRONMENT na inicialização do aplicativo e armazena o valor em IHostingEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IHostingEnvironment.EnvironmentName. ASPNETCORE_ENVIRONMENT pode ser definido como qualquer valor, mas três valores são fornecidos pela estrutura:ASPNETCORE_ENVIRONMENT can be set to any value, but three values are provided by the framework:

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

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

    app.UseStaticFiles();
    app.UseMvc();
}

O código anterior:The preceding code:

O Auxiliar de Marcação de Ambiente usa o valor de IHostingEnvironment.EnvironmentName para incluir ou excluir a marcação no elemento:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

No Windows e no macOS, valores e variáveis de ambiente não diferenciam maiúsculas de minúsculas.On Windows and macOS, environment variables and values aren't case sensitive. Valores e variáveis de ambiente do Linux diferenciam maiúsculas de minúsculas por padrão.Linux environment variables and values are case sensitive by default.

DesenvolvimentoDevelopment

O ambiente de desenvolvimento pode habilitar recursos que não devem ser expostos em produção.The development environment can enable features that shouldn't be exposed in production. Por exemplo, os modelos do ASP.NET Core habilitam a Página de exceção do desenvolvedor no ambiente de desenvolvimento.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

O ambiente de desenvolvimento do computador local pode ser definido no arquivo Properties\launchSettings.json do projeto.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Os valores de ambiente definidos em launchSettings.json substituem os valores definidos no ambiente do sistema.Environment values set in launchSettings.json override values set in the system environment.

O seguinte JSON mostra três perfis de um arquivo launchSettings.json:The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Observação

A propriedade applicationUrl no launchSettings.json pode especificar uma lista de URLs de servidores.The applicationUrl property in launchSettings.json can specify a list of server URLs. Use um ponto e vírgula entre as URLs na lista:Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Quando o aplicativo é inicializado com dotnet run, o primeiro perfil com "commandName": "Project" é usado.When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. O valor de commandName especifica o servidor Web a ser iniciado.The value of commandName specifies the web server to launch. commandName pode ser qualquer um dos seguintes:commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (que inicia o Kestrel)Project (which launches Kestrel)

Quando um aplicativo for iniciado com dotnet run:When an app is launched with dotnet run:

  • launchSettings.json é lido, se está disponível.launchSettings.json is read if available. As configurações de environmentVariables em launchSettings.json substituem as variáveis de ambiente.environmentVariables settings in launchSettings.json override environment variables.
  • O ambiente de hospedagem é exibido.The hosting environment is displayed.

A saída a seguir mostra um aplicativo iniciado com dotnet run:The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

A guia Depurar das propriedades do projeto do Visual Studio fornece uma GUI para editar o arquivo launchSettings.json:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

Configurando variáveis de ambiente das propriedades do projeto

As alterações feitas nos perfis do projeto poderão não ter efeito até que o servidor Web seja reiniciado.Changes made to project profiles may not take effect until the web server is restarted. O Kestrel precisa ser reiniciado antes de detectar as alterações feitas ao seu ambiente.Kestrel must be restarted before it can detect changes made to its environment.

Aviso

launchSettings.json não deve armazenar segredos.launchSettings.json shouldn't store secrets. A ferramenta Secret Manager pode ser usado para armazenar segredos de desenvolvimento local.The Secret Manager tool can be used to store secrets for local development.

Ao usar Visual Studio Code, variáveis de ambiente podem ser definidas no arquivo .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. O exemplo a seguir define o ambiente como Development:The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Um arquivo .vscode/launch.json do projeto não é lido ao iniciar o aplicativo com dotnet run da mesma maneira que Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Ao inicializar um aplicativo em desenvolvimento que não tem um arquivo launchSettings.json, defina o ambiente com uma variável de ambiente ou um argumento de linha de comando para o comando dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProductionProduction

O ambiente de produção deve ser configurado para maximizar a segurança, o desempenho e a robustez do aplicativo.The production environment should be configured to maximize security, performance, and app robustness. Algumas configurações comuns que são diferentes do desenvolvimento incluem:Some common settings that differ from development include:

  • Cache.Caching.
  • Recursos do lado do cliente são agrupados, minimizados e potencialmente atendidos por meio de uma CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Páginas de erro de diagnóstico desabilitadas.Diagnostic error pages disabled.
  • Páginas de erro amigáveis habilitadas.Friendly error pages enabled.
  • Log de produção e monitoramento habilitados.Production logging and monitoring enabled. Por exemplo, Application Insights.For example, Application Insights.

Definir o ambienteSet the environment

Geralmente, é útil definir um ambiente específico para teste com uma variável de ambiente ou configuração de plataforma.It's often useful to set a specific environment for testing with an environment variable or platform setting. Se o ambiente não for definido, ele usará Production como padrão, o que desabilitará a maioria dos recursos de depuração.If the environment isn't set, it defaults to Production, which disables most debugging features. O método para configurar o ambiente depende do sistema operacional.The method for setting the environment depends on the operating system.

Quando o host é criado, a última configuração de ambiente lida pelo aplicativo determina o ambiente do aplicativo.When the host is built, the last environment setting read by the app determines the app's environment. O ambiente do aplicativo não pode ser alterado enquanto o aplicativo está em execução.The app's environment can't be changed while the app is running.

Configuração de plataforma ou variável de ambienteEnvironment variable or platform setting

Serviço de Aplicativo do AzureAzure App Service

Para definir o ambiente no Serviço de Aplicativo do Azure, execute as seguintes etapas:To set the environment in Azure App Service, perform the following steps:

  1. Selecione o aplicativo na folha Serviços de Aplicativos.Select the app from the App Services blade.
  2. No grupo configurações , selecione a folha configuração .In the Settings group, select the Configuration blade.
  3. Na guia configurações do aplicativo , selecione nova configuração de aplicativo.In the Application settings tab, select New application setting.
  4. Na janela Adicionar/Editar configuração de aplicativo , forneça ASPNETCORE_ENVIRONMENT para o nome.In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. Para valor, forneça o ambiente (por exemplo, Staging).For Value, provide the environment (for example, 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 com o slot atual quando os slots de implantação forem trocados.Select the Deployment slot setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Para obter mais informações, consulte configurar ambientes de preparo no serviço de Azure app na documentação do Azure.For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Selecione OK para fechar a janela Adicionar/Editar configuração de aplicativo .Select OK to close the Add/Edit application setting window.
  7. Selecione salvar na parte superior da folha de configuração .Select Save at the top of the Configuration blade.

O Serviço de Aplicativo do Azure reinicia automaticamente o aplicativo após uma configuração de aplicativo (variável de ambiente) ser adicionada, alterada ou excluída no portal do Azure.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

PortalWindows

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:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Prompt de comandoCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Esses comandos somente têm efeito para a janela atual.These commands only take effect for the current window. Quando a janela é fechada, a configuração ASPNETCORE_ENVIRONMENT é revertida para a configuração padrão ou o valor de computador.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Para definir o valor globalmente no Windows, use uma das seguintes abordagens:To set the value globally in Windows, use either of the following approaches:

  • Abra o painel de controle > sistema > Configurações avançadas do sistema e adicione ou edite o valor ASPNETCORE_ENVIRONMENT:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    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:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Prompt de comandoCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    O comutador /M indica para definir a variável de ambiente no nível do sistema.The /M switch indicates to set the environment variable at the system level. Se o comutador /M não for usado, a variável de ambiente será definida para a conta de usuário.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

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

    O valor da opção Machine indica para definir a variável de ambiente no nível do sistema.The Machine option value indicates to set the environment variable at the system level. Se o valor da opção for alterado para User, a variável de ambiente será definida para a conta de usuário.If the option value is changed to User, the environment variable is set for the user account.

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.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT com web.config, consulte a seção Definindo variáveis de ambiente de Módulo do ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Módulo do ASP.NET Core.

Arquivo de projeto ou perfil de publicaçãoProject file or publish profile

Para implantações do Windows IIS: Inclua a propriedade <EnvironmentName> no perfil de publicação (. pubxml) ou no arquivo de projeto.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:This approach sets the environment in web.config when the project is published:

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

Por pool de aplicativos do IISPer IIS Application Pool

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>.To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. 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.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Importante

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:When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Execute net stop was /y seguido por net start w3svc em um prompt de comando.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Reinicie o servidor.Restart the server.

macOSmacOS

A configuração do ambiente atual para macOS pode ser feita em linha ao executar o aplicativo:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

Como alternativa, defina o ambiente com export antes de executar o aplicativo:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

As variáveis de ambiente no nível do computador são definidas no arquivo .bashrc ou .bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Edite o arquivo usando qualquer editor de texto.Edit the file using any text editor. Adicione a seguinte instrução:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

Para distribuições Linux, use o comando export no prompt de comando para as configurações de variável baseadas na sessão e o arquivo bash_profile para as configurações de ambiente no nível do computador.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Definir o ambiente no códigoSet the environment in code

Chame UseEnvironment ao compilar o host.Call UseEnvironment when building the host. Consulte Host da Web do ASP.NET Core.See Host da Web do ASP.NET Core.

Configuração por ambienteConfiguration by environment

Para carregar a configuração por ambiente, recomendamos:To load configuration by environment, we recommend:

Métodos e classe Startup baseados no ambienteEnvironment-based Startup class and methods

Injetar IHostingEnvironment na inicialização. configurarInject IHostingEnvironment into Startup.Configure

Injetar IHostingEnvironment em Startup.Configure.Inject IHostingEnvironment into Startup.Configure. Essa abordagem é útil quando o aplicativo requer apenas a configuração de Startup.Configure para apenas alguns ambientes com diferenças mínimas de código por ambiente.This approach is useful when the app only requires configuring Startup.Configure for only a few environments with minimal code differences per environment.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Development environment code
    }
    else
    {
        // Code for all other environments
    }
}

Injetar IHostingEnvironment na classe de inicializaçãoInject IHostingEnvironment into the Startup class

Insira IHostingEnvironment no Construtor Startup e atribua o serviço a um campo para uso em toda a classe Startup.Inject IHostingEnvironment into the Startup constructor and assign the service to a field for use throughout the Startup class. Essa abordagem é útil quando o aplicativo requer a configuração da inicialização para apenas alguns ambientes com diferenças mínimas de código por ambiente.This approach is useful when the app requires configuring startup for only a few environments with minimal code differences per environment.

No exemplo a seguir:In the following example:

  • O ambiente é mantido no campo _env.The environment is held in the _env field.
  • _env é usado em ConfigureServices e Configure para aplicar a configuração de inicialização com base no ambiente do aplicativo._env is used in ConfigureServices and Configure to apply startup configuration based on the app's environment.
public class Startup
{
    private readonly IHostingEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else if (_env.IsStaging())
        {
            // Staging environment code
        }
        else
        {
            // Code for all other environments
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else
        {
            // Code for all other environments
        }
    }
}

Convenções da classe StartupStartup class conventions

Quando um aplicativo ASP.NET Core é iniciado, a classe Startup inicia o aplicativo.When an ASP.NET Core app starts, the Startup class bootstraps the app. O aplicativo pode definir classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment).The app can define separate Startup classes for different environments (for example, StartupDevelopment). A classe de Startup apropriada está selecionada em tempo de execução.The appropriate Startup class is selected at runtime. A classe cujo sufixo do nome corresponde ao ambiente atual é priorizada.The class whose name suffix matches the current environment is prioritized. Se uma classe Startup{EnvironmentName} correspondente não for encontrada, a classe Startup será usada.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used. 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.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

Para implementar classes Startup com base em ambiente, crie uma classe Startup{EnvironmentName} para cada ambiente no uso e classe Startup de fallback:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

Use a sobrecarga UseStartup (IWebHostBuilder, String) que aceita um nome de assembly:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

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

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Convenções do método StartupStartup method conventions

Configurar e configuraservices oferecem suporte a versões específicas do ambiente do formulário Configure<EnvironmentName> e Configure<EnvironmentName>Services.Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services. 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.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

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

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Recursos adicionaisAdditional resources