適用於 IIS 的 ASP.NET Core 模組 (ANCM)

注意

這不是這篇文章的最新版本。關於目前版本，請參閱本文的 .NET 10 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。關於目前版本，請參閱本文的 .NET 10 版本。

ASP.NET Core 模組 (ANCM) 是可外掛至 IIS 管線的原生 IIS 模組，讓 ASP.NET Core 應用程式能夠使用 IIS。透過下列任一方式，使用 IIS 執行 ASP.NET Core 應用程式：

在 IIS 工作者處理序 (w3wp.exe) 中裝載 ASP.NET Core 應用程式 (稱為同處理序裝載模型)。
將網頁要求轉送到執行 Kestrel 伺服器的後端 ASP.NET Core 應用程式（稱為外處理程序裝載模型）。

在每一種託管模型之間都有權衡取捨。預設會使用同處理序裝載模型，因為效能更佳且診斷更佳。

如需詳細資訊與組態指南，請參閱下列主題：

ASP.NET Core 中的網頁伺服器實作

安裝 ASP.NET Core 模組 (ANCM)

ASP.NET Core 模組 (ANCM) 會隨 .NET Core 裝載套件組合中的 .NET Core 執行階段一起安裝。 ASP.NET Core 模組與 .NET 的支援中版本向前和回溯相容。

公告存放庫上會報告重大變更和安全性公告。選取 [標籤] 篩選，以將公告限制為特定版本。

使用下列連結下載安裝程式：

目前的 .NET Core 裝載套件組合安裝程式 (直接下載)

如需詳細資訊 (包括安裝舊版模組)，請參閱裝載套件組合。

如需將 ASP.NET Core 應用程式發佈至 IIS 伺服器的教學課程體驗，請參閱將 ASP.NET Core 應用程式發佈到 IIS。

ASP.NET Core 模組 (ANCM) 是一種原生 IIS 模組，可外掛至 IIS 管線以便：

在 IIS 工作進程 (w3wp.exe) 中托管 ASP.NET Core 應用程式，稱為同進程托管模型。
將 Web 要求轉送到執行 Kestrel 伺服器的後端 ASP.NET Core 應用程式 (稱為跨處理序裝載模型)。

支援的 Windows 版本：

Windows 7 或更新版本
Windows Server 2012 R2 或更新版本

同處理序裝載時，模組會使用 IIS 的同處理序伺服器實作，其名稱為 IIS HTTP 伺服器 (IISHttpServer)。

跨處理序裝載時，該模組只適用於 Kestrel。該模組無法與 HTTP.sys 搭配運作。

託管模型

內嵌管理模型

ASP.NET Core 應用程式預設為同處理序裝載模型。

在進程中裝載時具備下列特性：

使用 IIS HTTP 伺服器 (IISHttpServer)，而不是 Kestrel 伺服器。正在進行中的程序中，CreateDefaultBuilder 會呼叫 UseIIS 來：
- 註冊 IISHttpServer。
- 設定伺服器在 ASP.NET Core 模組後方執行時應該接聽的連接埠和基底路徑。
- 設定主機以擷取啟動錯誤。
requestTimeout 屬性不適用於進程內裝載。
不支援在應用程式之間共用應用程式集區。每個應用程式使用一個應用程式集區。
使用 Web Deploy 或以手動方式將 app_offline.htm 檔案放入部署時，若有未關閉的連線，應用程式可能無法立即關閉。例如，WebSocket 連線可能會延遲應用程式關閉。
應用程式的架構 (位元) 和已安裝的執行階段 (x64 或 x86) 必須符合應用程式集區的架構。
偵測到用戶端中斷連線。當用戶端中斷連線時，HttpContext.RequestAborted 取消權杖就會被取消。
在 ASP.NET Core 2.2.1 或更早版本中，GetCurrentDirectory 會傳回 IIS 所啟動之處理序的背景工作目錄，而非應用程式的目錄 (例如 C:\Windows\System32\inetsrv 為 w3wp.exe)。

