ASP.NET 核心运行时环境

ASP.NET Core 基于运行时 环境配置应用行为，这通常反映应用在何处运行。

应用程序通常在开发人员的计算机上进行本地开发和测试时在开发环境中运行，遵循一套配置好的行为。 相比之下，当部署到具有一组不同配置行为的服务器时，它们在 生产 环境中运行。 可以使用任意数量的附加环境，例如框架提供的 过渡 环境，用于在实时部署或开发人员创建的其他环境之前暂存应用。

本文介绍应用运行时环境、如何使用环境来控制应用行为，以及如何设置环境。

有关 Blazor 环境指南（补充或取代本文中的指南），请参阅 ASP.NET Core Blazor 环境。

Environments

尽管环境可以是任何字符串值，但框架提供了以下环境值：

• Development
• Staging
• Production

生产环境配置为最大程度地提高安全性、性能和应用可靠性。 与开发环境不同的常见开发人员设置和配置包括：

• 启用 缓存。
• 捆绑和缩小客户端资源，并可能从 CDN 提供它们。
• 禁用诊断错误页并启用友好错误页。
• 启用生产日志记录和监控。 例如，为 Azure Application Insights 启用日志记录。

应用读取的最后一个环境设置决定了应用的环境。 应用运行时无法更改应用的环境。

伐木业

启动时正在运行的应用的命令行界面中的输出指示应用的环境。 在以下示例中，应用在过渡环境中运行：

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

确定运行时环境的环境变量

为了确定运行时环境，ASP.NET Core 从以下环境变量中读取信息：

如果未设置DOTNET_ENVIRONMENT和ASPNETCORE_ENVIRONMENT环境变量，则生产环境是默认环境。

在 Windows 和 macOS 上，环境变量名称不区分大小写。 Linux 环境变量区分大小写。

根据环境控制代码执行

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

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

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

    ...
}

在应用中，提供有关 IHostEnvironment 应用的托管环境的一般信息，属性 IHostEnvironment.EnvironmentName 指示应用的当前环境。

控制呈现的内容

将 IHostEnvironment 注入服务器呈现的 Razor 组件，并使用服务的扩展方法和 EnvironmentName 属性来确定呈现内容的环境。

@inject IHostEnvironment Env

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

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

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

有关需要环境来控制客户端渲染的 Blazor Web App，请参阅 预呈现 ASP.NET 核心 Razor 组件。

运行应用时，在命令行界面中设置环境 （dotnet run）

使用选项-e|--environment设置环境：

dotnet run -e Staging

使用启动设置文件设置环境 （launchSettings.json）

可以在项目文件Properties\launchSettings.json中设置本地开发环境。 系统环境中设置的值会被 launchSettings.json 中设置的环境值覆盖。

launchSettings.json 文件：

• 仅在本地开发计算机上使用。
• 应用发布时不会部署。
• 可能包含多个配置文件，每个配置文件配置不同的环境。

以下示例使用https环境变量为ASPNETCORE_ENVIRONMENT启动配置文件设置暂存环境：

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

在 Visual Studio 中，通过启动配置文件有两种方法设置环境设置：

• 在解决方案资源管理器中右键单击项目后，按 +Enter 或选择“属性”。 选择 “调试>常规”，然后选择 “打开调试启动配置文件 UI ”链接。

• 在解决方案资源管理器中选择项目后，从“调试”菜单中选择“{PROJECT NAME} 调试属性”，其中{PROJECT NAME}占位符是项目名称。

上述方法打开 “启动配置文件 ”对话框，可在其中编辑文件中的 launchSettings.json 环境变量设置。 在 Web 服务器重新启动之前，对项目配置文件所做的更改可能不会生效。 必须重启 Kestrel 才能检测到对其环境所做的更改。

可以在 Visual Studio 用户界面中开始按钮 (►) 旁选择配置文件。

当解决方案包含多个项目时，仅设置启动项目的环境。

或者，使用dotnet run命令，并将-lp|--launch-profile选项设置为配置文件的名称。 此方法仅支持基于命令的 Project 启动配置文件。

dotnet run -lp "https"

将 Visual Studio Code 与 适用于 Visual Studio Code 的 C# 开发工具包 （VS Code 中的 C# 入门）配合使用时，启动配置文件将从应用 launchSettings.json 的文件中提取。

如果未使用 C# 开发工具包，请在env部分中设置ASPNETCORE_ENVIRONMENT环境变量，以及在该部分中设置的任何其他环境变量.vscode/launch.json。

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

.vscode/launch.json 文件仅由 Visual Studio Code 使用。

使用环境变量设置环境

通常，可以使用环境变量或平台设置来设置用于测试的特定环境。 如果未设置环境，则默认为生产环境，这会禁用大多数调试功能。 设置环境的方法取决于操作系统。

Azure App 服务

部署到 Azure 应用服务的应用 默认采用生产环境。

若要设置 ASPNETCORE_ENVIRONMENT 环境变量，请参阅 Azure 文档中的以下资源：

