本文轉自：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

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

設置環境變量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.

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

<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 解決方案。

[轉]ASP.NET 核心模塊配置參考