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

發行項
04/11/2023

ASP.NET Core模組 (ANCM) 是一種原生 IIS 模組，可插入 IIS 管線，讓 ASP.NET Core應用程式能夠使用 IIS。使用 IIS 執行 ASP.NET Core應用程式，方法是：

在 IIS 背景工作進程內裝載 ASP.NET Core應用程式 () w3wp.exe ，稱為同進程裝載模型。
將 Web 要求轉送至執行伺服器的後端 ASP.NET Core應用程式 Kestrel ，稱為跨進程裝載模型。

每個裝載模型之間都有取捨。根據預設，會使用進程內裝載模型，因為效能和診斷更好。

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

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

(ANCM) 安裝 ASP.NET Core模組

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 Server (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\inetsrvw3wp.exe 而不是應用程式目錄 (。

如需設定應用程式目前目錄的範例程式碼，請參閱類別 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 套件 (單一檔案) 部署。

跨處理序裝載模型

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

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

同進程裝載會設定為 InProcess ，這是預設值。

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

Kestrel 伺服器是用來取代 IIS HTTP Server (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 進行設定

設定 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 Service 時，stdoutLogFile 路徑會設定為 \\?\%home%\LogFiles\stdout。路徑會將 stdout 記錄儲存至 LogFiles 資料夾，這是服務自動建立的位置。

如需 IIS 子應用程式設定的相關資訊，請參閱Windows 上的主機 ASP.NET Core與 IIS。

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`	`InProcess` `inprocess`
`processesPerApplication`	選擇性的整數屬性。指定 processPath 設定中所指定處理序執行個體每個應用程式可上調的數目。 †針對進程內裝載，此值限制為 `1` 。不建議使用 `processesPerApplication` 設定。此屬性將在未來版本中移除。	預設： `1` 最小值：`1` 最大值： `100` †
`processPath`	必要的字串屬性。啟動接聽 HTTP 要求之處理序的可執行檔路徑。支援相對路徑。如果路徑的開頭為 `.`，該路徑即被視為網站根目錄的相對路徑。
`rapidFailsPerMinute`	選擇性的整數屬性。指定允許 processPath 中所指定處理序每分鐘當機的次數。如果超出此限制，模組就會在該分鐘的剩餘時間內停止啟動處理序。不支援同處理序裝載。	預設： `10` 最小值：`0` 最大值︰`100`
`requestTimeout`	選擇性的時間範圍屬性。針對在 %ASPNETCORE_PORT% 進行接聽的處理序，指定 ASP.NET Core 模組等候回應的持續時間。在 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`	選擇性字串屬性。指定記錄來自 processPath 中所指定處理序之 stdout 和 stderr 的相對或絕對檔案路徑。相對路徑是相對於網站的根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。建立記錄檔後，模組會建立路徑中提供的所有資料夾。使用底線分隔符號、時間戳記、進程識別碼和副檔名 () `.log` 會新增至 stdoutLogFile 路徑的最後一個區段。如果 `.\logs\stdout` 以值的形式提供，範例 stdout 記錄檔會在 `stdout_20180205194132_1934.loglogs` 2018/2018 年 2 月 5 日儲存為 19：41：32，且進程識別碼為 1934 時儲存為資料夾中。	`aspnetcore-stdout`

設定環境變數

您可以在 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>

警告

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

`app_offline.htm`

如果在應用程式的根目錄中偵測到名稱 app_offline.htm 為的檔案，ASP.NET Core Module 會嘗試正常關閉應用程式，並停止處理傳入的要求。如果在經過 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>。

記錄檔建立和重新導向

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

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

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

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

建立記錄檔時，系統會自動新增時間戳記和副檔名。記錄檔名稱是由附加時間戳記、進程識別碼和副檔名 (.log) 至路徑的最後一個區段 stdoutLogFile ， (通常會 stdout 以底線分隔) 。 stdoutLogFile如果路徑結尾為 stdout ，則 2018 年 2 月 5 日于 19：42：32 于 2018 年 2 月 5 日建立之應用程式的記錄檔名稱 stdout_20180205194132_1934.log 為。

若 stdoutLogEnabled 為 false，會擷取在應用程式啟動時發生的錯誤，並發出最大 30KB 的事件記錄檔。啟動之後，就會捨棄其他的記錄檔。

下列範例 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) 值可以同時包含層級和位置。

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

ERROR
WARNING
INFO
TRACE

位置 (允許多個位置)：

主控台
EVENTLOG
FILE

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

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

警告

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

如需檔案中 web.config 專案的範例 aspNetCore ，請參閱使用 web.config組態。

修改堆疊大小

僅適用于使用進程內裝載模型時。

使用中的 web.config 位元組設定來 stackSize 設定 Managed 堆疊大小。預設大小為 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 模組之間建立的 Proxy，並使用 Kestrel 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。

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

模組

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 Express

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

Visualstudio： {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe Cli： %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

您可以在檔案中 applicationHost.config 搜尋 aspnetcore 來找到檔案。

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 Server (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 Server () 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 驗證權杖。

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

如需如何安裝 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 為，表示位置 > 專案內 <指定的設定不會由位於應用程式的子目錄中的應用程式繼承。

將應用程式部署至 Azure App Service 時，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`	選擇性的時間範圍屬性。針對在 %ASPNETCORE_PORT% 進行接聽的處理序，指定 ASP.NET Core 模組等候回應的持續時間。在 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`	選擇性字串屬性。指定記錄中所 `stdoutstderrprocessPath` 指定進程的相對或絕對檔案路徑。相對路徑是相對於網站的根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。建立記錄檔後，模組會建立路徑中提供的所有資料夾。使用底線分隔符號、時間戳記、進程識別碼和副檔名 (`.log`) 會新增至路徑的最後一個區段 `stdoutLogFile` 。如果 `.\logs\stdout` 以值的形式提供，範例 stdout 記錄檔會在 2/5/2018 于 19：41：32 儲存于 1934 時儲存在 `stdout_20180205194132_1934.loglogs` 資料夾中。	`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

如果在應用程式的根目錄中偵測到名稱為 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 - 啟動失敗] 狀態碼頁面。

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

記錄檔建立和重新導向

如果已設定 aspNetCore 元素的 stdoutLogEnabled 和 stdoutLogFile 屬性，ASP.NET Core 模組就會將 stdout 和 stderr 主控台輸出重新導向到磁碟。建立記錄檔後，模組會建立 stdoutLogFile 路徑中的所有資料夾。應用程式集區必須具有寫入記錄位置的寫入權限， (用來 IIS AppPool\{APP POOL NAME} 提供寫入權限，其中預留位置 {APP POOL NAME} 是應用程式集區名稱) 。

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

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

建立記錄檔時，系統會自動新增時間戳記和副檔名。記錄檔名稱是由將時間戳記、進程識別碼和副檔名 .log () 附加至路徑的最後一個區段 stdoutLogFile ， (通常是 stdout 以底線分隔) 所組成。如果路徑結尾為 stdoutLogFilestdout ，則 2018 年 2 月 5 日于 19：42：32 于 2018 年 2 月 5 日建立之應用程式的記錄檔具有檔案名 stdout_20180205194132_1934.log 。

若 stdoutLogEnabled 為 false，會擷取在應用程式啟動時發生的錯誤，並發出最大 30KB 的事件記錄檔。啟動之後，就會捨棄其他的記錄檔。

下列範例 aspNetCore 專案會在相對路徑 .\log\ 上設定 stdout 記錄。確認應用程式集區使用者身分識別具有寫入所提供路徑的許可權。

<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 服務裝載的應用程式預先定義的。

如需路徑格式的詳細資訊，請參閱 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) 值可以同時包含層級和位置。

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

ERROR
WARNING
INFO
TRACE

位置 (允許多個位置)：

主控台
EVENTLOG
FILE

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

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

警告

如需檔案中 web.config 專案的範例 aspNetCore ，請參閱使用 web.config組態。

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

僅適用於跨處理序裝載。

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

具有 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 Express

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

Visualstudio： {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe Cli： %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

您可以在檔案中 applicationHost.config 搜尋 aspnetcore 來找到檔案。

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 子應用程式設定的相關資訊，請參閱Windows 上的主機 ASP.NET Core與 IIS。

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`	選擇性的時間範圍屬性。針對在 %ASPNETCORE_PORT% 進行接聽的處理序，指定 ASP.NET Core 模組等候回應的持續時間。在 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`	選擇性字串屬性。指定記錄來自 processPath 中所指定處理序之 stdout 和 stderr 的相對或絕對檔案路徑。相對路徑是相對於網站的根目錄。所有開頭為 `.` 的路徑都是網站根目錄的相對路徑，而所有其他路徑則視為絕對路徑。路徑中提供的所有資料夾都必須存在，模組才能建立記錄檔。使用底線分隔符號，時間戳記、處理序識別碼及副檔名 (.log) 會新增至 stdoutLogFile 路徑的最後一個區段。如果提供 `.\logs\stdout` 作為值，在 2018 年 2 月 5 日的 19:41:32 以處理序識別碼 1934 進行儲存時，範例 stdout 記錄檔就會以 stdout_20180205194132_1934.log 的形式儲存在 [logs] 資料夾中。	`aspnetcore-stdout`

設定環境變數

您可以在 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>

警告

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

app_offline.htm

app_offline.htm當檔案存在時，ASP.NET Core模組會藉由傳回檔案的內容 app_offline.htm 來回應要求。移除檔案 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 模組之間建立的 Proxy，並使用 Kestrel 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 共用設定」。
執行安裝程式。
將已更新的 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 Express

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

組態

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，即可找到這些檔案。

其他資源

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