共用方式為


web.config 檔案

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本

警告

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

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前版本,請參閱本文的 .NET 8 版本

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 檔案,則系統會使用正確的 processPatharguments 建立該檔案以設定 ASP.NET Core 模組,並將該檔案移至已發佈的輸出

如果專案中沒有 web.config 檔案,則系統會使用正確的 processPatharguments 轉換該檔案以設定 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 無法轉換檔案時,應該由開發人員手動設定 processPatharguments。 如需詳細資訊,請參閱適用於 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 中所指定處理序的 stdoutstderr 會重新導向至 stdoutLogFile中指定的檔案。

false
stdoutLogFile

選擇性字串屬性。

指定記錄來自 processPath 中所指定處理序之 stdoutstderr 的相對或絕對檔案路徑。 相對路徑是相對於網站的根目錄。 所有開頭為 . 的路徑都是網站根目錄的相對路徑,而所有其他路徑則視為絕對路徑。 建立記錄檔後,模組會建立路徑中提供的所有資料夾。 使用底線分隔符號,時間戳記、處理序識別碼及副檔名 (.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,以根據組態、設定檔或環境來設定環境變數。

其他資源