转换 web.configTransform web.config

作者:Vijay RamakrishnanLuke LathamBy Vijay Ramakrishnan and Luke Latham

基于以下内容发布应用时,可以自动应用对 web.config 文件的转换:Transformations to the web.config file can be applied automatically when an app is published based on:

以下 web.config 生成方案中的任何一个都会发生转换:These transformations occur for either of the following web.config generation scenarios:

  • Microsoft.NET.Sdk.Web SDK 自动生成。Generated automatically by the Microsoft.NET.Sdk.Web SDK.
  • 由开发人员在应用的内容根目录中提供。Provided by the developer in the content root of the app.

生成配置Build configuration

首先运行生成配置转换。Build configuration transforms are run first.

为需要 web.config 转换的每个生成配置(调试|发布)添加 web.{CONFIGURATION}.config 文件。Include a web.{CONFIGURATION}.config file for each build configuration (Debug|Release) requiring a web.config transformation.

以下示例在 web.Release.config 中设置特定于配置的环境变量:In the following example, a configuration-specific environment variable is set in 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>

当配置设置为“发布”时,将应用转换:The transform is applied when the configuration is set to Release:

dotnet publish --configuration Release

配置的 MSBuild 属性为 $(Configuration)The MSBuild property for the configuration is $(Configuration).

配置文件Profile

生成配置转换后,第二个运行配置文件转换。Profile transformations are run second, after Build configuration transforms.

为需要 web.config 转换的每个配置文件配置添加 web.{PROFILE}.config 文件。Include a web.{PROFILE}.config file for each profile configuration requiring a web.config transformation.

以下示例在 web.FolderProfile.config 中为文件夹发布配置文件设置特定于配置文件的环境变量:In the following example, a profile-specific environment variable is set in web.FolderProfile.config for a folder publish profile:

<?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 时,将应用转换:The transform is applied when the profile is FolderProfile:

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

配置文件名称的 MSBuild 属性为 $(PublishProfile)The MSBuild property for the profile name is $(PublishProfile).

如果未传递任何配置文件,则默认配置文件名称为 FileSystem,如果该文件存在于应用的内容根目录中,则应用 web.FileSystem.config。If no profile is passed, the default profile name is FileSystem and web.FileSystem.config is applied if the file is present in the app's content root.

环境Environment

生成配置配置文件转换后,第三个运行环境转换。Environment transformations are run third, after Build configuration and Profile transforms.

为需要 web.config 转换的每个环境添加 web.{ENVIRONMENT}.config 文件。Include a web.{ENVIRONMENT}.config file for each environment requiring a web.config transformation.

以下示例在 web.Production.config 中为生产环境设置特定于环境的环境变量:In the following example, a environment-specific environment variable is set in web.Production.config for the Production environment:

<?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>

当环境为“生产”时,将应用转换:The transform is applied when the environment is Production:

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

环境的 MSBuild 属性为 $(EnvironmentName)The MSBuild property for the environment is $(EnvironmentName).

从 Visual Studio 发布并使用发布配置文件时,请参阅 用于 ASP.NET Core 应用部署的 Visual Studio 发布配置文件When publishing from Visual Studio and using a publish profile, see 用于 ASP.NET Core 应用部署的 Visual Studio 发布配置文件.

指定环境名称时,ASPNETCORE_ENVIRONMENT 环境变量会自动添加到 web.config 文件中。The ASPNETCORE_ENVIRONMENT environment variable is automatically added to the web.config file when the environment name is specified.

自定义Custom

生成配置配置文件环境转换后,最后运行自定义转换。Custom transformations are run last, after Build configuration, Profile, and Environment transforms.

为需要 web.config 转换的每个自定义配置添加 {CUSTOM_NAME}.transform 文件。Include a {CUSTOM_NAME}.transform file for each custom configuration requiring a web.config transformation.

以下示例在 custom.transform 中设置自定义转换环境变量:In the following example, a custom transform environment variable is set in 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 命令时,将应用转换:The transform is applied when the CustomTransformFileName property is passed to the dotnet publish command:

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

配置文件名称的 MSBuild 属性为 $(CustomTransformFileName)The MSBuild property for the profile name is $(CustomTransformFileName).

阻止 web.config 转换Prevent web.config transformation

若要阻止转换 web.config 文件,请设置 MSBuild 属性 $(IsWebConfigTransformDisabled)To prevent transformations of the web.config file, set the MSBuild property $(IsWebConfigTransformDisabled):

dotnet publish /p:IsWebConfigTransformDisabled=true

其他资源Additional resources