Déploiement d'un processeur de directive personnaliséDeploying a Custom Directive Processor

Pour utiliser un processeur de directive personnalisé dans Visual Studio sur n’importe quel ordinateur, vous devez l’inscrire par une des méthodes décrites dans cette rubrique.To use a custom directive processor in Visual Studio on any computer, you must register it by one of the methods described in this topic.

Les différentes méthodes disponibles sont les suivantes :The alternative methods are:

  • Extensions Visual Studio.Visual Studio Extensions. Cette extension permet d'installer et de désinstaller le processeur de directive sur votre propre ordinateur et sur d'autres.This provides a way to install and uninstall the directive processor both on your own computer and on other computers. En général, vous pouvez empaqueter d’autres fonctionnalités dans la même extension VSIX.Typically, you might package other features in the same VSIX.

  • VSPackage.VSPackage. Si vous définissez un VSPackage qui contient d’autres fonctionnalités en plus du processeur de directive, vous pouvez aisément inscrire ce dernier.If you are defining a VSPackage that contains other features in addition to the directive processor, there is a convenient method of registering the directive processor.

  • Définition d'une clé de Registre.Set a registry key. Dans cette méthode, vous ajoutez une entrée de Registre pour le processeur de directive.In this method, you add a registry entry for the directive processor.

Vous devez utiliser une de ces méthodes uniquement si vous voulez transformer votre modèle de texte dans Visual Studio ou MSBuild.You need to use one of these methods only if you want to transform your text template in Visual Studio or MSBuild. Si vous employez un hôte personnalisé dans votre propre application, celui-ci est chargé de rechercher les processeurs de directive pour chaque directive.If you use a custom host in your own application, your custom host is responsible for finding the directive processors for each directive.

Déploiement d'un processeur de directive dans une extension VSIXDeploying a Directive Processor in a VSIX

Vous pouvez ajouter un processeur de directive personnalisé à un Extension Visual Studio (VSIX).You can add a custom directive processor to a Visual Studio Extension (VSIX).

Vous devez vérifier que les deux éléments suivants figurent dans le fichier .vsix :You need to make sure that the following two items are contained in the .vsix file:

  • L'assembly (.dll) qui contient la classe du processeur de directive personnalisé.The assembly (.dll) that contains the custom directive processor class.

  • Un fichier .pkgdef qui inscrit le processeur de directive.A .pkgdef file that registers the directive processor. Le nom racine du fichier doit être identique à celui de l'assembly.The root name of the file must be the same as the assembly. Par exemple, vos fichiers peuvent être nommés CDP.dll et CDP.pkgdef.For example, your files could be named CDP.dll and CDP.pkgdef.

Pour inspecter ou modifier le contenu d’un fichier .vsix, remplacez son extension de nom par .zip, puis ouvrez-le.To inspect or change the content of a .vsix file, change its file name extension to .zip and then open it. Après avoir modifié le contenu, réaffectez l'extension .vsix au nom de fichier.After editing the contents, change the filename back to .vsix.

Un fichier .vsix peut être créé de plusieurs façons.There are several ways of creating a .vsix file. La procédure suivante décrit une de ces méthodes.The following procedure describes one method.

Pour développer un processeur de directive personnalisé dans un projet VSIXTo develop a custom directive processor in a VSIX project

  1. Créez un projet VSIX dans Visual Studio.Create a VSIX project in Visual Studio.

    • Dans le nouveau projet boîte de dialogue, développez Visual Basic ou Visual C#, puis développez extensibilité.In the New Project dialog box, expand Visual Basic or Visual C#, then expand Extensibility. Cliquez sur projet VSIX.Click VSIX Project.
  2. Dans source.extension.vsixmanifest, définissez le type de contenu et les éditions prises en charge.In source.extension.vsixmanifest, set the content type and supported editions.

    1. Dans l’extension VSIX, l’éditeur de manifeste sur le actifs , choisir New et définissez les propriétés du nouvel élément :In the VSIX manifest editor, on the Assets tab, choose New and set the new item's properties:

      Type de contenu = VSPackageContent Type = VSPackage

      Projet source = <le projet actuel>Source Project = <the current project>

    2. Cliquez sur éditions sélectionnées et vérifiez les types d’installation sur lequel vous souhaitez que le processeur de directive pour être utilisable.Click Selected Editions and check the types of installation on which you want the directive processor to be usable.

  3. Ajoutez un fichier .pkgdef et définissez ses propriétés de sorte qu'il soit inclus dans l'extension VSIX.Add a .pkgdef file and set its properties to be included in the VSIX.

    1. Créez un fichier texte et nommez-le < assemblyName> .pkgdef.Create a text file and name it <assemblyName>.pkgdef.

      <assemblyName> est généralement le même que le nom du projet.<assemblyName> is usually the same as the name of the project.

    2. Sélectionnez-le dans l'Explorateur de solutions et définissez ses propriétés comme suit :Select it in Solution Explorer and set its properties as follows:

      Action de génération = contenuBuild Action = Content

      Copy to Output Directory = toujours copierCopy to Output Directory = Copy Always

      Inclure dans VSIX = TrueInclude in VSIX = True

    3. Définissez le nom de l'extension VSIX et assurez-vous que l'ID est unique.Set the name of the VSIX and make sure that the ID is unique.

  4. Ajoutez le texte suivant au fichier .pkgdef.Add the following text to the .pkgdef file.

    [$RootKey$\TextTemplating]
    [$RootKey$\TextTemplating\DirectiveProcessors]
    [$RootKey$\TextTemplating\DirectiveProcessors\ CustomDirectiveProcessorName]
    @="Custom Directive Processor description"
    "Class"="NamespaceName.ClassName"
    "CodeBase"="$PackageFolder$\AssemblyName.dll"
    

    Remplacez les noms suivants par vos propres noms : CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.Replace the following names with your own names: CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.

  5. Ajoutez les références suivantes au projet :Add the following references to the project:

    • Microsoft.VisualStudio.TextTemplating.*.0Microsoft.VisualStudio.TextTemplating.*.0

    • Microsoft.VisualStudio.TextTemplating.Interfaces.*.0Microsoft.VisualStudio.TextTemplating.Interfaces.*.0

    • Microsoft.VisualStudio.TextTemplating.VSHost. *.0Microsoft.VisualStudio.TextTemplating.VSHost.*.0

  6. Ajoutez la classe de votre processeur de directive personnalisé au projet.Add your custom directive processor class to the project.

    Il s'agit d'une classe publique qui doit implémenter DirectiveProcessor ou RequiresProvidesDirectiveProcessor.This is a public class that should implement DirectiveProcessor or RequiresProvidesDirectiveProcessor.

