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

Uma transformação de código-fonte aplica uma substituição unidirecional de tokens a arquivos na pasta do content ou contentFiles do pacote (content para clientes que utilizam packages.config e contentFiles para PackageReference) quando o pacote é instalado, onde os tokens referem-se às propriedades do projeto do Visual Studio. Isso permite que você insira um arquivo no namespace do projeto ou personalize o código que normalmente entraria 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, seu pacote pode precisar 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 esta 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 do pacote content e contentFiles pastas. Por exemplo, se você quiser que um arquivo chamado ContosoData.cs seja instalado em uma Models pasta do projeto de destino, ele deve 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 do código-fonte. Após a instalação, o arquivo não terá a .pp extensão.

Por exemplo, para fazer transformações no ContosoData.cs, nomeie o arquivo no pacote ContosoData.cs.pp. Após a instalação, aparecerá como ContosoData.cs.
No arquivo de código-fonte, use tokens no formato $token$ insensíveis a maiúsculas/minúsculas 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 desde que o namespace raiz do projeto de destino seja Fabrikam.

O $rootnamespace$ token é a propriedade do projeto mais usada, todas as outras estão listadas nas propriedades do projeto. Esteja ciente, é 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 do arquivo de configuração podem ser feitas de duas maneiras:

Inclua os ficheiros app.config.transform e web.config.transform na pasta content do pacote, onde a extensão .transform indica ao NuGet que esses ficheiros contêm o XML para mesclar com arquivos de configuração existentes quando o pacote é instalado. Quando um pacote é desinstalado, esse mesmo XML é removido.
Inclua app.config.install.xdt e web.config.install.xdt arquivos na pasta do content seu 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 correspondência de elementos e atributos usando suporte XPath completo. O XDT pode então 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 revertem todas as transformações feitas durante a instalação do pacote.

Transformações XML

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

Como exemplo, suponha que o projeto contenha inicialmente 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 aparecerá 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, apenas mesclou a nova entrada nela 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 instalação do .config pacote.

Como um exemplo mais extenso, o pacote ELMAH (Error Logging Modules and Handlers for ASP.NET) adiciona muitas entradas ao web.config, que são novamente removidas quando um pacote é desinstalado.

Para examinar seu web.config.transform arquivo, baixe o pacote ELMAH no 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á em Visual C# > Web na caixa de diálogo Novo Projeto) e selecione um aplicativo ASP.NET vazio. Abra web.config para ver o 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 no web.config. Agora desinstale o pacote e você verá web.config reverter para seu estado anterior.

Transformações XDT

Observação

Conforme mencionado na Secçã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 suportadas apenas pelo packages.config. Se adicionar os arquivos abaixo ao seu pacote, os consumidores que utilizam o seu pacote com PackageReference não terão as transformações aplicadas (consulte este exemplo para fazer com que as transformações XDT funcionem 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 nos $ delimitadores (sem distinção entre maiúsculas e minúsculas).

Por exemplo, o seguinte arquivo 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 contenha inicialmente 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 à secção modules durante a instalação do pacote, o web.config.install.xdt do pacote conteria 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 ficheiro 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