如需設定應用程式目前所在目錄的範例程式碼，請參閱 CurrentDirectoryHelpers class。呼叫 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();
}
```
- 不支援網頁套件 (單一檔案) 部署。

跨處理序裝載模型

若要設定應用程式進行跨處理序裝載，請在專案檔 (<AspNetCoreHostingModel>) 中將 OutOfProcess 屬性的值設定為 .csproj：

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

同處理序裝載會設定為 InProcess，此為預設值。

<AspNetCoreHostingModel> 的值不區分大小寫，因此 inprocess 和 outofprocess 都是有效的值。

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

若為跨處理序作業，CreateDefaultBuilder 會呼叫 UseIISIntegration 以便：

設定伺服器在執行於 ASP.NET Core 模組後方時應當接聽的連接埠和基底路徑。
設定主機以擷取啟動錯誤。

託管模型變更

如果變更了 web.config 檔案中的 hostingModel 設定（如在使用 web.config 進行設定一節中所述），則模組會回收 IIS 的工作程序。

針對 IIS Express，模組不會回收工作者處理序，但會改為觸發目前 IIS Express 處理序的正常關閉。應用程式的下一個請求會啟動新的 IIS Express 處理序。

程序名稱。

Process.GetCurrentProcess().ProcessName 報告 w3wp/iisexpress (預處理中) 或 dotnet (外部處理)。

許多如 Windows 驗證等原生模組仍在使用中。若要深入了解搭配 ASP.NET Core 模組的使用中 IIS 模組，請參閱與 ASP.NET Core 搭配運作的 IIS 模組。

ASP.NET Core 模組也可以：

設定工作者處理序的環境變數。
將 stdout 輸出記錄到檔案儲存區，以針對啟動問題進行疑難排解。
轉送 Windows 驗證憑證。

如何安裝和使用 ASP.NET Core 模組 (ANCM)

如需如何安裝 ASP.NET Core 模組的指示，請參閱安裝 .NET Core 裝載套件組合。 ASP.NET Core 模組與 .NET 的支援中版本向前和回溯相容。

公告存放庫上會報告重大變更和安全性公告。選取 [標籤] 篩選，以將公告限制為特定版本。

使用 web.config 進行設定

ASP.NET Core 模組的設定，是透過網站 web.config 檔案中 system.webServer 節點內的 aspNetCore 區段完成的。

以下 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，以表示位於應用程式子目錄中的應用程式不會繼承在<location>元素中指定的設定。

將應用程式部署至 Azure App 服務時，stdoutLogFile 路徑會設定為 \\?\%home%\LogFiles\stdout。此路徑會將 stdout 記錄檔儲存至 LogFiles 資料夾，這是服務自動建立的位置。

如需 IIS 子應用程式組態的相關資訊，請參閱使用 IIS 在 Windows 上裝載 ASP.NET Core。

aspNetCore 元素的屬性

屬性	描述	預設
`arguments`	選擇性字串屬性。 processPath 中所指定可執行檔的引數。
`disableStartUpErrorPage`	選擇性的 Boolean 屬性。如果為 true，就會抑制 [502.5 - 處理序失敗] 頁面，而優先顯示 web.config 中設定的 502 狀態碼頁面。	`false`
`forwardWindowsAuthToken`	選擇性的 Boolean 屬性。如果為 true，則會根據每次請求將權杖以標頭欄位 `%ASPNETCORE_PORT%` 的形式轉送至在 `'MS-ASPNETCORE-WINAUTHTOKEN'` 進行接聽的子處理序。該處理序有責任根據請求呼叫此權杖上的 CloseHandle 函式。	`true`
`hostingModel`	選擇性字串屬性。指定裝載模型為內部處理 (`InProcess`/`inprocess`) 或外部處理 (`OutOfProcess`/`outofprocess`)。	`InProcess` `inprocess`
`processesPerApplication`	選擇性的整數屬性。指定 processPath 設定中所指定處理序執行個體每個應用程式可上調的數目。 †針對同處理序裝載，此值會限制為 `1`。不建議使用 `processesPerApplication` 設定。此屬性將在未來版本中移除。	預設：`1` 最小值：`1` 最大值:`100`†
`processPath`	必要的字串屬性。啟動接聽 HTTP 請求的處理程序之可執行檔路徑。支援相對路徑。如果路徑的開頭為 `.`，該路徑即被視為網站根目錄的相對路徑。
`rapidFailsPerMinute`	選擇性的整數屬性。指定允許 processPath 中所指定處理序每分鐘當機的次數。如果超出此限制，模組就會在該分鐘的剩餘時間內停止啟動處理序。不支援進程內主機。	預設：`10` 最小值：`0` 最大值：`100`
`requestTimeout`	選擇性的時間範圍屬性。指定 ASP.NET Core 模組等待正在監聽 %ASPNETCORE_PORT% 的進程回應的時間。在 ASP.NET Core 2.1 或更新版本隨附的 ASP.NET Core 模組版本中，是以小時、分鐘及秒為單位來指定 `requestTimeout`。不適用於進程內宿主。針對執行中裝載，模組等待應用程式處理要求。字串中的分鐘和秒數的有效值介於 0 到 59。在分鐘或秒數的值中使用 60 將會導致「500 - 內部伺服器錯誤」。	預設：`00:02:00` 最小值：`00:00:00` 最大值：`360:00:00`
`shutdownTimeLimit`	選擇性的整數屬性。偵測到 `app_offline.htm` 檔案時，模組等候可執行檔正常關閉的持續時間 (以秒為單位)。	預設：`10` 最小值：`0` 最大值：`600`
`startupTimeLimit`	選擇性的整數屬性。模組等待可執行檔啟動一個在指定連接埠上進行接聽的處理序的時間 (以秒為單位)。如果超出此時間限制，模組就會終止處理序。進行同處理序裝載時：處理序不會重新啟動，而且不會使用 rapidFailsPerMinute 設定。進行跨處理序裝載時：模組會在收到新要求時，嘗試重新啟動處理序，然後在後續的傳入要求上繼續嘗試重新啟動處理序，除非應用程式在上一次循環的分鐘內無法啟動的次數達到 rapidFailsPerMinute 所指定的次數。 0 (零) 值不被視為無限超時。	預設：`120` 最小值：`0` 最大值：`3600`
`stdoutLogEnabled`	選擇性的 Boolean 屬性。如果為 true，就會將 processPath 中所指定處理序的 stdout 和 stderr 重新導向到 stdoutLogFile 中所指定的檔案。	`false`
`stdoutLogFile`	選擇性字串屬性。指定 stdout 和 stderr 從 processPath 指定的處理程序的相對或絕對檔案路徑以供記錄。相對路徑是相對於網站的根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。模組在建立日誌檔案時，會建立路徑中提供的任何資料夾。使用底線分隔符號，時間戳記、處理序識別碼及副檔名 (`.log`) 會新增至 stdoutLogFile 路徑的最後一個區段。如果提供 `.\logs\stdout` 作為值，在 2018 年 2 月 5 日的 19:41:32 以處理序識別碼 1934 進行儲存時，範例 stdout 記錄檔就會以 `stdout_20180205194132_1934.log` 的形式儲存在 `logs` 資料夾中。	`aspnetcore-stdout`

設定環境變數

您可以在 processPath 屬性中為處理序指定環境變數。請使用 <environmentVariable> 集合元素的 <environmentVariables> 子元素來指定環境變數。本節中所設定環境變數的優先順序會高於系統環境變數。

下列範例會在 web.config 中設定兩個環境變數。 ASPNETCORE_ENVIRONMENT 會將應用程式的環境設定為 Development。開發人員可能會暫時在檔案中設定此值，以便在偵錯應用程式異常時強制載入<開發人員例外頁面>。 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 中直接設定環境的替代方案，可以在發佈設定檔 (.pubxml) 或專案檔中納入屬性 <EnvironmentName>。此方法會在專案發行時於 web.config 中設定環境：

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

警告

請只有在未受信任網路 (例如網際網路) 無法存取的暫存和測試伺服器上，才將 ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。

`app_offline.htm`

如果在應用程式根目錄中偵測到名稱為 app_offline.htm 的檔案，ASP.NET Core 模組會嘗試正常關閉應用程式並停止處理傳入的要求。如果在經過 shutdownTimeLimit 中所定義的秒數之後，應用程式仍然在執行，ASP.NET Core Module 就會終止執行中的處理序。

當 app_offline.htm 檔案存在時，ASP.NET Core 模組會藉由傳回 app_offline.htm 檔案的內容來回應要求。已移除 app_offline.htm 檔案時，下一個要求則會啟動應用程式。

使用進程外部裝載模型時，如果有開啟的連線，應用程式可能無法立即關閉。例如，WebSocket 連線可能會延遲應用程式關閉。

啟動錯誤頁面

當同處理序和跨處理序裝載無法啟動應用程式時，它們都會產生自訂錯誤頁面。

若 ASP.NET Core 模組找不到同處理序或跨處理序要求處理常式時，就會顯示 [500.0 - 同處理序/跨處理序處理常式載入失敗] 狀態碼頁面。

在內部程序代管時，如果 ASP.NET Core 模組無法啟動應用程式，會顯示一個 500.30 - 啟動失敗 狀態碼頁面。

對於程序外主機，若 ASP.NET Core模組未能啟動後端程序，或後端程序啟動但未監聽已設定的埠口，則會出現一個502.5 - 程序故障狀態代碼頁。

若要避免此頁面產生並還原至預設的 IIS 5xx 狀態碼頁面，請使用 disableStartUpErrorPage 屬性。如需有關設定自訂錯誤訊息的詳細資訊，請參閱 HTTP 錯誤<httpErrors>。

日誌建立和重新導向

如果已設定 stdoutLogEnabled 元素的 stdoutLogFile 和 aspNetCore 屬性，ASP.NET Core 模組就會將 stdout 和 stderr 主控台輸出重新導向到磁碟。模組在建立日誌檔案時會建立路徑中 stdoutLogFile 的任何資料夾。應用程式集區必須具有記錄檔寫入位置的寫入權限 (請使用 IIS AppPool\<app_pool_name> 來提供寫入權限)。

除非發生處理序回收/重新啟動，否則不會輪替記錄檔。主機服務提供者必須負責限制記錄檔所使用的磁碟空間。

只有在裝載於 IIS 或使用 Visual Studio 中針對 IIS 的開發時間支援時，而不是在本機偵錯並使用 IIS Express 執行應用程式時，才建議使用 stdout 記錄來針對應用程式啟動問題進行疑難排解。

請勿將 stdout 記錄檔用來進行一般應用程式記錄。針對 ASP.NET Core 應用程式中的例行性記錄，請使用會限制記錄檔大小並輪替記錄檔的記錄程式庫。如需詳細資訊，請參閱協力廠商記錄提供者。

建立記錄檔時，系統會自動新增時間戳記和副檔名。記錄檔名稱是透過將時間戳記、處理序識別碼及副檔名 (.log) 附加至以底線分隔的 stdoutLogFile 路徑的最後一個區段 (通常是 stdout) 來組成。如果 stdoutLogFile 路徑以 stdout 結尾，則一個在 2018 年 2 月 5 日 19:42:32 建立的，PID 為 1934 的應用程式日誌，其檔案名稱為 stdout_20180205194132_1934.log。

若 stdoutLogEnabled 為 false，會擷取應用程式啟動時發生的錯誤，並將其記錄至最大為 30 KB 的事件日誌中。啟動後，所有其他的日誌都會被捨棄。

下列範例 aspNetCore 元素會在相對路徑 .\log\ 設定 stdout 記錄。確認 AppPool 使用者身份有權寫入所提供的路徑。

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

發佈適用於 Azure App 服務部署的應用程式時，Web SDK 會將 stdoutLogFile 值設定為 \\?\%home%\LogFiles\stdout。環境變數 %home 是針對 Azure App 服務所裝載的應用程式預先定義的。

若要建立記錄篩選規則，請參閱 ASP.NET Core 記錄文件中的在程式碼中套用記錄篩選規則一節。

如需路徑格式的詳細資訊，請參閱 Windows 系統上的檔案路徑格式。

增強型診斷日誌

ASP.NET Core 模組是可設定的，以提供增強型診斷記錄。將 <handlerSettings> 元素新增至 <aspNetCore> 中的 web.config 元素。將 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} 來提供寫入權限，其中預留位置 {APP POOL NAME} 是應用程式集區名稱)。

偵錯層級 (debugLevel) 值可以同時包含層級和位置。

層級 (按照詳細程度從最低到最高排序)：

錯誤
警告
資訊
TRACE

位置 (允許多個位置)：

主控台
EVENTLOG
檔案

也可以透過環境變數提供處理常式設定：

ASPNETCORE_MODULE_DEBUG_FILE：偵錯記錄檔的路徑。 (預設值：aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG：偵錯層級設定。

警告

在部署中保持啟用偵錯記錄的時間，不要超過針對問題進行排解疑難所需的時間。記錄的大小不受限制。保持啟用偵錯記錄可能會耗盡可用磁碟空間，並讓伺服器或應用程式服務當機。

請參閱 web.config 中的配置，了解 web.config 檔案中 aspNetCore 元素的範例。

修改堆疊大小

僅適用於使用同程式內裝載模型時。

在 stackSize 中使用 web.config 設定以位元組為單位來設定受控堆疊的大小。預設大小為 1,048,576 個位元組 (1 MB)。

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

Proxy 組態使用 HTTP 通訊協定和配對令牌

僅適用於進程外託管。

在 ASP.NET Core 模組與 Kestrel 之間建立的 Proxy 會使用 HTTP 通訊協定。沒有從伺服器外的位置竊聽模組與 Kestrel 之間流量的風險。

使用配對令牌來保證由 IIS 代理接收的請求是來自 Kestrel，而非其他來源。模組會建立配對權杖，並將其設定成環境變數 (ASPNETCORE_TOKEN)。配對令牌也會設定成每個代理要求的標頭 (MS-ASPNETCORE-TOKEN)。 IIS 中介軟體會檢查其收到的每個要求，以確認配對權杖的標頭值符合環境變數值。如果權杖值不符，系統將記錄此次請求並予以拒絕。使用者無法從伺服器外的位置存取配對權杖環境變數，以及模組與 Kestrel 之間的流量。在不知道配對權杖值的情況下，網路攻擊者無法送出要求來略過 IIS 中介軟體的檢查。

具有 IIS 共用設定的 ASP.NET Core 模組

ASP.NET Core 模組安裝程式會以 TrustedInstaller 帳戶的權限執行。由於本機系統帳戶並未具備 IIS 共用設定所使用的共用路徑修改權限，因此，安裝程式在嘗試於共用上的 applicationHost.config 檔案中進行模組設定時，會擲回拒絕存取的錯誤。

在與 IIS 安裝相同的電腦上使用 IIS 共用設定時，請執行 ASP.NET Core 裝載套件組合安裝程式並將 OPT_NO_SHARED_CONFIG_CHECK 參數設為 1：

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

若共用設定的路徑位於與 IIS 安裝不同的電腦上，請遵循下列步驟：

停用「IIS 共用設定」。
執行安裝程式。
將已更新的 applicationHost.config 檔案匯出至共用。
重新啟用「IIS 共用設定」。

模組版本和裝載套件組合安裝程式記錄檔

判斷已安裝的 ASP.NET Core 模組版本：

在主控系統上瀏覽至 %windir%\System32\inetsrv。
找出 aspnetcore.dll 檔案。
在該檔案上按一下滑鼠右鍵，然後從關聯式功能表中選取 [內容]。
選取 [詳細資料] 索引標籤。[檔案版本] 和 [產品版本] 代表已安裝的模組版本。

模組的「裝載套件組合」安裝程式記錄檔位於 C:\Users\%UserName%\AppData\Local\Temp。檔案命名為 dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log。

模組、結構描述及設定檔位置

模組

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

架構

IIS

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

IIS 快車

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

組態

IIS

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

IIS 快車

Visual Studio：{APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

在 aspnetcore 檔案中搜尋 applicationHost.config 即可找到檔案。

ASP.NET Core 模組 (ANCM) 是一種原生 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 搭配運作。

託管模型

同處理序託管模型

若要設定同處理序裝載的應用程式，請將 <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 Deploy 或以手動方式將 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();
}
```

