[转]ASP.NET 核心模块配置参考

本文转自：https://docs.microsoft.com/zh-cn/aspnet/core/host-and-deploy/aspnet-core-module?view=aspnetcore-2.1

通过Luke Latham， Rick Anderson，和Sourabh ShirhattiBy Luke Latham, Rick Anderson, and Sourabh Shirhatti

本文档将说明了如何配置 ASP.NET 核心模块用于承载 ASP.NET Core 应用。This document provides instructions on how to configure the ASP.NET Core Module for hosting ASP.NET Core apps. 有关 ASP.NET 核心模块和安装说明简介，请参阅ASP.NET 核心模块概述。For an introduction to the ASP.NET Core Module and installation instructions, see the ASP.NET Core Module overview.

Web.config 配置Configuration with web.config

使用配置 ASP.NET 核心模块aspNetCore部分system.webServer在站点的节点web.config文件。The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

以下web.config发布文件以便进行framework 相关部署和配置 ASP.NET 核心模块，以处理站点请求：The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

XML 复制

<?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为发布独立的部署:The following web.config is published for a self-contained deployment:

XML 复制

<?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 App Service、stdoutLogFile路径设置为\\?\%home%\LogFiles\stdout。When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. 路径将保存到 stdout 日志LogFiles文件夹，它是一个位置自动创建的服务。The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

请参阅子应用程序配置的与配置相关的重要说明web.config子应用程序中的文件。See Sub-application configuration for an important note pertaining to the configuration of web.config files in sub-apps.

AspNetCore 元素的特性Attributes of the aspNetCore element

特性Attribute	描述Description	默认Default
arguments	可选的字符串属性。Optional string attribute. 可执行文件中指定的自变量processPath。Arguments to the executable specified in processPath.
disableStartUpErrorPage	“真”或“假”。true or false. 如果为 true， 502.5-进程失败页被禁止显示，并且 502 状态代码页中配置web.config优先。If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.	false
forwardWindowsAuthToken	“真”或“假”。true or false. 如果为 true，该令牌将转发到侦听作为每个请求的标头 MS ASPNETCORE WINAUTHTOKEN 的 %aspnetcore_port%的子进程。If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. 它是该进程可以在每个请求此令牌上调用 CloseHandle 责任。It's the responsibility of that process to call CloseHandle on this token per request.	true
processPath	必需的字符串属性。Required string attribute. 将启动侦听 HTTP 请求的进程的可执行文件的路径。Path to the executable that launches a process listening for HTTP requests. 支持相对路径。Relative paths are supported. 如果路径以开始.，考虑使用该路径是相对站点根。If the path begins with ., the path is considered to be relative to the site root.
rapidFailsPerMinute	可选的整数属性。Optional integer attribute. 指定在指定的进程的次数processPath允许每分钟崩溃。Specifies the number of times the process specified in processPath is allowed to crash per minute. 如果超出此限制，该模块将停止启动剩余秒数的进程。If this limit is exceeded, the module stops launching the process for the remainder of the minute.	10
requestTimeout	可选的 timespan 属性。Optional timespan attribute. 指定为其 ASP.NET 核心模块等待侦听 %aspnetcore_port%的进程响应的持续时间。Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%. 中附带的版本的 ASP.NET 核心 2.0 或更早版本，ASP.NET 核心模块的版本requestTimeout必须指定整分钟数，否则它将默认为 2 分钟。In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.0 or earlier, the requestTimeout must be specified in whole minutes only, otherwise it defaults to 2 minutes.	00:02:00
shutdownTimeLimit	可选的整数属性。Optional integer attribute. 正常关闭的可执行文件的模块等待的秒数的持续时间时app_offline.htm检测到文件。Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.	10
startupTimeLimit	可选的整数属性。Optional integer attribute. 持续时间以启动侦听端口的进程的可执行文件的模块等待的秒数。Duration in seconds that the module waits for the executable to start a process listening on the port. 如果超过此时间限制，该模块可终止进程。If this time limit is exceeded, the module kills the process. 模块将尝试重新启动该过程，在它接收新请求，并将继续尝试重新启动此过程在后续的传入请求，除非应用程序启动失败时rapidFailsPerMinute次数在最后一个滚动分钟。The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.	120
stdoutLogEnabled	可选布尔属性。Optional Boolean attribute. 如果为 true， stdout和stderr中指定的进程的processPath重定向到中指定的文件stdoutLogFile。If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.	false
stdoutLogFile	可选的字符串属性。Optional string attribute. 为其指定的相对或绝对文件路径stdout和stderr中指定的进程从processPath记录。Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. 相对路径是相对于站点的根目录。Relative paths are relative to the root of the site. 从任何路径.是相对于站点根和所有其他路径被视为绝对路径。Any path starting with . are relative to the site root and all other paths are treated as absolute paths. 路径中提供的任何文件夹必须存在于要创建的日志文件的模块的顺序。Any folders provided in the path must exist in order for the module to create the log file. 使用下划线分隔符、 时间戳、 进程 ID 和文件扩展名 (.log) 添加到最后一个段stdoutLogFile路径。Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. 如果.\logs\stdout提供一个值，作为示例 stdout 日志另存为stdout_20180205194132_1934.log中日志文件夹保存在 19:41:32 并且进程 ID 为 1934年 2/5/2018年。If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.	aspnetcore-stdout