Pour installer le processeur de directive PersonnaliséTo install the Custom Directive Processor

  1. Dans l’Explorateur Windows, ouvrez le répertoire de build (en général, bin\Debug ou bin\Release).In Windows Explorer, open the build directory (usually bin\Debug or bin\Release).

  2. Si vous voulez installer le processeur de directive sur un autre ordinateur, copiez sur ce dernier le fichier .vsix.If you want to install the directive processor on another computer, copy the .vsix file to the other computer.

  3. Double-cliquez sur le fichier .vsix.Double-click the .vsix file. Le programme d’installation de Visual Studio Extension s’affiche.The Visual Studio Extension Installer appears.

  4. Redémarrez Visual Studio.Restart Visual Studio. Vous pourrez désormais exécuter des modèles de texte qui contiennent des directives faisant référence au processeur de directive personnalisé.You will now be able to run text templates that contain directives that refer to the custom directive processor. Chaque directive se présente comme suit :Each directive is of this form:

    <#@ CustomDirective Processor="CustomDirectiveProcessorName" parameter1="value1" ... #>

Pour désinstaller ou temporairement désactiver le processeur de directive personnaliséTo uninstall or temporarily disable the custom directive processor

  1. Dans Visual Studio outils menu, cliquez sur Gestionnaire d’extensions.In the Visual Studio Tools menu, click Extension Manager.

  2. Sélectionnez l’extension VSIX qui contient le processeur de directive, puis cliquez sur désinstallation ou désactiver.Select the VSIX that contains the directive processor, and then click Uninstall or Disable.

Dépannage d'un processeur de directive dans une extension VSIXTroubleshooting a Directive Processor in a VSIX

Si le processeur de directive ne fonctionne pas, les suggestions suivantes peuvent vous aider :If the directive processor does not work, the following suggestions might help:

  • Le nom de processeur que vous spécifiez dans la directive personnalisée doit correspondre à la valeur CustomDirectiveProcessorName que vous avez indiquée dans le fichier .pkgdef.The Processor name that you specify in the custom directive should match the CustomDirectiveProcessorName that you specified in the .pkgdef file.

  • Votre méthode IsDirectiveSupported doit retourner la valeur true lorsque le nom de votre CustomDirective lui est passé.Your IsDirectiveSupported method must return true when it is passed the name of your CustomDirective.

  • Si vous ne voyez pas l’extension dans le Gestionnaire d’extensions, mais le système vous autorisera pas à installer, supprimez-la de %localappdata%\Microsoft\VisualStudio\*. 0\Extensions\ .If you cannot see the extension in Extension Manager, but the system will not allow you to install it, delete the extension from %localappdata%\Microsoft\VisualStudio\*.0\Extensions\.

  • Ouvrez le fichier .vsix et inspectez son contenu.Open the .vsix file and inspect its contents. Pour l’ouvrir, remplacez l’extension de nom du fichier par .zip.To open it, change the filename extension to .zip. Vérifiez qu'il contient les fichiers .dll, .pkgdef et extension.vsixmanifest.Verify that it contains the .dll, .pkgdef, and extension.vsixmanifest files. Le fichier extension.vsixmanifest doit comporter la liste appropriée dans le nœud SupportedProducts, ainsi qu’un nœud VsPackage sous le nœud de contenu :The extension.vsixmanifest file should contain the appropriate list in the SupportedProducts node, and should also contain a VsPackage node under the Content node:

    <Content>

    <VsPackage>CustomDirectiveProcessor.dll</VsPackage>

    </Content>