跨處理序裝載模型

若要設定跨處理序裝載的應用程式，請在專案檔中使用下列任一方法：

請勿指定 <AspNetCoreHostingModel> 屬性。如果檔案中沒有 <AspNetCoreHostingModel> 屬性，預設值為 OutOfProcess。
將 <AspNetCoreHostingModel> 屬性的值設定為 OutOfProcess（進程內裝載使用 InProcess 設定）：

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

此值不區分大小寫，因此 inprocess 和 outofprocess 都是有效的值。

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

針對處理序外，CreateDefaultBuilder 呼叫 UseIISIntegration 以執行以下操作：

設定伺服器在執行於 ASP.NET Core 模組後方時應當接聽的連接埠和基底路徑。
設定主機以擷取啟動錯誤。

託管模型變更

如果 hostingModel 設定在 web.config 檔案中發生變更（如在web.config 中的設定一節中所說明），模組會回收 IIS 的工作者程序。

針對 IIS Express，模組不會回收工作者處理序，而是觸發目前 IIS Express 處理序的正常關閉。應用程式的下一個要求會產生新的 IIS Express 程序。

程序名稱。

Process.GetCurrentProcess().ProcessName 會報告 w3wp/iisexpress (處理中) 或 dotnet (處理序外)。

許多如 Windows 驗證等原生模組仍在使用中。若要深入了解搭配 ASP.NET Core 模組的使用中 IIS 模組，請參閱與 ASP.NET Core 搭配運作的 IIS 模組。

