ASP.NET Core 模块ASP.NET Core Module

本文内容

作者：Tom Dykstra、Rick Strahl、Chris Ross、Rick Anderson、Sourabh Shirhatti 和 Justin Kotalik

ASP.NET Core 模块是插入 IIS 管道的本机 IIS 模块，用于：

• 在 IIS 工作进程 (w3wp.exe) 内托管 ASP.NET Core 应用，称为进程内托管模型。
• 将 Web 请求转发到运行 Kestrel 服务器的后端 ASP.NET Core 应用，称为进程外托管模型。

受支持的 Windows 版本：

• Windows 7 或更高版本
• Windows Server 2008 R2 或更高版本

在进程内托管时，该模块会使用 IIS 进程内服务器实现，即 IIS HTTP 服务器 (IISHttpServer)。

在进程外托管时，该模块仅适用于 Kestrel。该模块无法与 HTTP.sys 一起工作。

托管模型Hosting models

进程内托管模型In-process hosting model

ASP.NET Core 应用默认为进程内托管模型。

在进程内托管时，将应用以下特征：

• 使用 IIS HTTP 服务器 (IISHttpServer) 而不是 Kestrel 服务器。在进程内，CreateDefaultBuilder 调用 UseIIS 以执行以下操作：

  • 注册 IISHttpServer。
  • 在 ASP.NET Core 模块后运行时，配置服务器应侦听的端口和基本路径。
  • 配置主机以捕获启动错误。

• requestTimeout 属性不适用于进程内托管。

• 不支持在应用之间共享应用池。每个应用使用一个应用池。

• 使用 Web 部署或手动将 app_offline.htm 文件置于部署中时，如果有已打开的连接，则应用可能不会立即关闭。例如，WebSocket 连接可能会延迟应用关闭。

• 应用和已安装的运行时（x64 或 x86）的体系结构（位数）必须与应用池的体系结构匹配。

• 检测到客户端连接断开。客户端连接断开时，HttpContext.RequestAborted 取消标记将会取消。

• 在 ASP.NET Core 2.2.1 或早期版本中，GetCurrentDirectory 会返回 IIS 启动的进程的工作目录而非应用目录（例如，对于 w3wp.exe，是 C:\Windows\System32\inetsrv ）。

对于设置应用的当前目录的示例代码，请参阅 CurrentDirectoryHelpers 类。调用 SetCurrentDirectory 方法。后续 GetCurrentDirectory 调用提供应用的目录。

• 在进程内托管时，不会在内部调用 AuthenticateAsync 来初始化用户。因此，默认情况下不激活每次身份验证后用于转换声明的 IClaimsTransformation 实现。使用 IClaimsTransformation 实现转换声明时，请调用 AddAuthentication 以添加身份验证服务：

public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}
public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}

• 不支持 Web 包（单文件）部署。

进程外托管模型Out-of-process hosting model

若要配置进程外托管应用，请在项目文件 ( .csproj) 中将 <AspNetCoreHostingModel> 属性的值设置为 OutOfProcess：

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

进程内托管设为 InProcess，这是默认值。

<AspNetCoreHostingModel> 的值不区分大小写，因此 inprocess 和 outofprocess 均为有效值。

使用 Kestrel 服务器，而不是 IIS HTTP 服务器 (IISHttpServer)。

在进程外，CreateDefaultBuilder 调用 UseIISIntegration 以执行以下操作：

• 在 ASP.NET Core 模块后运行时，配置服务器应侦听的端口和基本路径。
• 配置主机以捕获启动错误。

托管模型更改Hosting model changes

如果 hostingModel 设置在 web.config 文件中被更改（如 web.config 的配置部分中所述），则该模块会再循环 IIS 工作进程。

对于 IIS Express，该模块不会再循环工作进程，但改为触发当前 IIS Express 进程的正常关闭。应用的下一个请求会生成新的 IIS Express 进程。

进程名Process name

Process.GetCurrentProcess().ProcessName 报告 w3wp/iisexpress（进程内）或 dotnet（进程外）。

许多本机模块（如 Windows 身份验证）仍处于活动状态。要详细了解随 ASP.NET Core 模块活动的 IIS 模块，请参阅 IIS 模块与 ASP.NET Core。

ASP.NET Core 模块还可以：

• 为工作进程设置环境变量。
• 将 stdout 输出记录到文件存储器，以解决启动问题。
• 转发 Windows 身份验证令牌。

如何安装和使用 ASP.NET Core 模块How to install and use the ASP.NET Core Module

有关如何安装 ASP.NET Core 模块的说明，请参阅安装 .NET Core 托管捆绑包。

web.config 的配置Configuration with web.config

在站点的 web.config 文件中使用 system.webServer 节点的 aspNetCore 部分配置 ASP.NET Core 模块。

以下 web.config 文件发布用于依赖框架的部署，并配置 ASP.NET Core 模块以处理站点请求：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

以下 web.config 发布用于独立部署：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

