Transformando o código-fonte e os arquivos de configuração

Uma transformação de código-fonte aplica a substituição de token unidirecional a arquivos na pasta ou content no pacote (contentFilespara clientes que usam content e packages.config para contentFiles) quando o pacote é instalado, em que os tokens se referem às PackageReference do Visual Studio. Isso permite que você insira um arquivo no namespace de um projeto ou personalize o código que normalmente iria em global.asax em um projeto ASP.NET.

Uma transformação de arquivo de configuração permite modificar arquivos que já existem em um projeto de destino, como web.config e app.config. Por exemplo, talvez o pacote precise adicionar um item à modules seção no arquivo de configuração. Essa transformação é feita incluindo arquivos especiais no pacote que descrevem as seções a serem adicionadas aos arquivos de configuração. Quando um pacote é desinstalado, essas mesmas alterações são revertidas, tornando essa uma transformação bidirecional.

Especificando transformações de código-fonte

Os arquivos que você deseja inserir do pacote no projeto devem estar localizados dentro das pastas content e contentFiles do pacote. Por exemplo, se você quiser que um arquivo chamado ContosoData.cs seja instalado em uma Models pasta do projeto de destino, ele deverá estar dentro das content\Models pastas e contentFiles\{lang}\{tfm}\Models no pacote.
Para instruir o NuGet a aplicar a substituição de token no momento da instalação, acrescente .pp ao nome do arquivo de código-fonte. Após a instalação, o arquivo não terá a .pp extensão.

Por exemplo, para fazer transformações em ContosoData.cs, nomeie o arquivo no pacote ContosoData.cs.pp. Após a instalação, ele aparecerá como ContosoData.cs.
No arquivo de código-fonte, use tokens que não diferenciam maiúsculas de minúsculas da forma $token$ para indicar valores que o NuGet deve substituir pelas propriedades do projeto.
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Após a instalação, o NuGet substitui $rootnamespace$ por Fabrikam, assumindo que o namespace raiz do projeto de destino seja Fabrikam.

O $rootnamespace$ token é a propriedade de projeto mais usada; todas as outras estão listadas nas propriedades do projeto. Lembre-se, é claro, de que algumas propriedades podem ser específicas para o tipo de projeto.

Especificando transformações de arquivo de configuração

Conforme descrito nas seções a seguir, as transformações de arquivo de configuração podem ser feitas de duas maneiras:

Inclua os arquivos app.config.transform e web.config.transform na pasta content do pacote, onde a extensão .transform informa ao NuGet que esses arquivos contêm o XML para mesclar com os arquivos de configuração existentes quando o pacote for instalado. Quando um pacote é desinstalado, esse mesmo XML é removido.
Inclua os arquivos app.config.install.xdt e web.config.install.xdt na pasta content do pacote, usando a sintaxe XDT para descrever as alterações desejadas. Com essa opção, você também pode incluir um .uninstall.xdt arquivo para reverter as alterações quando o pacote é removido de um projeto.

Observação

As transformações não são aplicadas a .config arquivos referenciados como um link no Visual Studio.

A vantagem de usar XDT é que, em vez de simplesmente mesclar dois arquivos estáticos, ele fornece uma sintaxe para manipular a estrutura de um DOM XML usando a correspondência de elementos e atributos usando o suporte completo do XPath. O XDT pode adicionar, atualizar ou remover elementos, colocar novos elementos em um local específico ou substituir/remover elementos (incluindo nós filho). Isso torna simples criar transformações de desinstalação que fazem backup de todas as transformações feitas durante a instalação do pacote.

Transformações de XML

O app.config.transform e web.config.transform na pasta content de um pacote contêm apenas aqueles elementos para mesclar nos arquivos app.config e web.config existentes do projeto.

Por exemplo, suponha que o projeto inicialmente contenha o seguinte conteúdo em web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Para adicionar um elemento MyNuModule à seção modules durante a instalação do pacote, crie um arquivo web.config.transform na pasta content do pacote com o seguinte formato:

<configuration>
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Depois que o NuGet instalar o pacote, web.config será exibido da seguinte maneira:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Observe que o NuGet não substituiu a modules seção, ele acabou de mesclar a nova entrada a ela adicionando apenas novos elementos e atributos. O NuGet não alterará nenhum elemento ou atributo existente.

Quando o pacote for desinstalado, o NuGet examinará os .transform arquivos novamente e removerá os elementos que ele contém dos arquivos apropriados .config . Observe que esse processo não afetará nenhuma linha no arquivo que você modificar após a .config instalação do pacote.

Como um exemplo mais extenso, o pacote ELMAH (Módulos de Log de Erros e Manipuladores para ASP.NET) adiciona muitas entradas web.config, que são removidas novamente quando um pacote é desinstalado.

Para examinar seu web.config.transform arquivo, baixe o pacote ELMAH do link acima, altere a extensão do pacote de .nupkg para .zipe, em seguida, abra content\web.config.transform nesse arquivo ZIP.

Para ver o efeito da instalação e desinstalação do pacote, crie um novo projeto ASP.NET no Visual Studio (o modelo está no Visual C# > Web na caixa de diálogo Novo Projeto) e selecione um aplicativo ASP.NET vazio. Abra web.config para ver seu estado inicial. Em seguida, clique com o botão direito do mouse no projeto, selecione Gerenciar Pacotes NuGet, procure eLMAH no nuget.org e instale a versão mais recente. Observe todas as alterações em web.config. Agora, desinstale o pacote e você verá web.config reverter para o estado anterior.

Transformações de XDT

Observação

Conforme mencionado na seção de problemas de compatibilidade do pacote dos documentos para migração de packages.config para PackageReference, as transformações XDT, conforme descrito abaixo, são suportadas apenas por packages.config. Se você adicionar os arquivos abaixo ao pacote, os consumidores que usam seu pacote com PackageReference não terão as transformações aplicadas (consulte este exemplo para fazer as transformações XDT funcionarem com PackageReference).

Você pode modificar arquivos de configuração usando a sintaxe XDT. Você também pode fazer com que o NuGet substitua tokens por propriedades do projeto, incluindo o nome da propriedade em $ delimitadores (insensível a maiúsculas e minúsculas).

Por exemplo, o arquivo a seguir app.config.install.xdt inserirá um elemento appSettings em app.config contendo os valores FullPath, FileName e ActiveConfigurationSettings do projeto:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="Insert">
        <add key="FullPath" value="$FullPath$" />
        <add key="FileName" value="$filename$" />
        <add key="ActiveConfigurationSettings " value="$ActiveConfigurationSettings$" />
    </appSettings>
</configuration>

Para outro exemplo, suponha que o projeto inicialmente contenha o seguinte conteúdo em web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Para adicionar um MyNuModule elemento à seção modules durante a instalação do web.config.install.xdt pacote, o web.config.install.xdt incluirá o seguinte:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" xdt:Transform="Insert" />
        </modules>
    </system.webServer>
</configuration>

Depois de instalar o pacote, web.config terá esta aparência:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Para remover apenas o elemento MyNuModule durante a desinstalação do pacote, o arquivo web.config.uninstall.xdt deve conter o seguinte:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" xdt:Transform="Remove" xdt:Locator="Match(name)" />
        </modules>
    </system.webServer>
</configuration>

Comentários

Esta página foi útil?

Last updated on 2025-10-31