ASP.NET Core 模組也可以：

設定背景工作程序的環境變數。
將 stdout 輸出記錄到檔案儲存區，以針對啟動問題進行疑難排解。
傳送 Windows 驗證訊息憑證。

如何安裝和使用 ASP.NET Core 模組 (ANCM)

如需如何安裝 ASP.NET Core 模組的指示，請參閱安裝 .NET Core 裝載套件組合。 ASP.NET Core 模組與 .NET 的支援中版本向前和回溯相容。

公告存放庫上會報告重大變更和安全性公告。選取 [標籤] 篩選，以將公告限制為特定版本。

使用 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，表示位於應用程式子目錄內的應用程式不會繼承 <location> 元素中指定的設定。

將應用程式部署至 Azure App 服務時，stdoutLogFile 路徑會設定為 \\?\%home%\LogFiles\stdout。此路徑會將 stdout 記錄檔儲存至 [LogFiles] 資料夾，這是服務自動建立的位置。

如需 IIS 子應用程式組態的相關資訊，請參閱使用 IIS 在 Windows 上裝載 ASP.NET Core。

aspNetCore 元素的屬性

屬性	描述	預設
`arguments`	選擇性字串屬性。 `processPath` 中所指定可執行檔的引數。
`disableStartUpErrorPage`	選擇性的 Boolean 屬性。如果為 true，就會抑制 [502.5 - 處理序失敗] 頁面，而優先顯示 web.config 中設定的 502 狀態碼頁面。	`false`
`forwardWindowsAuthToken`	選擇性的 Boolean 屬性。如果為 true，就會依據要求將權杖以標頭 'MS-ASPNETCORE-WINAUTHTOKEN' 形式轉送至在 %ASPNETCORE_PORT% 進行接聽的子處理序。該處理序有責任根據請求呼叫此權杖上的 CloseHandle 函式。	`true`
`hostingModel`	選擇性字串屬性。指定裝載模型為內部處理 (`InProcess`/`inprocess`) 或外部處理 (`OutOfProcess`/`outofprocess`)。	`OutOfProcess` `outofprocess`
`processesPerApplication`	選擇性的整數屬性。指定在 `processPath` 設定中所指定的處理程序實例可在每個應用程式中啟動的數量。 †針對同處理序裝載，此值會限制為 `1`。不建議使用 `processesPerApplication` 設定。此屬性將在未來版本中移除。	預設：`1` 最小值：`1` 最大值:`100`†
`processPath`	必要的字串屬性。啟動接聽 HTTP 請求的處理程序之可執行檔路徑。支援相對路徑。如果路徑的開頭為 `.`，該路徑即被視為網站根目錄的相對路徑。
`rapidFailsPerMinute`	選擇性的整數屬性。指定允許 `processPath` 中所指定處理序每分鐘當機的次數。如果超出此限制，模組就會在該分鐘的剩餘時間內停止啟動處理序。不支援進程內主機。	預設：`10` 最小值：`0` 最大值：`100`
`requestTimeout`	選擇性的時間範圍屬性。指定 ASP.NET Core 模組等待正在監聽 %ASPNETCORE_PORT% 的進程回應的時間。在 ASP.NET Core 2.1 或更新版本隨附的 ASP.NET Core 模組版本中，是以小時、分鐘及秒為單位來指定 `requestTimeout`。不適用於進程內宿主。針對執行中裝載，模組等待應用程式處理要求。字串中的分鐘和秒數的有效值介於 0 到 59。在分鐘或秒數的值中使用 60 將會導致「500 - 內部伺服器錯誤」。	預設：`00:02:00` 最小值：`00:00:00` 最大值：`360:00:00`
`shutdownTimeLimit`	選擇性的整數屬性。偵測到 `app_offline.htm` 檔案時，模組等候可執行檔正常關閉的持續時間 (以秒為單位)。	預設：`10` 最小值：`0` 最大值：`600`
`startupTimeLimit`	選擇性的整數屬性。模組等待可執行檔啟動一個在指定連接埠上進行接聽的處理序的時間 (以秒為單位)。如果超出此時間限制，模組就會終止處理序。在裝載同處理序時：處理序不會重新啟動，並且不會使用`rapidFailsPerMinute`設定。進行外部處理序裝載時：模組會在收到新要求時嘗試重新啟動處理序，並在後續的傳入要求上持續嘗試重新啟動，除非應用程式在前一分鐘內的失敗次數達到 `rapidFailsPerMinute` 指定的次數。 0 (零) 值不被視為無限超時。	預設：`120` 最小值：`0` 最大值：`3600`
`stdoutLogEnabled`	選擇性的 Boolean 屬性。如果為 true，指定於的處理序之 stdout 和 stderr 會重新導向至指定於 stdoutLogFile 的檔案。	`false`
`stdoutLogFile`	選擇性字串屬性。指定記錄 `processPath` 中所指定處理序之 `stdout` 和 `stderr` 的相對或絕對檔案路徑。相對路徑是相對於網站根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。模組在建立日誌檔案時，會建立路徑中提供的任何資料夾。使用底線分隔符號，時間戳記、處理序識別碼及副檔名 (`.log`) 會新增至 `stdoutLogFile` 路徑的最後一個區段。如果提供 `.\logs\stdout` 作為值，在 2018 年 2 月 5 日的 19:41:32 以處理序識別碼 1934 進行儲存時，範例 stdout 記錄檔就會以 `stdout_20180205194132_1934.log` 的形式儲存在 `logs` 資料夾中。	`aspnetcore-stdout`

