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

Artigo
08/10/2023

Uma transformação de código-fonte aplicará a substituição de token unidirecional aos arquivos na pasta content ou contentFiles do pacote (content para clientes usando packages.config e contentFiles para PackageReference) quando o pacote estiver instalado e quando os tokens fizerem referência às propriedades do projeto do Visual Studio. Isso permite inserir um arquivo de namespace de projeto ou personalizar código que geralmente iria para global.asax em um projeto do ASP.NET.

Uma transformação do arquivo de configuração permite que você modifique os arquivos que já existem em um projeto de destino, como web.config e app.config. Por exemplo, seu pacote pode ser necessário para adicionar um item à seção modules no arquivo de configuração. Essa transformação são feitas incluindo arquivos especiais no pacote que descreve as seções a serem adicionadas aos arquivos de configuração. Quando um pacote é desinstalado, essas mesmas alterações são revertidas, tornando esta uma transformação bidirecional.

Especificar as transformações do código-fonte

Os arquivos do pacote que você deseja inserir no projeto devem estar localizados nas pastas content e contentFiles do pacote. Por exemplo, se você desejar que um arquivo chamado ContosoData.cs seja instalado em uma pasta Models do projeto de destino, ele precisará estar nas pastas content\Models 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 extensão .pp.

Por exemplo, para realizar transformações em ContosoData.cs, nomeie o arquivo no pacote ContosoData.cs.pp. Após a instalação, ele será exibido como ContosoData.cs.
No arquivo de código-fonte, use tokens que não diferenciam maiúsculas e minúsculas no formato $token$ para indicar os valores que o NuGet deve substituir com as 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, considerando o projeto de destino cujo namespace da raiz é Fabrikam.

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

Especificar as transformações do arquivo de configuração

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

Inclua os arquivos app.config.transform e web.config.transform na pasta content do seu pacote, em que a extensão .transform diz ao NuGet que esses arquivos contêm o XML para serem mesclados com os arquivos de configuração existentes quando o pacote é 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 sintaxe XDT para descrever as alterações desejadas. Com essa opção, também é possível incluir um arquivo .uninstall.xdt para reverter as alterações quando o pacote é removido de um projeto.

Observação

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

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

Transformações de XML

Os app.config.transform e web.config.transform na pasta content de um pacote contém apenas os elementos para mesclar os arquivos app.config e web.config existentes do projeto.

Por exemplo, suponha que o projeto inicialmente contém o conteúdo a seguir 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 que se assemelhará a esta:

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

Depois que o NuGet instala 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 seção modules, ele só mesclou a nova entrada com ele adicionando somente novos elementos e atributos. O NuGet não alterará nenhum atributo ou elemento existente.

Quando o pacote é desinstalado, o NuGet examinará os arquivos .transform novamente e remove os elementos que ele contém dos arquivos .config apropriados. Observe que esse processo não afetará as linhas no arquivo .config que podem ser modificadas após a instalação do pacote.

Como um exemplo mais amplo, o pacote Módulos e manipuladores de log de erros para ASP.NET (ELMAH) adiciona várias entradas a web.config, que são removidas novamente quando um pacote é desinstalado.

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

Para ver o efeito de instalação e desinstalação do pacote, crie um novo projeto do ASP.NET no Visual Studio (o modelo está em 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 botão direito do mouse no projeto, selecione Gerenciar pacotes do NuGet, procurar ELMAH no nuget.org e instalar a versão mais recente. Observe todas as alterações em web.config. Agora, desinstale o pacote e você verá o web.config reverter para seu estado anterior.

Transformações XDT

Observação

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

Você pode modificar os arquivos de configuração usando sintaxe XDT. Você também pode fazer com que o NuGet substitua os tokens pelas Propriedades do projeto incluindo o nome da propriedade dentro dos delimitadores $(não diferencia maiúsculas de minúsculas).

Por exemplo, o arquivo app.config.install.xdt a seguir inserirá um elemento appSettings em app.config que contém os valores FullPath, FileName e ActiveConfigurationSettings valores 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 ver outro exemplo, considere que o projeto inicialmente tem o conteúdo a seguir 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 de pacotes, o web.config.install.xdt do pacote poderia conter 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 se parecerá com o seguinte:

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

Share via