特性Attribute	描述Description	默认Default
arguments	可选的字符串属性。Optional string attribute. 可执行文件中指定的自变量processPath。Arguments to the executable specified in processPath.
disableStartUpErrorPage	“真”或“假”。true or false. 如果为 true， 502.5-进程失败页被禁止显示，并且 502 状态代码页中配置web.config优先。If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.	false
forwardWindowsAuthToken	“真”或“假”。true or false. 如果为 true，该令牌将转发到侦听作为每个请求的标头 MS ASPNETCORE WINAUTHTOKEN 的 %aspnetcore_port%的子进程。If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. 它是该进程可以在每个请求此令牌上调用 CloseHandle 责任。It's the responsibility of that process to call CloseHandle on this token per request.	true
processPath	必需的字符串属性。Required string attribute. 将启动侦听 HTTP 请求的进程的可执行文件的路径。Path to the executable that launches a process listening for HTTP requests. 支持相对路径。Relative paths are supported. 如果路径以开始.，考虑使用该路径是相对站点根。If the path begins with ., the path is considered to be relative to the site root.
rapidFailsPerMinute	可选的整数属性。Optional integer attribute. 指定在指定的进程的次数processPath允许每分钟崩溃。Specifies the number of times the process specified in processPath is allowed to crash per minute. 如果超出此限制，该模块将停止启动剩余秒数的进程。If this limit is exceeded, the module stops launching the process for the remainder of the minute.	10
requestTimeout	可选的 timespan 属性。Optional timespan attribute. 指定为其 ASP.NET 核心模块等待侦听 %aspnetcore_port%的进程响应的持续时间。Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%. 中附带的版本的 ASP.NET 核心 2.1 或更高版本，ASP.NET 核心模块的版本requestTimeout中小时、 分钟和秒为单位指定。In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.	00:02:00
shutdownTimeLimit	可选的整数属性。Optional integer attribute. 正常关闭的可执行文件的模块等待的秒数的持续时间时app_offline.htm检测到文件。Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.	10
startupTimeLimit	可选的整数属性。Optional integer attribute. 持续时间以启动侦听端口的进程的可执行文件的模块等待的秒数。Duration in seconds that the module waits for the executable to start a process listening on the port. 如果超过此时间限制，该模块可终止进程。If this time limit is exceeded, the module kills the process. 模块将尝试重新启动该过程，在它接收新请求，并将继续尝试重新启动此过程在后续的传入请求，除非应用程序启动失败时rapidFailsPerMinute次数在最后一个滚动分钟。The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.	120
stdoutLogEnabled	可选布尔属性。Optional Boolean attribute. 如果为 true， stdout和stderr中指定的进程的processPath重定向到中指定的文件stdoutLogFile。If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.	false
stdoutLogFile	可选的字符串属性。Optional string attribute. 为其指定的相对或绝对文件路径stdout和stderr中指定的进程从processPath记录。Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. 相对路径是相对于站点的根目录。Relative paths are relative to the root of the site. 从任何路径.是相对于站点根和所有其他路径被视为绝对路径。Any path starting with . are relative to the site root and all other paths are treated as absolute paths. 路径中提供的任何文件夹必须存在于要创建的日志文件的模块的顺序。Any folders provided in the path must exist in order for the module to create the log file. 使用下划线分隔符、 时间戳、 进程 ID 和文件扩展名 (.log) 添加到最后一个段stdoutLogFile路径。Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. 如果.\logs\stdout提供一个值，作为示例 stdout 日志另存为stdout_20180205194132_1934.log中日志文件夹保存在 19:41:32 并且进程 ID 为 1934年 2/5/2018年。If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.	aspnetcore-stdout

