Transformation de fichiers de code source et de configurationTransforming source code and configuration files

Pour les projets utilisant packages.config, NuGet offre la possibilité d’effectuer des transformations sur les fichiers de code source et de configuration au moment de l’installation et de la désinstallation des packages.For projects using packages.config, NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. Seules les transformations du code source sont appliquées en cas d’installation d’un package dans un projet avec PackageReference.Only Source code transformations are applied when a package is installed in a project using PackageReference.

Une transformation de code source applique un remplacement unilatéral des jetons aux fichiers inclus dans le dossier content ou contentFiles (content pour les clients utilisant packages.config et contentFiles pour PackageReference) au moment où le package est installé, où les jetons font référence aux propriétés de projet Visual Studio.A source code transformation applies one-way token replacement to files in the package's content or contentFiles folder (content for customers using packages.config and contentFiles for PackageReference) when the package is installed, where tokens refer to Visual Studio project properties. Ainsi, vous pouvez insérer un fichier dans l’espace de noms du projet, ou bien personnaliser du code qui irait normalement dans global.asax dans un projet ASP.NET.This allows you to insert a file into the project's namespace, or to customize code that would typically go into global.asax in an ASP.NET project.

Une transformation de fichier de configuration vous permet de modifier des fichiers qui existent déjà dans un projet cible, comme web.config et app.config.A config file transformation allows you to modify files that already exist in a target project, such as web.config and app.config. Par exemple, votre package peut avoir besoin d’ajouter un élément à la section modules dans le fichier de configuration.For example, your package might need to add an item to the modules section in the config file. Cette transformation est effectuée en incluant des fichiers spéciaux dans le package qui décrivent les sections à ajouter aux fichiers de configuration.This transformation is done by including special files in the package that describe the sections to add to the configuration files. Lorsqu’un package est désinstallé, ces mêmes modifications sont alors annulées, ce qui en fait une transformation bidirectionnelle.When a package is uninstalled, those same changes are then reversed, making this a two-way transformation.

Spécification de transformations de code sourceSpecifying source code transformations

  1. Les fichiers que vous voulez insérer à partir du package dans le projet doivent se trouver dans les dossiers content et contentFiles du package.Files that you want to insert from the package into the project must be located within the package's content and contentFiles folders. Par exemple, si vous voulez installer un fichier appelé ContosoData.cs dans un dossier Models du projet cible, il doit se trouver à l’intérieur des dossiers content\Models et contentFiles\{lang}\{tfm}\Models dans le package.For example, if you want a file called ContosoData.cs to be installed in a Models folder of the target project, it must be inside the content\Models and contentFiles\{lang}\{tfm}\Models folders in the package.

  2. Pour demander à NuGet d’appliquer un remplacement des jetons au moment de l’installation, ajoutez .pp au nom du fichier de code source.To instruct NuGet to apply token replacement at install time, append .pp to the source code file name. Après l’installation, le fichier ne porte pas l’extension .pp.After installation, the file will not have the .pp extension.

    Par exemple, pour effectuer des transformations dans ContosoData.cs, nommez le fichier dans le package ContosoData.cs.pp.For example, to make transformations in ContosoData.cs, name the file in the package ContosoData.cs.pp. Après l’installation, il s’affiche en tant que ContosoData.cs.After installation it will appear as ContosoData.cs.

  3. Dans le fichier de code source, utilisez des jetons ne respectant pas la casse sous la forme $token$ pour indiquer les valeurs que NuGet doit remplacer par les propriétés de projet :In the source code file, use case-insensitive tokens of the form $token$ to indicate values that NuGet should replace with project properties:

    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 le projet cible a pour espace de noms racine Fabrikam.Upon installation, NuGet replaces $rootnamespace$ with Fabrikam assuming the target project's whose root namespace is Fabrikam.

Le jeton $rootnamespace$ est la propriété de projet la plus souvent utilisée ; toutes les autres sont listés dans la documentation sur les propriétés de projet.The $rootnamespace$ token is the most commonly used project property; all others are listed in project properties. N’oubliez pas, évidemment, que certaines propriétés peuvent être spécifiques du type de projet.Be mindful, of course, that some properties might be specific to the project type.

Spécification de transformations de fichiers de configurationSpecifying config file transformations

Comme décrit dans les sections qui suivent, les transformations de fichiers de configuration peuvent être effectuées de deux manières :As described in the sections that follow, config file transformations can be done in two ways:

  • Incluez des fichiers app.config.transform et web.config.transform dans le dossier content de votre package, où l’extension .transform indique à NuGet que ces fichiers contiennent le code XML à fusionner avec les fichiers de configuration existants lors de l’installation du package.Include app.config.transform and web.config.transform files in your package's content folder, where the .transform extension tells NuGet that these files contain the XML to merge with existing config files when the package is installed. Lorsqu’un package est désinstallé, ce même code XML est supprimé.When a package is uninstalled, that same XML is removed.
  • Incluez les fichiers app.config.install.xdt et web.config.install.xdt dans le dossier content de votre package en utilisant la syntaxe XDT pour décrire les changements souhaités.Include app.config.install.xdt and web.config.install.xdt files in your package's content folder, using XDT syntax to describe the desired changes. Avec cette option, vous pouvez également inclure un fichier .uninstall.xdt pour annuler ces modifications lorsque le package est supprimé d’un projet.With this option you can also include a .uninstall.xdt file to reverse changes when the package is removed from a project.

Notes