設定環境變數

下列範例會設定兩個環境變數。 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>

警告

請只有在未受信任網路 (例如網際網路) 無法存取的暫存和測試伺服器上，才將 ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。

app_offline.htm

使用跨處理序裝載模型時，如果存在開放的連線，應用程式可能無法立即關閉。例如，Websocket 連線可能會延遲應用程式關閉。

啟動錯誤頁面

在處理序內與處理序外的托管在無法啟動應用程式時，皆會產生自訂錯誤頁面。

若 ASP.NET Core 模組找不到同處理序或跨處理序要求處理常式時，就會顯示 [500.0 - 同處理序/跨處理序處理常式載入失敗] 狀態碼頁面。

對於在處理序中的裝載，如果 ASP.NET Core 模組無法啟動應用程式，則會顯示 [500.30 - 啟動失敗] 狀態碼頁面。

對於進程外托管，若 ASP.NET Core 模組無法啟動後端處理序，或後端處理序啟動但無法在所設定的連接埠上進行接聽，就會顯示 (502.5 - 處理序失敗) 狀態碼頁面。

若要避免此頁面產生並還原至預設的 IIS 5xx 狀態碼頁面，請使用 disableStartUpErrorPage 屬性。如需有關設定自訂錯誤訊息的詳細資訊，請參閱 HTTP 錯誤 <httpErrors>。