Déploiement d'un processeur de directive dans un VSPackageDeploying a Directive Processor in a VSPackage

Si votre processeur de directive fait partie d'un VSPackage qui sera installé dans le GAC, vous pouvez faire en sorte que le système génère le fichier .pkgdef à votre place.If your directive processor is part of a VSPackage that will be installed in the GAC, you can have the system generate the .pkgdef file for you.

Placez l'attribut suivant sur la classe de votre package :Place the following attribute on your package class:

[ProvideDirectiveProcessor(typeof(DirectiveProcessorClass), "DirectiveProcessorName", "Directive processor description.")]

Note

Cet attribut est placé sur la classe du package, et non pas sur la classe du processeur de directive.This attribute is placed on the package class, not the directive processor class.

Le fichier .pkgdef sera généré en même temps que le projet.The .pkgdef file will be generated when you build the project. Lorsque vous installerez le VSPackage, le fichier .pkgdef inscrira le processeur de directive.When you install the VSPackage, the .pkgdef file will register the directive processor.

Vérifiez que le fichier .pkgdef s’affiche dans le dossier de génération, qui correspond en général à bin\Debug ou bin\Release.Verify that the .pkgdef file appears in the build folder, which is usually bin\Debug or bin\Release. S'il ne s'affiche pas, ouvrez le fichier .csproj dans un éditeur de texte et supprimez le nœud suivant : <GeneratePkgDefFile>false</GeneratePkgDefFile>.If it does not appear, open the .csproj file in a text editor, and remove the following node: <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Pour plus d’informations, consultez VSPackages.For more information, see VSPackages.

Définition d'une clé de RegistreSetting a Registry Key

Cette méthode d'installation d'un processeur de directive personnalisé est la moins recommandée.This method of installing a custom directive processor is the least preferred. Elle ne permet pas d'activer ni de désactiver facilement le processeur de directive, et ne fournit pas de méthode pour distribuer le processeur de directive aux autres utilisateurs.It does not provide a convenient way enable and disable the directive processor, and does not provide a method of distributing the directive processor to other users.

Caution

Toute modification incorrecte du Registre peut gravement endommager votre système.Incorrectly editing the registry can severely damage your system. Avant d'apporter des modifications au Registre, veillez à sauvegarder toutes les données importantes qui se trouvent sur l'ordinateur.Before making changes to the registry, be sure to back up any valued data on the computer.

Pour inscrire un processeur de directive en définissant une clé de RegistreTo register a directive processor by setting a registry key

  1. Exécutez regedit.Run regedit.

  2. Dans regedit, accédez àIn regedit, navigate to

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessorsHKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors

    Si vous souhaitez installer le processeur de directive dans la version expérimentale de Visual Studio, insérez « Exp » après « 11.0 ».If you want to install the directive processor in the experimental version of Visual Studio, insert "Exp" after "11.0".

  3. Ajoutez une clé de Registre ayant le même nom que la classe du processeur de directive.Add a registry key that has the same name as the directive processor class.

    • Dans l’arborescence du Registre, cliquez sur le DirectiveProcessors nœud, pointez sur New, puis cliquez sur clé.In the registry tree, right-click the DirectiveProcessors node, point to New, and then click Key.
  4. Dans le nouveau nœud, ajoutez des valeurs de chaîne pour Class, CodeBase ou Assembly, en fonction des tableaux suivants.In the new node, add string values for Class and CodeBase or Assembly, according to the following tables.

    1. Cliquez sur le nœud que vous avez créé, pointez sur New, puis cliquez sur valeur de chaîne.Right-click the node that you created, point to New, and then click String Value.

    2. Modifiez le nom de la valeur.Edit the name of the value.

    3. Double-cliquez sur le nom et modifiez les données.Double-click the name and edit the data.

    Si le processeur de directive personnalisé ne se trouve pas dans le GAC, les sous-clés de Registre doivent se présenter comme dans le tableau suivant :If the custom directive processor is not in the GAC, the registry subkeys should look like the following table:

NameName TypeType DonnéesData
(Default)(Default) REG_SZREG_SZ (valeur non définie)(value not set)
ClasseClass REG_SZREG_SZ <Nom de Namespace >. <Nom de la classe ><Namespace Name>.<Class Name>
CodeBaseCodeBase REG_SZREG_SZ <Votre chemin d’accès >\< votre nom de l’Assembly><Your Path>\<Your Assembly Name>

Si l'assembly se trouve dans le GAC, les sous-clés de Registre doivent se présenter comme dans le tableau suivant :If the assembly is in the GAC, the registry subkeys should look like the following table:

NameName TypeType DonnéesData
(Default)(Default) REG_SZREG_SZ (valeur non définie)(value not set)
ClasseClass REG_SZREG_SZ <Votre nom de classe complet><Your Fully Qualified Class Name>
AssemblyAssembly REG_SZREG_SZ <Votre nom de l’Assembly dans le GAC><Your Assembly Name in the GAC>

Voir aussiSee also