设置环境变量Setting environment variables

环境变量可以为中的过程指定processPath属性。Environment variables can be specified for the process in the processPath attribute. 指定的环境变量environmentVariable的子元素environmentVariables集合元素。Specify an environment variable with the environmentVariable child element of an environmentVariables collection element. 在本部分中设置的环境变量优先于系统环境变量。Environment variables set in this section take precedence over system environment variables.

下面的示例设置两个环境变量。The following example sets two environment variables. ASPNETCORE_ENVIRONMENT 配置应用程序的环境以Development。ASPNETCORE_ENVIRONMENT configures the app's environment to Development. 开发人员可能将此值暂时设置web.config文件以便强制开发人员异常页以便在调试应用程序异常时加载。A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR 是一种用户定义的环境变量中，开发人员曾读取启动窗体中用于加载应用程序的配置文件的路径上的值的代码。CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

XML 复制

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

警告

只能设置ASPNETCORE_ENVIRONMENTenvirnonment 变量Development过渡和测试不到不受信任的网络，例如 Internet 可访问的服务器上。Only set the ASPNETCORE_ENVIRONMENT envirnonment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

如果具有名称的文件app_offline.htm中检测到一个应用程序的根目录下 ASP.NET 核心模块尝试正常关闭应用程序，并停止处理传入请求。If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 如果应用程序中定义的秒数后仍在运行shutdownTimeLimit，ASP.NET 核心模块将终止正在运行的进程。If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

虽然app_offline.htm存在文件，则 ASP.NET 核心模块响应请求通过发回的内容app_offline.htm文件。While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. 当app_offline.htm删除文件，则下一个请求启动应用程序。When the app_offline.htm file is removed, the next request starts the app.

启动错误页Start-up error page

如果 ASP.NET 核心模块无法启动后端进程或后端进程启动但不能在配置的端口上侦听502.5 进程失败状态代码页将出现。If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 Process Failure status code page appears. 若要禁止显示此页并还原为默认 IIS 502 状态代码页，请使用disableStartUpErrorPage属性。To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. 有关配置自定义错误消息的详细信息，请参阅HTTP 错误<httpErrors>。For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

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

ASP.NET 核心模块将重定向 stdout 和 stderr 的日志磁盘如果stdoutLogEnabled和stdoutLogFile属性aspNetCore元素设置。The ASP.NET Core Module redirects stdout and stderr logs to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. 中的任何文件夹stdoutLogFile路径必须存在于要创建的日志文件的模块的顺序。Any folders in the stdoutLogFile path must exist in order for the module to create the log file. 应用程序池必须具有写入访问权限日志将写入其中的位置 (使用IIS AppPool\<app_pool_name>提供写入权限)。The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

日志不轮换，除非进程回收/重新启动时发生。Logs aren't rotated, unless process recycling/restart occurs. 它负责的托管商来限制日志使用的磁盘空间。It's the responsibility of the hoster to limit the disk space the logs consume.

应用程序启动问题的故障排除，仅建议使用 stdout 日志。Using the stdout log is only recommended for troubleshooting app startup issues. 不要使用用于常规应用程序日志记录的 stdout 日志。Don't use the stdout log for general app logging purposes. 对于例程日志记录在 ASP.NET Core 应用程序，使用限制日志文件大小和旋转日志的日志记录库。For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. 有关详细信息，请参阅第三方日志记录提供程序。For more information, see third-party logging providers.

创建日志文件时，将自动添加时间戳和文件扩展名。A timestamp and file extension are added automatically when the log file is created. 日志文件名称由后面追加时间戳、 进程 ID 和文件扩展名 (.log) 到的最后一段stdoutLogFile路径 (通常stdout) 由下划线分隔。The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 如果stdoutLogFile路径以结束stdout，pid 为 1934 在 19:42:32 2/5/2018年上创建的应用程序日志中的文件名称stdout_20180205194132_1934.log。If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

