转换 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 转换的每个生成配置(调试|发布)添加 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>

当配置设置为“发布”时,将应用转换:

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>

当环境为“生产”时,将应用转换:

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 文件,请设置 MSBuild 属性 $(IsWebConfigTransformDisabled)

dotnet publish /p:IsWebConfigTransformDisabled=true

其他资源