Transformando o código-fonte e os arquivos de configuração
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
econtentFiles
do pacote. Por exemplo, se você desejar que um arquivo chamadoContosoData.cs
seja instalado em uma pastaModels
do projeto de destino, ele precisará estar nas pastascontent\Models
econtentFiles\{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 pacoteContosoData.cs.pp
. Após a instalação, ele será exibido comoContosoData.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$
porFabrikam
, 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
eweb.config.transform
na pastacontent
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
eweb.config.install.xdt
na pastacontent
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>