下面的示例aspNetCore元素会配置的 Azure App Service 中承载的应用的标准输出日志记录。The following sample aspNetCore element configures stdout logging for an app hosted in Azure App Service. 本地路径或网络共享路径是可接受的本地日志记录。A local path or network share path is acceptable for local logging. 确认应用程序池用户标识有权写入提供的路径。Confirm that the AppPool user identity has permission to write to the path provided.

XML 复制

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>

请参阅web.config 配置有关的示例aspNetCore中的元素web.config文件。See Configuration with web.config for an example of the aspNetCore element in the web.config file.

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

在 ASP.NET 核心模块和 Kestrel 之间创建的代理服务器使用 HTTP 协议。The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. 使用 HTTP 是一种性能优化，其中模块和 Kestrel 之间的通信发生在上环回地址从网络接口中移出。Using HTTP is a performance optimization, where the traffic between the module and Kestrel takes place on a loopback address off of the network interface. 没有任何风险的窃听模块和 Kestrel 从服务器中移出的位置之间的通信。There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

配对令牌用于保证 Kestrel 收到的请求已由 IIS 代理且不来自某些其他源。A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. 创建并设置环境变量到配对的令牌 (ASPNETCORE_TOKEN) 由模块。The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. 此外，配对令牌还设置到每个代理请求的标头 (MSAspNetCoreToken)。The pairing token is also set into a header (MSAspNetCoreToken) on every proxied request. IIS 中间件检查它所接收的每个请求，以确认配对令牌标头值与环境变量值相匹配。IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. 如果令牌值不匹配，则将记录请求并拒绝该请求。If the token values are mismatched, the request is logged and rejected. 配对的令牌的环境变量和模块和 Kestrel 之间的通信无法访问从服务器中移出的位置。The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. 如果不知道配对令牌值，攻击者就无法提交绕过 IIS 中间件中的检查的请求。Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

ASP.NET 核心模块与 IIS 共享配置ASP.NET Core Module with an IIS Shared Configuration

ASP.NET 核心模块安装程序使用的特权运行系统帐户。The ASP.NET Core Module installer runs with the privileges of the SYSTEM account. 安装程序的本地系统帐户不具有修改权限使用 IIS 共享配置的共享路径，因为达到拒绝访问错误时尝试进行配置中的模块设置applicationHost.config共享上。Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer hits an access denied error when attempting to configure the module settings in applicationHost.config on the share. 在将非 IIS 共享配置，请按照下列步骤：When using an IIS Shared Configuration, follow these steps:

1. 禁用 IIS 共享的配置。Disable the IIS Shared Configuration.
2. 运行安装程序。Run the installer.
3. 导出已更新applicationHost.config到共享的文件。Export the updated applicationHost.config file to the share.
4. 重新启用 IIS 共享的配置。Re-enable the IIS Shared Configuration.

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

若要确定已安装 ASP.NET 核心模块的版本：To determine the version of the installed ASP.NET Core Module:

1. 在托管系统上，导航到 %windir%\System32\inetsrv。On the hosting system, navigate to %windir%\System32\inetsrv.
2. 找到aspnetcore.dll文件。Locate the aspnetcore.dll file.
3. 右键单击该文件并选择属性从上下文菜单。Right-click the file and select Properties from the contextual menu.
4. 选择详细信息选项卡。文件版本和产品版本表示已安装的模块版本。Select the Details tab. The File version and Product version represent the installed version of the module.

在找到承载捆绑安装程序日志模块c:\用户\%username%\AppData\本地\Temp。将文件命名为dd_DotNetCoreWinSvrHosting__<时间戳 > _000_AspNetCoreModule_x64.log。The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

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

模块Module

IIS (x86/amd64):IIS (x86/amd64):

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

• %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

架构Schema

IISIIS

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

IIS ExpressIIS Express

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

配置Configuration

IISIIS

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

IIS ExpressIIS Express

• .vs\config\applicationHost.config.vs\config\applicationHost.config

可以通过搜索找到文件aspnetcore.dll中applicationHost.config文件。The files can be found by searching for aspnetcore.dll in the applicationHost.config file. IIS express， applicationHost.config文件不存在默认情况下。For IIS Express, the applicationHost.config file won't exist by default. 在创建文件 <application_root >\.vs\配置时从任何 web 应用程序项目开始在 Visual Studio 解决方案。