共用方式為

轉換 web.config

  • 發行項

注意

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

警告

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

重要

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

如需目前的版本，請參閱 本文的 .NET 9 版本。

作者：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

其他資源