将 InheritInChildApplications 属性设置为 false，表示 <> 元素中指定的设置不会由驻留在应用子目录中的应用继承。

将应用部署为 Azure 应用服务时，stdoutLogFile 路径将设置为 \?\%home%\LogFiles\stdout。该路径会将 stdout 日志保存到 LogFiles 文件夹，该文件夹是由服务自动创建的位置。

有关 IIS 子应用程序配置的信息，请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。

aspNetCore 元素的属性Attributes of the aspNetCore element

设置环境变量Set environment variables

可以为 processPath 属性中的进程指定环境变量。使用 <environmentVariables> 集合元素的 <environmentVariable> 子元素指定环境变量。本部分中设置的环境变量优先于系统环境变量。

以下示例在 web.config 中设置两个环境变量。ASPNETCORE_ENVIRONMENT 将应用的环境配置为 Development。开发人员可能会暂时在 web.config 文件中设置此值，以便在调试应用异常时强制加载开发人员异常页面。CONFIG_DIR 是用户定义的环境变量的一个示例，其中开发人员已写入可在启动时读取值的代码以便形成用于加载应用配置文件的路径。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

备注

直接在 web.config 中设置环境的替代方法是将 <EnvironmentName> 属性包含在发布配置文件 (.pubxml) 或项目文件中。此方法在发布项目时设置 web.config 中的环境：

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

警告

仅当不受信任的网络（如 Internet）无法访问暂存和测试服务器时，才能将 ASPNETCORE_ENVIRONMENT 环境变量设置为 Development。

app_offline.htmapp_offline.htm

如果在应用的根目录中检测到名为 “app_offline.htm” 的文件，ASP.NET Core 模块将尝试正常关闭应用并停止处理传入请求。如果应用在 shutdownTimeLimit 中定义的秒数之后仍在运行，ASP.NET Core 模块将终止正在运行的进程。

存在 app_offline.htm 文件时，ASP.NET Core 模块会通过发送回 app_offline.htm 文件的内容来响应请求。删除 app_offline.htm 文件后，下一个请求将启动应用。

使用进程外托管模型时，如果有已打开的连接，则应用可能不会立即关闭。例如，WebSocket 连接可能会延迟应用关闭。

启动错误页面Start-up error page

进程内和进程外托管在无法启动应用时均会生成自定义错误页面。

如果 ASP.NET Core 模块无法找到进程内或进程外请求处理程序，则会显示“500.0 - 进程内/进程外处理程序加载失败”状态代码页 。

对于进程内托管，如果 ASP.NET Core 模块无法启动应用，则会显示“500.30 - 启动失败”状态代码页 。

对于进程外托管，如果 ASP.NET Core 模块无法启动后端进程或后端进程启动但无法在配置的端口上侦听，则将显示“502.5 - 进程失败” 状态代码页。

若要禁止显示此页面并还原为默认 IIS 5xx 状态代码页，请使用 disableStartUpErrorPage 属性。有关配置自定义错误消息的详细信息，请参阅 HTTP 错误 <httpErrors>。

日志创建和重定向Log creation and redirection

如果已设置 aspNetCore 元素的 stdoutLogEnabled 和 stdoutLogFile 属性，ASP.NET Core 模块会将 stdout 和 stderr 控制台输出重定向到磁盘。创建日志文件时，模块会创建 stdoutLogFile 路径中提供的所有文件夹。应用池必须对写入日志的位置具有写入权限（使用 IIS AppPool\<app_pool_name> 提供写入权限）。

日志不会旋转，除非回收/重新启动进程。宿主负责限制日志占用的磁盘空间。

仅当在 IIS 上托管或使用 Visual Studio 中针对 IIS 的开发时支持时，而不是在本地调试和使用 IIS Express 运行应用时，才建议使用 stdout 日志来排查应用程序启动问题。

不要将 stdout 日志用于常规应用日志记录。对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

创建日志文件时，将自动添加时间戳和文件扩展名。日志文件名是通过将时间戳、进程 ID 和文件扩展名 (.log ) 附加到由下划线分隔的 stdoutLogFile 路径的最后一段（通常为 stdout ）组合而成的。如果 stdoutLogFile 路径以 stdout 结尾，则 PID 为 1934 且于 2018 年 2 月 5 日 19:42:32 创建的应用的日志的文件名为 stdout_20180205194132_1934.log 。

如果 stdoutLogEnabled 为 false，则会捕获应用启动时发生的错误，并将其发送到事件日志，最大为 30 KB。启动后，将丢弃所有其他日志。

以下示例 aspNetCore 元素在相对路径 .\log\ 上配置 stdout 日志记录。确认应用池用户标识是否已提供写入路径的权限。

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

发布用于 Azure 应用服务部署的应用时，Web SDK 会将 stdoutLogFile 值设置为 \?\%home%\LogFiles\stdout。已为 Azure 应用服务托管的应用预定义了 %home 环境变量。

要创建日志记录筛选器规则，请参阅 ASP.NET Core 日志记录文档的配置和日志筛选部分。