Les transformations ne sont pas appliquées aux fichiers .config référencés sous forme de lien dans Visual Studio.Transformations are not applied to .config files referenced as a link in Visual Studio.

L’avantage d’utiliser la syntaxe XDT est qu’au lieu de simplement fusionner deux fichiers statiques, elle permet de manipuler la structure d’un DOM XML en faisant correspondre éléments et attributs à l’aide d’une prise en charge XPath complète.The advantage of using XDT is that instead of simply merging two static files, it provides a syntax for manipulating the structure of an XML DOM using element and attribute matching using full XPath support. La syntaxe XDT permet alors d’ajouter, de mettre à jour ou de supprimer des éléments, de placer de nouveaux éléments à un emplacement spécifique ou de remplacer/supprimer des éléments (y compris des nœuds enfants).XDT can then add, update, or remove elements, place new elements at a specific location, or replace/remove elements (including child nodes). La création de transformations de désinstallation qui reviennent sur toutes les transformations effectuées pendant l’installation du package est ainsi facilitée.This makes it straightforward to create uninstall transforms that back out all transformations done during package installation.

Transformations XMLXML transforms

Les fichiers app.config.transform et web.config.transform du dossier content d’un package contiennent uniquement les éléments à fusionner dans les fichiers app.config et web.config existants du projet.The app.config.transform and web.config.transform in a package's content folder contain only those elements to merge into the project's existing app.config and web.config files.

Par exemple, supposons que le projet contienne initialement ce qui suit dans web.config :As an example, suppose the project initially contains the following content in 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 d’un package, créez un fichier web.config.transform dans le dossier content du package qui ressemble à ceci :To add a MyNuModule element to the modules section during package install, create a web.config.transform file in the package's content folder that looks like this:

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

Une fois que NuGet a installé le package, web.config apparaît comme suit :After NuGet installs the package, web.config will appear as follows:

<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 section modules, mais y a simplement fusionné la nouvelle entrée en ajoutant uniquement de nouveaux éléments et attributs.Notice that NuGet didn't replace the modules section, it just merged the new entry into it by adding only new elements and attributes. NuGet ne modifie pas les éléments ou attributs existants.NuGet will not change any existing elements or attributes.

Lorsque le package est désinstallé, NuGet réexamine les fichiers .transform et supprime les éléments qu’ils contiennent provenant des fichiers .config appropriés.When the package is uninstalled, NuGet will examine the .transform files again and remove the elements it contains from the appropriate .config files. Notez que ce processus n’affecte pas les lignes du fichier .config que vous modifiez après l’installation du package.Note that this process will not affect any lines in the .config file that you modify after package installation.

Comme un exemple plus complet, le package Gestionnaires et modules d’enregistrement des erreurs (ELMAH) pour ASP.NET ajoute de nombreuses entrées dans web.config, qui sont de nouveau supprimées lors de la désinstallation d’un package.As a more extensive example, the Error Logging Modules and Handlers for ASP.NET (ELMAH) package adds many entries into web.config, which are again removed when a package is uninstalled.

Pour examiner son fichier web.config.transform, téléchargez le package ELMAH à partir du lien ci-dessus, remplacez l’extension du package .nupkg par .zip, puis ouvrez content\web.config.transform dans ce fichier ZIP.To examine its web.config.transform file, download the ELMAH package from the link above, change the package extension from .nupkg to .zip, and then open content\web.config.transform in that ZIP file.

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 est disponible sous Visual C# > Web dans la boîte de dialogue Nouveau projet), puis sélectionnez une application ASP.NET vide.To see the effect of installing and uninstalling the package, create a new ASP.NET project in Visual Studio (the template is under Visual C# > Web in the New Project dialog), and select an empty ASP.NET application. Ouvrez web.config pour voir son état initial.Open web.config to see its initial state. Ensuite, cliquez sur le projet, sélectionnez Gérer les packages NuGet, recherchez ELMAH sur nuget.org et installez la version la plus récente.Then right-click the project, select Manage NuGet Packages, browse for ELMAH on nuget.org, and install the latest version. Remarquez toutes les modifications apportées à web.config.Notice all the changes to web.config. Désinstallez maintenant le package : web.config reviendra à son état antérieur.Now uninstall the package and you see web.config revert to its prior state.

Transformations XDTXDT transforms

Vous pouvez modifier des fichiers de configuration en utilisant la syntaxe XDT.You can modify config files using XDT syntax. Vous pouvez également demander à NuGet de remplacer les jetons par des propriétés de projet en plaçant leur nom entre les délimiteurs $ (sans respect de la casse).You can also have NuGet replace tokens with project properties by including the property name within $ delimiters (case-insensitive).

Par exemple, le fichier app.config.install.xdt suivant insère un élément appSettings dans app.config qui contient les valeurs FullPath, FileName et ActiveConfigurationSettings du projet :For example, the following app.config.install.xdt file will insert an appSettings element into app.config containing the FullPath, FileName, and ActiveConfigurationSettings values from the project:

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

Autre exemple, supposons que le projet contienne initialement ce qui suit dans web.config :For another example, suppose the project initially contains the following content in 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 package, le fichier web.config.install.xdt du package doit contenir ce qui suit :To add a MyNuModule element to the modules section during package install, the package's web.config.install.xdt would contain the following:

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

Après avoir installé le package, web.config ressemble à ceci :After installing the package, web.config will look like this:

<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 MyNuModule pendant la désinstallation du package, le fichier web.config.uninstall.xdt doit contenir ce qui suit :To remove only the MyNuModule element during package uninstall, the web.config.uninstall.xdt file should contain the following:

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