Compartilhar via


Transformação do Web.config

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Por Vijay Ramakrishnan

As transformações no arquivo web.config podem ser aplicadas automaticamente quando um aplicativo é publicado com base em:

Essas transformações ocorrem para qualquer um dos seguintes cenários de geração web.config:

  • Gerado automaticamente pelo SDK Microsoft.NET.Sdk.Web.
  • Fornecido pelo desenvolvedor na raiz do conteúdo do aplicativo.

Configuração de compilação

Transformações de configuração de compilação são executadas primeiros.

Inclua um arquivo web.{CONFIGURATION}.config para cada configuração de build (Debug|Release) que exija uma transformação de web.config.

No exemplo a seguir, uma variável de ambiente específica à configuração está definida em 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>

A transformação é aplicada quando a configuração é definida como Release:

dotnet publish --configuration Release

A propriedade de MSBuild para a configuração é $(Configuration).

Perfil

As transformações de perfil são executadas depois, após as transformações da Configuração de build.

Inclua um arquivo web.{PROFILE}.config para cada configuração de perfil que exija uma transformação de web.config.

No exemplo a seguir, uma variável de ambiente específica ao perfil está definida em web.FolderProfile.config para um perfil de publicação de pasta:

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

A transformação é aplicada quando o perfil for FolderProfile:

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

A propriedade de MSBuild para o nome do perfil é $(PublishProfile).

Se nenhum perfil for passado, o nome do perfil padrão será FileSystem e web. FileSystem.config será aplicado se o arquivo estiver presente na raiz de conteúdo do aplicativo.

Ambiente

As transformações de ambiente são executadas logo após as transformações da Configuração de build e de Perfil.

Inclua um arquivo web.{ENVIRONMENT}.config para cada ambiente que exija uma transformação de web.config.

No exemplo a seguir, uma variável de ambiente específica ao ambiente é definida em web.Production.config para o ambiente de Produção:

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

A transformação será aplicada quando o ambiente for Produção:

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

A propriedade de MSBuild para o ambiente é $(EnvironmentName).

Ao publicar do Visual Studio e usar um perfil de publicação, consulte Perfis de publicação do Visual Studio (.pubxml) para implantação de aplicativo do ASP.NET Core.

A variável de ambiente ASPNETCORE_ENVIRONMENT é adicionada automaticamente ao arquivo web.config quando o nome do ambiente for especificado.

Personalizado

As transformações personalizadas são executadas por último, após as transformações da Configuração de build, de Perfil e de Ambiente.

Inclua um arquivo {CUSTOM_NAME}.transform para cada configuração personalizada que exija uma transformação de web.config.

No exemplo a seguir, uma variável de ambiente de transformação personalizada está definida em 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>

A transformação é aplicada quando a propriedade CustomTransformFileName é passada para o comando dotnet publish:

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

A propriedade de MSBuild para o nome do perfil é $(CustomTransformFileName).

Impedir a transformação de web.config

Para impedir transformações do arquivo web.config, defina a propriedade de MSBuild $(IsWebConfigTransformDisabled):

dotnet publish /p:IsWebConfigTransformDisabled=true

Recursos adicionais