有关路径格式的详细信息，请参阅 Windows 系统上的文件路径格式。

增强的诊断日志Enhanced diagnostic logs

可以配置 ASP.NET Core 模块，以提供增强的诊断日志。向 web.config 中的 <aspNetCore> 元素添加 <handlerSettings> 元素 。将 debugLevel 设置为 TRACE 将提供更准确的诊断信息：

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

创建日志文件时，路径中的任何文件夹（上述示例中为 logs ）由模块创建。应用池必须对写入日志的位置具有写入权限（使用 IIS AppPool\<app_pool_name> 提供写入权限）。

调试级别 (debugLevel) 值可以同时包含级别和位置。

级别（详细程度由低到高）：

• 错误
• 警告
• 信息
• TRACE

位置（允许多个位置）：

• CONSOLE
• 事件日志
• 文件

还可以通过环境变量提供处理程序设置：

• ASPNETCORE_MODULE_DEBUG_FILE – 调试日志文件的路径。（默认值：aspnetcore debug.log）
• ASPNETCORE_MODULE_DEBUG – 调试级别设置。

警告

部署中启用的调试日志记录的时间不要超出排除故障所需的时间 。日志大小不限。持续启用调试日志可能耗尽可用磁盘空间并导致服务器或应用服务崩溃。

有关 web.config 文件中的 aspNetCore 元素的示例，请参阅 web.config 的配置。

修改堆栈大小Modify the stack size

仅适用于使用进程内托管模型的情况。

使用 web.config 中的 stackSize 设置（以字节为单位）配置托管堆栈大小 。默认大小为 1048576 个字节 (1 MB)。

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

代理配置使用 HTTP 协议和配对令牌Proxy configuration uses HTTP protocol and a pairing token

仅适用于进程外托管。

在 ASP.NET Core 模块和 Kestrel 之间创建的代理使用 HTTP 协议。因此，不存在从脱离服务器的位置窃取模块和 Kestrel 之间的流量的风险。

配对令牌用于保证 Kestrel 收到的请求已由 IIS 代理且不来自某些其他源。模块已创建配对令牌并将其设置到环境变量 (ASPNETCORE_TOKEN)。此外，配对令牌还设置到每个代理请求的标头 (MS-ASPNETCORE-TOKEN)。IIS 中间件检查它所接收的每个请求，以确认配对令牌标头值与环境变量值相匹配。如果令牌值不匹配，则将记录请求并拒绝该请求。无法从脱离服务器的位置访问配对令牌环境变量及模块和 Kestrel 之间的流量。如果不知道配对令牌值，攻击者就无法提交绕过 IIS 中间件中的检查的请求。

具有 IIS 共享配置的 ASP.NET Core 模块ASP.NET Core Module with an IIS Shared Configuration

ASP.NET Core 模块安装程序使用 TrustedInstaller 帐户的权限运行 。由于本地系统帐户没有 IIS 共享配置所用的共享路径的修改权限，因此在尝试配置共享上的 applicationHost.config 文件中的模块设置时，安装程序将引发拒绝访问错误 。

在与 IIS 安装相同的计算机上使用 IIS 共享配置时，请运行 ASP.NET Core Hosting Bundle 安装程序，并将 OPT_NO_SHARED_CONFIG_CHECK 参数设置为 1：

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

如果共享配置的路径与 IIS 安装的路径不在同一台计算机上，请按照下列步骤操作：

• 禁用 IIS 共享配置。
• 运行安装程序。
• 将已更新的 applicationHost.config 文件导出到共享。
• 重新启用 IIS 共享配置。

模块版本和托管捆绑安装程序日志Module version and Hosting Bundle installer logs

若要确定已安装 ASP.NET Core 模块的版本，请执行以下操作：

• 在托管系统上，导航到 %windir%\System32\inetsrv 。
• 找到 aspnetcore.dll 文件。
• 右键单击该文件，然后从上下文菜单中选择“属性” 。
• 选择“详细信息”选项卡 。“文件版本” 和“产品版本” 表示模块的已安装版本。
  在 C:\Users\%UserName%\AppData\Local\Temp 中找到了模块的托管捆绑安装程序日志。该文件名为 ddDotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log 。

模块、架构和配置文件位置Module, schema, and configuration file locations

模块Module

IIS (x86/amd64) ：

• %windir%\System32\inetsrv\aspnetcore.dll

• %windir%\SysWOW64\inetsrv\aspnetcore.dll

• %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

• %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64) ：

• %ProgramFiles%\IIS Express\aspnetcore.dll

• %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

• %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

• %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

架构Schema

IIS

• %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

• %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

• %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

• %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

ConfigurationConfiguration

IIS

• %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

• Visual Studio：{APPLICATION ROOT}.vs\config\applicationHost.config

• iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

可以通过在 applicationHost.config 文件中搜索 aspnetcore 找到这些文件。

ASP.NET Core 模块是插入 IIS 管道的本机 IIS 模块，用于：

