`web.config` 檔案

發行項
11/30/2023

web.config是 IIS 和 ASP.NET Core Module 所讀取的檔案，用來設定裝載於 IIS 的應用程式。

`web.config` 檔案位置

為了正確設定 ASP.NET Core 模組，web.config 檔案必須存在於已部署應用程式的內容根路徑 (通常是應用程式基底路徑)。這是與提供給 IIS 的網站實體路徑相同的位置。應用程式的根目錄需有 web.config 檔案，才能使用 Web Deploy 發行多個應用程式。

敏感性檔案存在於應用程式的實體路徑上，例如 {ASSEMBLY}.runtimeconfig.json、{ASSEMBLY}.xml (XML 文件註解) 和 {ASSEMBLY}.deps.json，其中預留位置 {ASSEMBLY} 是組件名稱。當 web.config 檔案存在且網站正常啟動時，如果有人要求機密檔案，IIS 不會予以提供。若 web.config 檔案遺失或沒有正確命名，或是無法設定網站以正常啟動，IIS 可能會公開提供機密檔案。

web.config 檔案必須持續存在於部署之中、已正確命名，並能夠設定網站以正常啟動。無論在任何情況下，請都不要從生產環境部署移除 web.config 檔案。

如果專案中沒有 web.config 檔案，則系統會使用正確的 processPath 和 arguments 建立該檔案以設定 ASP.NET Core 模組，並將該檔案移至已發佈的輸出。

如果專案中沒有 web.config 檔案，則系統會使用正確的 processPath 和 arguments 轉換該檔案以設定 ASP.NET Core 模組，並將該檔案移至已發佈的輸出。轉換不會修改檔案中的 IIS 組態設定。

web.config 檔案可提供能控制作用中 IIS 模組的額外 IIS 組態設定。如需能處理 ASP.NET Core 應用程式要求之 IIS 模組的相關資訊，請參閱 IIS 模組主題。

發佈專案時，由 MSBuild 目標 (_TransformWebConfig) 處理 web.config 檔案的建立、轉換及發佈。此目標存在於 Web SDK 目標 (Microsoft.NET.Sdk.Web)。 SDK 設定在專案檔的頂端：

<Project Sdk="Microsoft.NET.Sdk.Web">

為防止 Web SDK 轉換 web.config 檔案，請使用專案檔中的 <IsTransformWebConfigDisabled> 屬性：

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

使 Web SDK 無法轉換檔案時，應該由開發人員手動設定 processPath 和 arguments。如需詳細資訊，請參閱適用於 IIS 的 ASP.NET Core 模組 (ANCM)。

使用 `web.config` 設定 ASP.NET Core 模組

設定 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 子應用程式組態的資訊，請參閱進階設定。

`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`	選擇性字串屬性。指定記錄來自 `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 中設定兩個環境變數。 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 中直接設定環境的一種替代方案，是在發行設定檔 (.pubxml) 或專案檔中納入 <EnvironmentName> 屬性。此方法會在專案發行時於 web.config 中設定環境：

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

警告

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

使用 `web.config` 設定 IIS

在對使用了 ASP.NET Core 模組的 ASP.NET Core 有作用的 IIS 情境下，IIS 組態會受 web.config 的 <system.webServer> 區段影響。舉例來說，IIS 設定對動態壓縮有作用。如果在伺服器層級將 IIS 設為使用動態壓縮，應用程式 web.config 檔案中的 <urlCompression> 元素則可為 ASP.NET Core 應用程式予以停用。

如需詳細資訊，請參閱下列主題：

若要設定在隔離的應用程式集區中執行之個別應用程式的環境變數 (支援 IIS 10.0 或更新版本)，請參閱 IIS 參考文件的環境變數 Environment Variables<environmentVariables> 主題的 AppCmd.exe 命令一節。

`web.config` 的組態區段

ASP.NET Core 應用程式的設定不使用 web.config 中 ASP.NET 4.x 應用程式的設定區段：

<system.web>
<appSettings>
<connectionStrings>
<location>

使用其他組態提供者設定的 ASP.NET Core 應用程式。如需詳細資訊，請參閱組態。

轉換 web.config

如果您需要在發佈時轉換 web.config，請參閱轉換 web.config。您可能需要在發佈時轉換 web.config，以根據組態、設定檔或環境來設定環境變數。

共用方式為

`web.config` 檔案