共用方式為


轉換 web.config

注意

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

警告

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

重要

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

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

作者:Vijay Ramakrishnan

web.config 檔案的轉換可在發佈應用程式時,根據下列條件進行套用:

這些轉換會針對下列任一 web.config 產生案例進行:

  • Microsoft.NET.Sdk.Web SDK 自動產生。
  • 由開發人員在應用程式的內容根目錄中提供。

組建組態

組建組態會第一個執行。

請為每個需要進行 web.config 轉換的 組建組態 (Debug|Release) 包含一個 web.{CONFIGURATION}.config 檔案。

在下列範例中,會在 web.Release.config 中設定一個組態特定的環境變數:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location>
    <system.webServer>
      <aspNetCore>
        <environmentVariables xdt:Transform="InsertIfMissing">
          <environmentVariable name="Configuration_Specific" 
                               value="Configuration_Specific_Value" 
                               xdt:Locator="Match(name)" 
                               xdt:Transform="InsertIfMissing" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

當組態設定為 Release 時,就會套用轉換:

dotnet publish --configuration Release

組態的 MSBuild 屬性為 $(Configuration)

設定檔

設定檔轉換會第二個執行,亦即在組建組態轉換之後執行。

請為每個需要進行 web.config 轉換的設定檔組態包含一個 web.{PROFILE}.config 檔案。

在下列範例中,會在資料夾發佈設定檔的 web.FolderProfile.config 中設定一個設定檔特定的環境變數:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location>
    <system.webServer>
      <aspNetCore>
        <environmentVariables xdt:Transform="InsertIfMissing">
          <environmentVariable name="Profile_Specific" 
                               value="Profile_Specific_Value" 
                               xdt:Locator="Match(name)" 
                               xdt:Transform="InsertIfMissing" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

當設定檔為 FolderProfile 時,就會套用轉換:

dotnet publish --configuration Release /p:PublishProfile=FolderProfile

設定檔名稱的 MSBuild 屬性為 $(PublishProfile)

如果未傳遞任何設定檔,則預設的設定檔名稱為 FileSystem,而如果檔案存在於應用程式的內容根目錄中,就會套用 web.FileSystem.config

環境

環境轉換會第三個執行,亦即在 組建組態設定檔轉換之後執行。

請為每個需要進行 web.config 轉換的環境包含一個 web.{ENVIRONMENT}.config檔案。

在下列範例中,會在生產環境的 web.Production.config 中設定一個環境特定的環境變數:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location>
    <system.webServer>
      <aspNetCore>
        <environmentVariables xdt:Transform="InsertIfMissing">
          <environmentVariable name="Environment_Specific" 
                               value="Environment_Specific_Value" 
                               xdt:Locator="Match(name)" 
                               xdt:Transform="InsertIfMissing" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

當環境為 Production 時,就會套用轉換:

dotnet publish --configuration Release /p:EnvironmentName=Production

環境的 MSBuild 屬性為 $(EnvironmentName)

從 Visual Studio 發行並使用發行設定檔時,請參閱適用於 ASP.NET Core 應用程式部署的 Visual Studio 發佈設定檔 (.pubxml)

已指定環境名稱時,ASPNETCORE_ENVIRONMENT 環境變數會自動新增至 web.config 檔案。

自訂

自訂轉換會第四個執行,亦即在 組建組態設定檔環境轉換之後執行。

請為每個需要進行 web.config 轉換的自訂組態包含一個 {CUSTOM_NAME}.transform 檔案。

在下列範例中,會在 custom.transform 中設定一個自訂轉換環境變數:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location>
    <system.webServer>
      <aspNetCore>
        <environmentVariables xdt:Transform="InsertIfMissing">
          <environmentVariable name="Custom_Specific" 
                               value="Custom_Specific_Value" 
                               xdt:Locator="Match(name)" 
                               xdt:Transform="InsertIfMissing" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

CustomTransformFileName 屬性傳遞給 dotnet publish 命令時,就會套用轉換:

dotnet publish --configuration Release /p:CustomTransformFileName=custom.transform

設定檔名稱的 MSBuild 屬性為 $(CustomTransformFileName)

防止 web.config 轉換

若要防止轉換 web.config 檔案,請設定 $(IsWebConfigTransformDisabled) MSBuild 屬性:

dotnet publish /p:IsWebConfigTransformDisabled=true

其他資源