• 在 IIS 工作进程 (w3wp.exe) 内托管 ASP.NET Core 应用，称为进程内托管模型。
• 将 Web 请求转发到运行 Kestrel 服务器的后端 ASP.NET Core 应用，称为进程外托管模型。

受支持的 Windows 版本：

• Windows 7 或更高版本
• Windows Server 2008 R2 或更高版本

在进程内托管时，该模块会使用 IIS 进程内服务器实现，即 IIS HTTP 服务器 (IISHttpServer)。

在进程外托管时，该模块仅适用于 Kestrel。该模块无法与 HTTP.sys 一起工作。

托管模型Hosting models

进程内托管模型In-process hosting model

若要配置用于进程内托管的应用，请将 <AspNetCoreHostingModel> 属性添加到值为 InProcess（进程外托管使用 OutOfProcess 进行设置）的应用项目文件：

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

定目标到 .NET Framework 的 ASP.NET Core 应用不支持进程内托管模型。

<AspNetCoreHostingModel> 的值不区分大小写，因此 inprocess 和 outofprocess 均为有效值。

如果文件中不存在 <AspNetCoreHostingModel> 属性，则默认值为 OutOfProcess。

在进程内托管时，将应用以下特征：

• 使用 IIS HTTP 服务器 (IISHttpServer) 而不是 Kestrel 服务器。在进程内，CreateDefaultBuilder 调用 UseIIS 以执行以下操作：

  • 注册 IISHttpServer。
  • 在 ASP.NET Core 模块后运行时，配置服务器应侦听的端口和基本路径。
  • 配置主机以捕获启动错误。

• requestTimeout 属性不适用于进程内托管。

• 不支持在应用之间共享应用池。每个应用使用一个应用池。

• 使用 Web 部署或手动将 app_offline.htm 文件置于部署中时，如果有已打开的连接，则应用可能不会立即关闭。例如，WebSocket 连接可能会延迟应用关闭。

• 应用和已安装的运行时（x64 或 x86）的体系结构（位数）必须与应用池的体系结构匹配。

• 检测到客户端连接断开。客户端连接断开时，HttpContext.RequestAborted 取消标记将会取消。

• 在 ASP.NET Core 2.2.1 或早期版本中，GetCurrentDirectory 会返回 IIS 启动的进程的工作目录而非应用目录（例如，对于 w3wp.exe，是 C:\Windows\System32\inetsrv ）。

对于设置应用的当前目录的示例代码，请参阅 CurrentDirectoryHelpers 类。调用 SetCurrentDirectory 方法。后续 GetCurrentDirectory 调用提供应用的目录。

• 在进程内托管时，不会在内部调用 AuthenticateAsync 来初始化用户。因此，默认情况下不激活每次身份验证后用于转换声明的 IClaimsTransformation 实现。使用 IClaimsTransformation 实现转换声明时，请调用 AddAuthentication 以添加身份验证服务：

public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}
public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}

进程外托管模型Out-of-process hosting model

若要配置进程外托管应用，请在项目文件中使用以下方法之一：

• 不指定 <AspNetCoreHostingModel> 属性。如果文件中不存在 <AspNetCoreHostingModel> 属性，则默认值为 OutOfProcess。
• 将 <AspNetCoreHostingModel> 属性的值设为 OutOfProcess（进程内托管设为 InProcess）：

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

值不区分大小写，因此 inprocess 和 outofprocess 均为有效值。

使用 Kestrel 服务器，而不是 IIS HTTP 服务器 (IISHttpServer)。

在进程外，CreateDefaultBuilder 调用 UseIISIntegration 以执行以下操作：

• 在 ASP.NET Core 模块后运行时，配置服务器应侦听的端口和基本路径。
• 配置主机以捕获启动错误。

托管模型更改Hosting model changes

如果 hostingModel 设置在 web.config 文件中被更改（如 web.config 的配置部分中所述），则该模块会再循环 IIS 工作进程。

对于 IIS Express，该模块不会再循环工作进程，但改为触发当前 IIS Express 进程的正常关闭。应用的下一个请求会生成新的 IIS Express 进程。

进程名Process name

Process.GetCurrentProcess().ProcessName 报告 w3wp/iisexpress（进程内）或 dotnet（进程外）。

许多本机模块（如 Windows 身份验证）仍处于活动状态。要详细了解随 ASP.NET Core 模块活动的 IIS 模块，请参阅 IIS 模块与 ASP.NET Core。

ASP.NET Core 模块还可以：

• 为工作进程设置环境变量。
• 将 stdout 输出记录到文件存储器，以解决启动问题。
• 转发 Windows 身份验证令牌。

如何安装和使用 ASP.NET Core 模块How to install and use the ASP.NET Core Module

有关如何安装 ASP.NET Core 模块的说明，请参阅安装 .NET Core 托管捆绑包。

web.config 的配置Configuration with web.config

在站点的 web.config 文件中使用 system.webServer 节点的 aspNetCore 部分配置 ASP.NET Core 模块。