記錄建立與重新導向

除非發生處理序回收/重新啟動，否則不會輪替記錄檔。主機服務提供者必須負責限制記錄檔所使用的磁碟空間。

建立記錄檔時，系統會自動新增時間戳記和副檔名。記錄檔名稱是通過將時間戳記、處理序識別碼及副檔名（.log）用底線分隔後，附加到stdoutLogFile 路徑的最後一個區段（通常是stdout）來組成的。如果 stdoutLogFile 路徑的結尾是 stdout，則在 2018 年 2 月 5 日 19:42:32 建立且 PID 為 1934 的應用程式記錄檔檔案名稱會是 stdout_20180205194132_1934.log。

若 stdoutLogEnabled 為 false，應用程式啟動時發生的錯誤會被擷取並發送至事件日誌，錯誤大小上限為 30KB。啟動後，所有附加的記錄檔已被捨棄。

下列範例 aspNetCore 元素會在相對路徑 .\log\ 設定 stdout 記錄。確認應用程式池使用者身份有權寫入所提供的路徑。

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

如需路徑格式的詳細資訊，請參閱 Windows 系統上的檔案路徑格式。

增強型診斷記錄

<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} 來提供寫入權限，其中預留位置 {APP POOL NAME} 是應用程式集區名稱)。

偵錯層級 (debugLevel) 值可以同時包含層級和位置。

層級 (順序從最不詳細到最詳細)：

錯誤
警告
資訊
追踪

位置 (允許多個位置)：

主控台
EVENTLOG
檔案

也可以透過環境變數提供處理常式設定：