• 配置应用服务应用
• 在 Azure 应用服务中设置过渡环境

添加、更改或删除应用设置后，Azure 应用服务会自动重启应用。

为进程设置环境变量

若要在开始使用ASPNETCORE_ENVIRONMENT应用时为当前会话（命令行界面）设置dotnet run环境变量，请使用以下命令。 设置环境变量后，应用在没有启动配置文件的情况下，用--no-launch-profile选项启动。

1. 在命令行界面中，使用适用于作系统的相应方法设置环境变量。

2. 在不使用启动配置文件的情况下执行 dotnet run命令。

   dotnet run --no-launch-profile
   

使用 PowerShell 时，可以在以下两个命令中组合上述步骤。 以下示例设置过渡环境：

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

全局设置环境变量

使用适用于操作系统的适当的指导来设置ASPNETCORE_ENVIRONMENT环境变量。

ASPNETCORE_ENVIRONMENT全局设置环境变量时，它将对dotnet run设置值后打开的任何命令行界面中的命令生效。 文件 中的 launchSettings.json 启动配置文件 设置的环境值替代为系统环境设置的值。

为部署到 IIS 的应用设置环境

要通过ASPNETCORE_ENVIRONMENT文件设置web.config环境变量，请参阅web.config 文件。

若要在部署到 IIS 时设置环境变量，请在<EnvironmentName>或项目文件中包括该属性。 以下示例在发布项目时将环境 web.config 设置为过渡环境：

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

若要为独立应用程序池中运行的应用设置 ASPNETCORE_ENVIRONMENT 环境变量（在 IIS 10.0 或更高版本上受支持），请参阅 环境变量 <environmentVariables>。 ASPNETCORE_ENVIRONMENT为应用程序池设置环境变量时，其值将替代系统级别的设置。

在 IIS 中托管应用并添加或更改 ASPNETCORE_ENVIRONMENT 环境变量时 ，请使用以下 任一方法使新值对运行应用生效：

• 执行 net stop was /y，然后在命令行中执行 net start w3svc。
• 重新启动服务器。

Docker

使用本部分中的任何方法设置应用的环境。

使用 Dockerfile

在 Dockerfile 中，使用ENV指令设置ASPNETCORE_ENVIRONMENT环境变量：

ENV ASPNETCORE_ENVIRONMENT=Staging

使用 Docker Compose

对于使用 Docker Compose 管理的多服务应用，请在文件中定义 ASPNETCORE_ENVIRONMENT 环境变量 docker-compose.yml ：

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

使用 Docker Compose 在运行时设置的环境会替代 Dockerfile 设置的环境。

使用docker run命令

使用docker run命令运行 Docker 容器时，使用ASPNETCORE_ENVIRONMENT选项设置-e|--env环境变量：

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

运行时设置的环境，替代 docker run Dockerfile 设置的环境。

Docker 环境文件

使用 Docker 环境文件 .env 设置 ASPNETCORE_ENVIRONMENT 环境变量。

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

在执行docker run命令时，使用--env-file选项加载文件：

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

运行时设置的环境，替代 docker run Dockerfile 设置的环境。

在应用的启动代码中设置环境

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

按环境加载配置

若要按环境加载配置，请参阅 ASP.NET Core 中的配置。

从 Startup 类中访问环境

.NET 6 发布之前需要使用 Startup 类（Startup.cs）的 Configure 和 ConfigureServices 方法，并且仍受支持。

IWebHostEnvironment注入Startup构造函数以控制代码执行。 当应用只需为少数环境配置启动代码，并且每个环境的启动代码差异很小时，此方法非常有用。

在以下示例中，环境保存在 _env 字段中，并基于应用的环境控制代码执行：

public class Startup
{
    private readonly IWebHostEnvironment _env;

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

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

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

        ...
    }
}

特定于 Startup 环境的类

应用可以使用命名约定Startup类为不同环境定义多个Startup{EnvironmentName}类，其中{ENVIRONMENT NAME}占位符是环境名称。

优先考虑名称后缀与当前环境相匹配的类。 如果找不到匹配的 Startup{EnvironmentName}，就会使用 Startup 类。

若要实现基于 Startup 环境的类，请根据需要创建多个 Startup{EnvironmentName} 类和后备 Startup 类：

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

在创建主机生成器的位置，调用一个接受程序集名称的 HostingAbstractionsWebHostBuilderExtensions.UseStartup 方法，以加载正确的 Startup 类。

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

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

环境特定的 Startup 类方法

Configure和ConfigureServices 方法支持特定环境的表单版本 Configure{ENVIRONMENT NAME} 和 Configure{ENVIRONMENT NAME}Services，其中{ENVIRONMENT NAME}占位符表示环境名称。 如果未为命名的方法找到匹配的环境名称，则分别使用 ConfigureServices 或 Configure 方法。

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

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

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

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

其他资源

• 查看或下载示例代码（如何下载）
• ASP.NET Core 中的应用启动
• ASP.NET Core 中的配置
• ASP.NET Core Blazor 环境