以下 web.config 文件发布用于依赖框架的部署，并配置 ASP.NET Core 模块以处理站点请求：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

以下 web.config 发布用于独立部署：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

将 InheritInChildApplications 属性设置为 false，表示 <> 元素中指定的设置不会由驻留在应用子目录中的应用继承。

将应用部署为 Azure 应用服务时，stdoutLogFile 路径将设置为 \?\%home%\LogFiles\stdout。该路径会将 stdout 日志保存到 LogFiles 文件夹，该文件夹是由服务自动创建的位置。

有关 IIS 子应用程序配置的信息，请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。

aspNetCore 元素的属性Attributes of the aspNetCore element

设置环境变量Setting environment variables

可以为 processPath 属性中的进程指定环境变量。使用 <environmentVariables> 集合元素的 <environmentVariable> 子元素指定环境变量。本部分中设置的环境变量优先于系统环境变量。

以下示例设置了两个环境变量。ASPNETCORE_ENVIRONMENT 将应用的环境配置为 Development。开发人员可能会暂时在 web.config 文件中设置此值，以便在调试应用异常时强制加载开发人员异常页面。CONFIG_DIR 是用户定义的环境变量的一个示例，其中开发人员已写入可在启动时读取值的代码以便形成用于加载应用配置文件的路径。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

备注

直接在 web.config 中设置环境的替代方法是将 <EnvironmentName> 属性包含在发布配置文件 (.pubxml) 或项目文件中。此方法在发布项目时设置 web.config 中的环境：

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

警告

仅当不受信任的网络（如 Internet）无法访问暂存和测试服务器时，才能将 ASPNETCORE_ENVIRONMENT 环境变量设置为 Development。

app_offline.htmapp_offline.htm

如果在应用的根目录中检测到名为 “app_offline.htm” 的文件，ASP.NET Core 模块将尝试正常关闭应用并停止处理传入请求。如果应用在 shutdownTimeLimit 中定义的秒数之后仍在运行，ASP.NET Core 模块将终止正在运行的进程。

存在 app_offline.htm 文件时，ASP.NET Core 模块会通过发送回 app_offline.htm 文件的内容来响应请求。删除 app_offline.htm 文件后，下一个请求将启动应用。

使用进程外托管模型时，如果有已打开的连接，则应用可能不会立即关闭。例如，WebSocket 连接可能会延迟应用关闭。

启动错误页面Start-up error page

进程内和进程外托管在无法启动应用时均会生成自定义错误页面。

如果 ASP.NET Core 模块无法找到进程内或进程外请求处理程序，则会显示“500.0 - 进程内/进程外处理程序加载失败”状态代码页 。

对于进程内托管，如果 ASP.NET Core 模块无法启动应用，则会显示“500.30 - 启动失败”状态代码页 。

对于进程外托管，如果 ASP.NET Core 模块无法启动后端进程或后端进程启动但无法在配置的端口上侦听，则将显示“502.5 - 进程失败” 状态代码页。

若要禁止显示此页面并还原为默认 IIS 5xx 状态代码页，请使用 disableStartUpErrorPage 属性。有关配置自定义错误消息的详细信息，请参阅 HTTP 错误 <httpErrors>。

日志创建和重定向Log creation and redirection

如果已设置 aspNetCore 元素的 stdoutLogEnabled 和 stdoutLogFile 属性，ASP.NET Core 模块会将 stdout 和 stderr 控制台输出重定向到磁盘。创建日志文件时，模块会创建 stdoutLogFile 路径中提供的所有文件夹。应用池必须对写入日志的位置具有写入权限（使用 IIS AppPool\<app_pool_name> 提供写入权限）。

日志不会旋转，除非回收/重新启动进程。宿主负责限制日志占用的磁盘空间。

仅当在 IIS 上托管或使用 Visual Studio 中针对 IIS 的开发时支持时，而不是在本地调试和使用 IIS Express 运行应用时，才建议使用 stdout 日志来排查应用程序启动问题。

不要将 stdout 日志用于常规应用日志记录。对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

创建日志文件时，将自动添加时间戳和文件扩展名。日志文件名是通过将时间戳、进程 ID 和文件扩展名 (.log ) 附加到由下划线分隔的 stdoutLogFile 路径的最后一段（通常为 stdout ）组合而成的。如果 stdoutLogFile 路径以 stdout 结尾，则 PID 为 1934 且于 2018 年 2 月 5 日 19:42:32 创建的应用的日志的文件名为 stdout_20180205194132_1934.log 。

如果 stdoutLogEnabled 为 false，则会捕获应用启动时发生的错误，并将其发送到事件日志，最大为 30 KB。启动后，将丢弃所有其他日志。

以下示例 aspNetCore 元素在相对路径 .\log\ 上配置 stdout 日志记录。确认应用池用户标识是否已提供写入路径的权限。

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

发布用于 Azure 应用服务部署的应用时，Web SDK 会将 stdoutLogFile 值设置为 \?\%home%\LogFiles\stdout。已为 Azure 应用服务托管的应用预定义了 %home 环境变量。