ASPNETCORE_MODULE_DEBUG_FILE：偵錯記錄檔的路徑。 (預設值：aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG：偵錯層級設定。

警告

在部署中不要保持偵錯記錄啟用超過排解問題所需的時間。記錄的大小不受限制。保持啟用偵錯記錄可能會耗盡可用磁碟空間，並讓伺服器或應用程式服務當機。

請參閱 Configuration with web.config 以查看 web.config 檔案中的 aspNetCore 元素範例。

Proxy 配置使用 HTTP 通訊協定和配對權杖

僅適用於外部進程宿主。

在 ASP.NET Core 模組與 Kestrel 之間建立的 Proxy 會使用 HTTP 通訊協定。沒有從伺服器外的位置竊聽模組與 Kestrel 之間流量的風險。

配對權杖用來保證 Kestrel 所接收的要求已由 IIS 代理，而且不是來自其他來源。模組會建立配對權杖，並將其設定成環境變數 (ASPNETCORE_TOKEN)。配對票證也會設定成每個代理要求的標頭檔 (MS-ASPNETCORE-TOKEN)。 IIS 中介軟體會檢查其收到的每個要求，以確認配對權杖的標頭值符合環境變數值。如果令牌值不相符，將會記錄此請求並拒絕。使用者無法從伺服器外的位置存取配對權杖環境變數，以及模組與 Kestrel 之間的流量。在不知道配對碼值的情況下，網路攻擊者無法繞過 IIS 中介軟體的驗證來提交請求。

具有 IIS 共用設定的 ASP.NET Core 模組

ASP.NET Core 模組安裝程式會以 TrustedInstaller 帳戶的權限執行。由於本機系統帳戶並未具備 IIS 共用設定所使用的共用路徑修改權限，因此，安裝程式在嘗試於共用上的 applicationHost.config 檔案中進行模組設定時，會擲回拒絕存取的錯誤。

在與 IIS 安裝相同的電腦上使用 IIS 共用設定時，請執行 ASP.NET Core 裝載套件組合安裝程式並將 OPT_NO_SHARED_CONFIG_CHECK 參數設為 1：

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

若共用設定的路徑位於與 IIS 安裝不同的電腦上，請遵循下列步驟：

停用「IIS 共用設定」。
執行安裝程式。
將已更新的 applicationHost.config 檔案匯出至共用。
重新啟用「IIS 共用設定」。

模組版本與主機附件安裝程式日誌

判斷已安裝的 ASP.NET Core 模組版本：

在主機系統上瀏覽至 %windir%\System32\inetsrv。
找出 aspnetcore.dll 檔案。
在該檔案上按一下滑鼠右鍵，然後從關聯式功能表中選取 [內容]。
選取 [詳細資料] 索引標籤。[檔案版本] 和 [產品版本] 代表已安裝的模組版本。

模組的「裝載套件組合」安裝程式記錄檔位於 C:\\Users\\%UserName%\\AppData\\Local\\Temp。檔案的名稱為 dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log，其中預留位置 {TIMESTAMP} 是時間戳記。

模組、結構描述及設定檔位置

模組

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

模式

IIS

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

IIS 快車

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

組態

IIS

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

IIS 快車

Visual Studio：{APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

在 aspnetcore 檔案中搜尋 applicationHost.config 即可找到檔案。

ASP.NET Core 模組 (ANCM) 是一種原生 IIS 模組，可外掛至 IIS 管線，將 Web 要求重新轉送到後端的 ASP.NET Core 應用程式。

支援的 Windows 版本：

Windows 7 或更新版本
Windows Server 2008 R2 或更新版本

該模組只適用於 Kestrel。該模組與 HTTP.sys 不相容。

因為 ASP.NET Core 應用程式是在一個與 IIS 背景工作處理序分離的處理序中執行，所以此模組也會負責處理序管理。此模組會在第一個要求到達時啟動 ASP.NET Core 應用程式的處理序，並在應用程式損毀時將它重新啟動。此行為基本上與在 IIS 中執行同處理序，並由 Windows 處理器啟用服務 (WAS) 所管理的 ASP.NET 4.x 應用程式相同。

下圖說明 IIS、ASP.NET Core 模組和應用程式之間的關聯性：

ASP.NET Core 模組

要求會從 Web 到達核心模式的 HTTP.sys 驅動程式。驅動程式會在網站設定的通訊埠上將要求路由至 IIS，此通訊埠通常是 80 (HTTP) 或 443 (HTTPS)。此模組會在應用程式的隨機通訊埠上將要求轉送至 Kestrel，而且不會是通訊埠 80 或 443。

此模組在啟動時透過環境變數指定連接埠，而 IIS 整合中介軟體則會設定伺服器來接聽 http://localhost:{port}。將會執行額外檢查，不是源自模組的要求都會遭到拒絕。此模組不支援 HTTPS 轉送，因此即使由 IIS 透過 HTTPS 接收，要求還是會透過 HTTP 轉送。

Kestrel 收取來自模組的要求之後，要求會被推送至 ASP.NET Core 中介軟體管線。中介軟體管線會處理要求，並將其作為HttpContext執行個體傳遞至應用程式邏輯。 IIS Integration 新增的中介軟體會更新協定、遠端 IP 和路徑基底，以將要求轉送至 Kestrel。應用程式的回應會傳回 IIS，而 IIS 會將其推送回起始要求的 HTTP 用戶端。

許多如 Windows 驗證等原生模組仍在使用中。若要深入了解搭配 ASP.NET Core 模組的使用中 IIS 模組，請參閱與 ASP.NET Core 搭配運作的 IIS 模組。

ASP.NET Core 模組也可以：

設定工作程序的環境變數。
將 stdout 輸出記錄到檔案儲存區，以針對啟動問題進行疑難排解。
轉送 Windows 驗證憑證。

如何安裝和使用 ASP.NET Core 模組 (ANCM)

如需如何安裝 ASP.NET Core 模組的指示，請參閱安裝 .NET Core 裝載套件組合。

使用 web.config 進行設定

ASP.NET Core 模組在網站的 web.config 檔案中，以 system.webServer 節點的 aspNetCore 區段進行設定。

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

如需 IIS 子應用程式組態的相關資訊，請參閱使用 IIS 在 Windows 上裝載 ASP.NET Core。

aspNetCore 元素的屬性

屬性	描述	預設
`arguments`	選擇性字串屬性。 processPath 中所指定可執行檔的引數。
`disableStartUpErrorPage`	選擇性的 Boolean 屬性。如果為 true，就會抑制 [502.5 - 處理序失敗] 頁面，而優先顯示 web.config 中設定的 502 狀態碼頁面。	`false`
`forwardWindowsAuthToken`	選擇性的 Boolean 屬性。如果為 true，就會依據要求將權杖以標頭 'MS-ASPNETCORE-WINAUTHTOKEN' 形式轉送至在 %ASPNETCORE_PORT% 進行接聽的子處理序。該處理序有責任根據請求呼叫此權杖上的 CloseHandle 函式。	`true`
`processesPerApplication`	選擇性的整數屬性。指定 processPath 設定中所指定處理序執行個體每個應用程式可上調的數目。不建議使用 `processesPerApplication` 設定。此屬性將在未來版本中移除。	預設：`1` 最小值：`1` 最大值：`100`
`processPath`	必要的字串屬性。啟動接聽 HTTP 請求的處理程序之可執行檔路徑。支援相對路徑。如果路徑的開頭為 `.`，該路徑即被視為網站根目錄的相對路徑。
`rapidFailsPerMinute`	選擇性的整數屬性。指定允許 processPath 中所指定處理序每分鐘當機的次數。如果超出此限制，模組就會在該分鐘的剩餘時間內停止啟動處理序。	預設：`10` 最小值：`0` 最大值：`100`
`requestTimeout`	選擇性的時間範圍屬性。指定 ASP.NET Core 模組等待正在監聽 %ASPNETCORE_PORT% 的進程回應的時間。在 ASP.NET Core 2.1 或更新版本隨附的 ASP.NET Core 模組版本中，是以小時、分鐘及秒為單位來指定 `requestTimeout`。	預設：`00:02:00` 最小值：`00:00:00` 最大值：`360:00:00`
`shutdownTimeLimit`	選擇性的整數屬性。偵測到 `app_offline.htm` 檔案時，模組等候可執行檔正常關閉的持續時間 (以秒為單位)。	預設：`10` 最小值：`0` 最大值：`600`
`startupTimeLimit`	選擇性的整數屬性。模組等待可執行檔啟動一個在指定連接埠上進行接聽的處理序的時間 (以秒為單位)。如果超出此時間限制，模組就會終止處理序。模組會在收到新請求時嘗試重新啟動程序，並在後續的連入請求上繼續嘗試重啟，除非應用程式在過去一分鐘內無法啟動的次數達到參數 rapidFailsPerMinute 所規定的次數。 0 (零) 值不被視為無限超時。	預設：`120` 最小值：`0` 最大值：`3600`
`stdoutLogEnabled`	選擇性的 Boolean 屬性。如果為 true，就會將 processPath 中所指定處理序的 stdout 和 stderr 重新導向到 stdoutLogFile 中所指定的檔案。	`false`
`stdoutLogFile`	選擇性字串屬性。指定 stdout 和 stderr 從 processPath 指定的處理程序的相對或絕對檔案路徑以供記錄。相對路徑是相對於網站的根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。路徑中提供的所有資料夾都必須存在，模組才能建立記錄檔。使用底線分隔符號，時間戳記、處理序識別碼及副檔名 (.log) 會新增至 stdoutLogFile 路徑的最後一個區段。如果提供 `.\logs\stdout` 作為值，在 2018 年 2 月 5 日的 19:41:32 以處理序識別碼 1934 進行儲存時，範例 stdout 記錄檔就會以 stdout_20180205194132_1934.log 的形式儲存在 [logs] 資料夾中。	`aspnetcore-stdout`

設定環境變數

您可以在 processPath 屬性中為處理序指定環境變數。請使用 <environmentVariable> 集合元素的 <environmentVariables> 子元素來指定環境變數。

警告

此節中所設定的環境變數與使用相同名稱設定的系統環境變數相衝突。若同時在 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>

警告

請只有在未受信任網路 (例如網際網路) 無法存取的暫存和測試伺服器上，才將 ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。

app_offline.htm

啟動錯誤頁面

如果 ASP.NET Core 模組無法啟動後端處理序，或後端處理序啟動但無法在所設定的連接埠上進行接聽，就會顯示 [502.5 - 處理序失敗] 狀態碼頁面。若要抑制此頁面並還原至預設的 IIS 502 狀態碼頁面，請使用 disableStartUpErrorPage 屬性。如需有關設定自訂錯誤訊息的詳細資訊，請參閱 HTTP 錯誤 <httpErrors>。

日誌建立和重新導向

除非發生處理序回收/重新啟動，否則不會輪替記錄檔。主機服務提供者必須負責限制記錄檔所使用的磁碟空間。

建立記錄檔時，系統會自動新增時間戳記和副檔名。記錄檔名稱是將時間戳記、處理序識別碼及副檔名 (.log) 以底線分隔後，附加到 stdoutLogFile 路徑的最後一個區段上 (通常是 stdout) 來組成的。如果 stdoutLogFile 路徑的結尾是 stdout，則在 2018 年 2 月 5 日 19:42:32 建立且 PID 為 1934 的應用程式記錄檔檔案名稱會是 stdout_20180205194132_1934.log。

下列範例 aspNetCore 元素會在相對路徑 .\log\ 設定 stdout 記錄。確認 AppPool 使用者身份有權寫入所提供的路徑。

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

若要建立記錄篩選規則，請參閱 ASP.NET Core 記錄文件中的在程式碼中套用記錄篩選規則一節。

如需路徑格式的詳細資訊，請參閱 Windows 系統上的檔案路徑格式。

Proxy 組態使用 HTTP 通訊協定和配對令牌

在 ASP.NET Core 模組與 Kestrel 之間建立的 Proxy 會使用 HTTP 通訊協定。沒有從伺服器外的位置竊聽模組與 Kestrel 之間流量的風險。

具有 IIS 共用設定的 ASP.NET Core 模組

ASP.NET Core 模組安裝程式會以 TrustedInstaller 帳戶的權限執行。由於本機系統帳戶並未具備 IIS 共用設定所使用的共用路徑修改權限，因此，安裝程式在嘗試於共用上的 applicationHost.config 檔案中進行模組設定時，會擲回拒絕存取的錯誤。

使用「IIS 共用設定」時，請依照下列步驟進行操作：

停用「IIS 共用設定」。
執行安裝程式。
將已更新的 applicationHost.config 檔案匯出到共用。
重新啟用「IIS 共用設定」。

模組版本和宿主套件安裝程式記錄檔

判斷已安裝的 ASP.NET Core 模組版本：

在主控系統上，瀏覽至 %windir%\System32\inetsrv。
找出 aspnetcore.dll 檔案。
在該檔案上按一下滑鼠右鍵，然後從關聯式功能表中選取 [內容]。
選取 [詳細資料] 索引標籤。[檔案版本] 和 [產品版本] 代表已安裝的模組版本。

模組的「裝載套件組合」安裝程式記錄檔位於 C:\Users\%UserName%\AppData\Local\Temp。檔案的名稱為 dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log。

模組、結構描述及設定檔位置

模組

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

架構

IIS

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

IIS 快車

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

組態

IIS

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

IIS 快車

Visual Studio：{APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI：%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

在 applicationHost.config 檔案中搜尋 aspnetcore，即可找到這些檔案。

其他資源

使用 IIS 在 Windows 上裝載 ASP.NET Core
將 ASP.NET Core 應用程式部署至 Azure App 服務
ASP.NET Core 模組參考來源 [預設分支 (主要)]：使用 [分支] 下拉式清單選取特定版本 (例如，release/3.1)。
與 ASP.NET Core 搭配運作的 IIS 模組

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-01