Transformation du code source et des fichiers de configuration

Une transformation de code source applique un remplacement unidirectionnel de jetons aux fichiers dans le dossier content ou contentFiles (content pour les clients utilisant packages.config et contentFiles pour PackageReference) lorsque le package est installé, où les jetons se réfèrent aux propriétés du projet de Visual Studio. Cela vous permet d’insérer un fichier dans l’espace de noms du projet, ou de personnaliser le code qui serait généralement entré global.asax dans un projet ASP.NET.

Une transformation de fichier de configuration vous permet de modifier des fichiers qui existent déjà dans un projet cible, tels que web.config et app.config. Par exemple, votre package peut avoir besoin d’ajouter un élément à la modules section du fichier de configuration. Cette transformation est effectuée en incluant des fichiers spéciaux dans le package qui décrivent les sections à ajouter aux fichiers de configuration. Lorsqu’un package est désinstallé, ces mêmes modifications sont ensuite inversées, ce qui rend cette transformation bidirectionnel.

Spécification des transformations de code source

Les fichiers que vous souhaitez insérer à partir du paquet dans le projet doivent se trouver dans les dossiers content et contentFiles du paquet. Par exemple, si vous souhaitez qu’un fichier appelé ContosoData.cs soit installé dans un dossier Models du projet cible, il doit se trouver à l’intérieur des dossiers content\Models et contentFiles\{lang}\{tfm}\Models du package.
Pour demander à NuGet d’appliquer le remplacement de jeton au moment de l’installation, ajoutez .pp au nom du fichier de code source. Après l’installation, le fichier n’aura pas l’extension .pp .

Par exemple, pour effectuer des transformations dans ContosoData.cs, nommez le fichier dans le package ContosoData.cs.pp. Une fois l’installation terminée, elle apparaît sous la forme ContosoData.cs.
Dans le fichier de code source, utilisez des jetons insensibles à la casse de la forme $token$ pour indiquer les valeurs que NuGet doit remplacer par les propriétés du projet :
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Lors de l’installation, NuGet remplace $rootnamespace$ par Fabrikam, en supposant que l’espace de noms racine du projet cible est Fabrikam.

Le $rootnamespace$ jeton est la propriété de projet la plus utilisée couramment ; tous les autres sont répertoriés dans propriétés du projet. N’oubliez pas, bien sûr, que certaines propriétés peuvent être spécifiques au type de projet.

Spécification des transformations de fichier de configuration

Comme décrit dans les sections qui suivent, les transformations de fichier de configuration peuvent être effectuées de deux manières :

Incluez app.config.transform et web.config.transform fichiers dans le dossier de content votre package, où l’extension .transform indique à NuGet que ces fichiers contiennent le code XML à fusionner avec les fichiers config existants lorsque le package est installé. Lorsqu’un package est désinstallé, ce même code XML est supprimé.
Incluez les fichiers app.config.install.xdt et web.config.install.xdt dans le dossier content de votre package, à l’aide de la syntaxe XDT pour décrire les modifications souhaitées. Avec cette option, vous pouvez également inclure un .uninstall.xdt fichier pour inverser les modifications lorsque le package est supprimé d’un projet.

Note

Les transformations ne sont pas appliquées aux .config fichiers référencés en tant que lien dans Visual Studio.

L’avantage de l’utilisation de XDT est qu’au lieu de fusionner simplement deux fichiers statiques, il fournit une syntaxe permettant de manipuler la structure d’un DOM XML à l’aide d’un élément et d’une correspondance d’attributs à l’aide de la prise en charge complète de XPath. XDT peut ensuite ajouter, mettre à jour ou supprimer des éléments, placer de nouveaux éléments à un emplacement spécifique ou remplacer/supprimer des éléments (y compris des nœuds enfants). Cela facilite la création de transformations de désinstallation qui sauvegardent toutes les transformations effectuées lors de l’installation du package.

Transformations XML

Le dossier app.config.transform et web.config.transform dans le dossier d’un package content contiennent seulement les éléments nécessaires à fusionner dans les fichiers app.config et web.config existants du projet.

Par exemple, supposons que le projet contient initialement le contenu suivant dans web.config:

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

Pour ajouter un élément MyNuModule à la section modules lors de l’installation du paquet, créez un fichier web.config.transform dans le dossier du paquet content qui ressemble à ceci :

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

Une fois nuGet installé le package, web.config s’affiche comme suit :

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

Notez que NuGet n’a pas remplacé la modules section, il vient de fusionner la nouvelle entrée en lui ajoutant uniquement de nouveaux éléments et attributs. NuGet ne modifie pas les éléments ou attributs existants.

Lorsque le package est désinstallé, NuGet examine à nouveau les .transform fichiers et supprime les éléments qu’il contient des fichiers appropriés .config . Notez que ce processus n’affecte pas les lignes du .config fichier que vous modifiez après l’installation du package.

Par exemple, les modules et gestionnaires de journalisation des erreurs pour ASP.NET (ELMAH) ajoutent de nombreuses entrées web.config, qui sont à nouveau supprimées lorsqu’un package est désinstallé.

Pour examiner son web.config.transform fichier, téléchargez le package ELMAH à partir du lien ci-dessus, changez l'extension du package de .nupkg à .zip, puis ouvrez content\web.config.transform dans ce fichier ZIP.

Pour voir l’effet de l’installation et de la désinstallation du package, créez un projet ASP.NET dans Visual Studio (le modèle se trouve sous Visual C# > Web dans la boîte de dialogue Nouveau projet), puis sélectionnez une application ASP.NET vide. Ouvrez web.config pour voir son état initial. Cliquez ensuite avec le bouton droit sur le projet, sélectionnez Gérer les packages NuGet, recherchez ELMAH sur nuget.org, puis installez la dernière version. Notez toutes les modifications apportées à web.config. Désinstallez maintenant le package et vous voyez web.config revenir à son état antérieur.

Transformations XDT

Note

Comme mentionné dans la section problèmes de compatibilité des packages de la documentation pour la migration vers packages.configPackageReference, les transformations XDT, comme décrit ci-dessous, ne sont prises en charge que par packages.config. Si vous ajoutez les fichiers ci-dessous à votre package, les consommateurs qui utilisent votre package PackageReference n’ont pas les transformations appliquées (reportez-vous à cet exemple pour que les transformations XDT fonctionnent avecPackageReference).

Vous pouvez modifier des fichiers de configuration à l’aide de la syntaxe XDT. Vous pouvez également faire en sorte que NuGet remplace des jetons par des propriétés de projet en incluant le nom de la propriété entre les délimiteurs $ (insensible à la casse).

Par exemple, le fichier suivant app.config.install.xdt insère un appSettings élément dans app.config qui contient les valeurs FullPath, FileName, et ActiveConfigurationSettings du projet.

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

Pour un autre exemple, supposons que le projet contient initialement le contenu suivant dans web.config:

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

Pour ajouter un élément MyNuModule à la section modules pendant l'installation du paquet, le paquet web.config.install.xdt contiendrait les éléments suivants :

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

Une fois le package installé, web.config il se présente comme suit :

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

Pour supprimer uniquement l’élément lors de la désinstallation du MyNuModule package, le web.config.uninstall.xdt fichier doit contenir les éléments suivants :

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

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-31