有关路径格式的详细信息，请参阅 Windows 系统上的文件路径格式。

增强的诊断日志Enhanced diagnostic logs

可以配置 ASP.NET Core 模块，以提供增强的诊断日志。向 web.config 中的 <aspNetCore> 元素添加 <handlerSettings> 元素 。将 debugLevel 设置为 TRACE 将提供更准确的诊断信息：

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

提供给 <handlerSetting> 值（上述示例中为 logs ）的路径中的文件夹不是由模块自动创建的，并且应该预先存在于部署中。应用池必须对写入日志的位置具有写入权限（使用 IIS AppPool\<app_pool_name> 提供写入权限）。

调试级别 (debugLevel) 值可以同时包含级别和位置。

级别（详细程度由低到高）：

• 错误
• 警告
• 信息
• TRACE

位置（允许多个位置）：

• CONSOLE
• 事件日志
• 文件

还可以通过环境变量提供处理程序设置：

• ASPNETCORE_MODULE_DEBUG_FILE – 调试日志文件的路径。（默认值：aspnetcore debug.log）
• ASPNETCORE_MODULE_DEBUG – 调试级别设置。

警告

部署中启用的调试日志记录的时间不要超出排除故障所需的时间 。日志大小不限。持续启用调试日志可能耗尽可用磁盘空间并导致服务器或应用服务崩溃。

有关 web.config 文件中的 aspNetCore 元素的示例，请参阅 web.config 的配置。

代理配置使用 HTTP 协议和配对令牌Proxy configuration uses HTTP protocol and a pairing token

仅适用于进程外托管。

在 ASP.NET Core 模块和 Kestrel 之间创建的代理使用 HTTP 协议。因此，不存在从脱离服务器的位置窃取模块和 Kestrel 之间的流量的风险。

配对令牌用于保证 Kestrel 收到的请求已由 IIS 代理且不来自某些其他源。模块已创建配对令牌并将其设置到环境变量 (ASPNETCORE_TOKEN)。此外，配对令牌还设置到每个代理请求的标头 (MS-ASPNETCORE-TOKEN)。IIS 中间件检查它所接收的每个请求，以确认配对令牌标头值与环境变量值相匹配。如果令牌值不匹配，则将记录请求并拒绝该请求。无法从脱离服务器的位置访问配对令牌环境变量及模块和 Kestrel 之间的流量。如果不知道配对令牌值，攻击者就无法提交绕过 IIS 中间件中的检查的请求。

具有 IIS 共享配置的 ASP.NET Core 模块ASP.NET Core Module with an IIS Shared Configuration

ASP.NET Core 模块安装程序使用 TrustedInstaller 帐户的权限运行 。由于本地系统帐户没有 IIS 共享配置所用的共享路径的修改权限，因此在尝试配置共享上的 applicationHost.config 文件中的模块设置时，安装程序将引发拒绝访问错误 。

在与 IIS 安装相同的计算机上使用 IIS 共享配置时，请运行 ASP.NET Core Hosting Bundle 安装程序，并将 OPT_NO_SHARED_CONFIG_CHECK 参数设置为 1：

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

如果共享配置的路径与 IIS 安装的路径不在同一台计算机上，请按照下列步骤操作：

• 禁用 IIS 共享配置。
• 运行安装程序。
• 将已更新的 applicationHost.config 文件导出到共享。
• 重新启用 IIS 共享配置。

模块版本和托管捆绑安装程序日志Module version and Hosting Bundle installer logs

若要确定已安装 ASP.NET Core 模块的版本，请执行以下操作：

• 在托管系统上，导航到 %windir%\System32\inetsrv 。
• 找到 aspnetcore.dll 文件。
• 右键单击该文件，然后从上下文菜单中选择“属性” 。
• 选择“详细信息”选项卡 。“文件版本” 和“产品版本” 表示模块的已安装版本。
  在 C:\Users\%UserName%\AppData\Local\Temp 中找到了模块的托管捆绑安装程序日志。该文件名为 ddDotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log 。

模块、架构和配置文件位置Module, schema, and configuration file locations

模块Module

IIS (x86/amd64) ：

• %windir%\System32\inetsrv\aspnetcore.dll

• %windir%\SysWOW64\inetsrv\aspnetcore.dll

• %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

• %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64) ：

• %ProgramFiles%\IIS Express\aspnetcore.dll

• %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

• %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

• %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

架构Schema

IIS

• %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

• %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

• %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

• %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

ConfigurationConfiguration

IIS

• %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

• Visual Studio：{APPLICATION ROOT}.vs\config\applicationHost.config

• iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

可以通过在 applicationHost.config 文件中搜索 aspnetcore 找到这些文件。

ASP.NET Core 模块是插入 IIS 管道的本机 IIS 模块，用于将 Web 请求转发到后端 ASP.NET Core 应用。

受支持的 Windows 版本：

• Windows 7 或更高版本
• Windows Server 2008 R2 或更高版本

该模块仅适用于 Kestrel。该模块与 HTTP.sys 不兼容。

由于 ASP.NET Core 应用在独立于 IIS 辅助进程的进程中运行，因此该模块还处理进程管理。该模块在第一个请求到达时启动 ASP.NET Core 应用的进程，并在应用崩溃时重新启动该应用。这基本上与在 Windows 进程激活服务 (WAS) 托管的 IIS 中在进程内运行的 ASP.NET 4.x 应用中出现的行为相同。

下图说明了 IIS、ASP.NET Core 模块和应用之间的关系：

请求从 Web 到达内核模式 HTTP.sys 驱动程序。驱动程序将请求路由到网站的配置端口上的 IIS，通常为 80 (HTTP) 或 443 (HTTPS)。该模块将该请求转发到应用的随机端口（非端口 80/443）上的 Kestrel。

该模块在启动时通过环境变量指定端口，IIS 集成中间件将服务器配置为侦听 http://localhost:{port}。执行其他检查，拒绝不是来自该模块的请求。该模块不支持 HTTPS 转发，因此即使请求由 IIS 通过 HTTPS 接收，它们还是通过 HTTP 转发。

Kestrel 从模块获取请求后，请求会被推送到 ASP.NET Core 中间件管道中。中间件管道处理该请求并将其作为 HttpContext 实例传递给应用的逻辑。IIS 集成添加的中间件会将方案、远程 IP 和 pathbase 更新到帐户以将请求转发到 Kestrel。应用的响应传递回 IIS，IIS 将响应推送回发起请求的 HTTP 客户端。

许多本机模块（如 Windows 身份验证）仍处于活动状态。要详细了解随 ASP.NET Core 模块活动的 IIS 模块，请参阅 IIS 模块与 ASP.NET Core。

ASP.NET Core 模块还可以：

• 为工作进程设置环境变量。
• 将 stdout 输出记录到文件存储器，以解决启动问题。
• 转发 Windows 身份验证令牌。

如何安装和使用 ASP.NET Core 模块How to install and use the ASP.NET Core Module

有关如何安装 ASP.NET Core 模块的说明，请参阅安装 .NET Core 托管捆绑包。

web.config 的配置Configuration with web.config

在站点的 web.config 文件中使用 system.webServer 节点的 aspNetCore 部分配置 ASP.NET Core 模块。

以下 web.config 文件发布用于依赖框架的部署，并配置 ASP.NET Core 模块以处理站点请求：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\MyApp.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

以下 web.config 发布用于独立部署：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath=".\MyApp.exe"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

将应用部署为 Azure 应用服务时，stdoutLogFile 路径将设置为 \?\%home%\LogFiles\stdout。该路径会将 stdout 日志保存到 LogFiles 文件夹，该文件夹是由服务自动创建的位置。

有关 IIS 子应用程序配置的信息，请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。

aspNetCore 元素的属性Attributes of the aspNetCore element

设置环境变量Setting environment variables

可以为 processPath 属性中的进程指定环境变量。使用 <environmentVariables> 集合元素的 <environmentVariable> 子元素指定环境变量。

警告

本部分中设置的环境变量与使用同一名称设置的系统环境变量冲突。如果在 web.config 文件以及 Windows 中的系统级别中同时设置了环境变量，则 web.config 文件中的值将被追加到系统环境变量值（例如，ASPNETCORE_ENVIRONMENT: Development;Development），这将阻止应用启动。

以下示例设置了两个环境变量。ASPNETCORE_ENVIRONMENT 将应用的环境配置为 Development。开发人员可能会暂时在 web.config 文件中设置此值，以便在调试应用异常时强制加载开发人员异常页面。CONFIG_DIR 是用户定义的环境变量的一个示例，其中开发人员已写入可在启动时读取值的代码以便形成用于加载应用配置文件的路径。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

警告

仅当不受信任的网络（如 Internet）无法访问暂存和测试服务器时，才能将 ASPNETCORE_ENVIRONMENT 环境变量设置为 Development。

app_offline.htmapp_offline.htm

如果在应用的根目录中检测到名为 “app_offline.htm” 的文件，ASP.NET Core 模块将尝试正常关闭应用并停止处理传入请求。如果应用在 shutdownTimeLimit 中定义的秒数之后仍在运行，ASP.NET Core 模块将终止正在运行的进程。

存在 app_offline.htm 文件时，ASP.NET Core 模块会通过发送回 app_offline.htm 文件的内容来响应请求。删除 app_offline.htm 文件后，下一个请求将启动应用。

启动错误页面Start-up error page

如果 ASP.NET Core 模块无法启动后端进程或后端进程启动但无法在配置的端口上侦听，则将显示“502.5 - 进程失败” 状态代码页。若要禁止显示此页面并还原为默认 IIS 502 状态代码页面，请使用 disableStartUpErrorPage 属性。有关配置自定义错误消息的详细信息，请参阅 HTTP 错误 <httpErrors>。

日志创建和重定向Log creation and redirection

如果已设置 aspNetCore 元素的 stdoutLogEnabled 和 stdoutLogFile 属性，ASP.NET Core 模块会将 stdout 和 stderr 控制台输出重定向到磁盘。创建日志文件时，模块会创建 stdoutLogFile 路径中提供的所有文件夹。应用池必须对写入日志的位置具有写入权限（使用 IIS AppPool\<app_pool_name> 提供写入权限）。

日志不会旋转，除非回收/重新启动进程。宿主负责限制日志占用的磁盘空间。

仅当在 IIS 上托管或使用 Visual Studio 中针对 IIS 的开发时支持时，而不是在本地调试和使用 IIS Express 运行应用时，才建议使用 stdout 日志来排查应用程序启动问题。

不要将 stdout 日志用于常规应用日志记录。对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

创建日志文件时，将自动添加时间戳和文件扩展名。日志文件名是通过将时间戳、进程 ID 和文件扩展名 (.log ) 附加到由下划线分隔的 stdoutLogFile 路径的最后一段（通常为 stdout ）组合而成的。如果 stdoutLogFile 路径以 stdout 结尾，则 PID 为 1934 且于 2018 年 2 月 5 日 19:42:32 创建的应用的日志的文件名为 stdout_20180205194132_1934.log 。

以下示例 aspNetCore 元素在相对路径 .\log\ 上配置 stdout 日志记录。确认应用池用户标识是否已提供写入路径的权限。

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout">
</aspNetCore>

发布用于 Azure 应用服务部署的应用时，Web SDK 会将 stdoutLogFile 值设置为 \?\%home%\LogFiles\stdout。已为 Azure 应用服务托管的应用预定义了 %home 环境变量。

要创建日志记录筛选器规则，请参阅 ASP.NET Core 日志记录文档的配置和日志筛选部分。

有关路径格式的详细信息，请参阅 Windows 系统上的文件路径格式。

代理配置使用 HTTP 协议和配对令牌Proxy configuration uses HTTP protocol and a pairing token

在 ASP.NET Core 模块和 Kestrel 之间创建的代理使用 HTTP 协议。因此，不存在从脱离服务器的位置窃取模块和 Kestrel 之间的流量的风险。

配对令牌用于保证 Kestrel 收到的请求已由 IIS 代理且不来自某些其他源。模块已创建配对令牌并将其设置到环境变量 (ASPNETCORE_TOKEN)。此外，配对令牌还设置到每个代理请求的标头 (MS-ASPNETCORE-TOKEN)。IIS 中间件检查它所接收的每个请求，以确认配对令牌标头值与环境变量值相匹配。如果令牌值不匹配，则将记录请求并拒绝该请求。无法从脱离服务器的位置访问配对令牌环境变量及模块和 Kestrel 之间的流量。如果不知道配对令牌值，攻击者就无法提交绕过 IIS 中间件中的检查的请求。

具有 IIS 共享配置的 ASP.NET Core 模块ASP.NET Core Module with an IIS Shared Configuration

ASP.NET Core 模块安装程序使用 TrustedInstaller 帐户的权限运行 。由于本地系统帐户没有 IIS 共享配置所用的共享路径的修改权限，因此在尝试配置共享上的 applicationHost.config 文件中的模块设置时，安装程序将引发拒绝访问错误 。

使用 IIS 共享配置时，请执行以下步骤：

• 禁用 IIS 共享配置。
• 运行安装程序。
• 将已更新的 applicationHost.config 文件导出到共享。
• 重新启用 IIS 共享配置。

模块版本和托管捆绑安装程序日志Module version and Hosting Bundle installer logs

若要确定已安装 ASP.NET Core 模块的版本，请执行以下操作：

• 在托管系统上，导航到 %windir%\System32\inetsrv 。
• 找到 aspnetcore.dll 文件。
• 右键单击该文件，然后从上下文菜单中选择“属性” 。
• 选择“详细信息”选项卡 。“文件版本” 和“产品版本” 表示模块的已安装版本。
  在 C:\Users\%UserName%\AppData\Local\Temp 中找到了模块的托管捆绑安装程序日志。该文件名为 ddDotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log 。

模块、架构和配置文件位置Module, schema, and configuration file locations

模块Module

IIS (x86/amd64) ：

• %windir%\System32\inetsrv\aspnetcore.dll

• %windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64) ：

• %ProgramFiles%\IIS Express\aspnetcore.dll

• %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

架构Schema

IIS

• %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

• %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

ConfigurationConfiguration

IIS

• %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

• Visual Studio：{APPLICATION ROOT}.vs\config\applicationHost.config

• iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

可以通过在 applicationHost.config 文件中搜索 aspnetcore 找到这些文件。

其他资源Additional resources

• 使用 IIS 在 Windows 上托管 ASP.NET Core
• 将 ASP.NET Core 应用部署到 Azure 应用服务
• ASP.NET Core 模块引用源（主分支） – 使用“分支” 下拉列表选择特定版本（例如，release/3.1）。
• IIS 模块与 ASP.NET Core