Partager via

Déploiement d'un processeur de directive personnalisé

  • Article

Pour utiliser un processeur de directives personnalisé dans Visual Studio sur n’importe quel ordinateur, vous devez l’inscrire avec l’une des méthodes décrites dans cette rubrique.

Les différentes méthodes disponibles sont les suivantes :

  • Extensions Visual Studio. Cette extension permet d'installer et de désinstaller le processeur de directive sur votre propre ordinateur et sur d'autres. En général, vous pouvez empaqueter d'autres fonctionnalités dans la même extension VSIX.

  • 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.

  • Définition d'une clé de Registre. Dans cette méthode, vous ajoutez une entrée de Registre pour le processeur de directive.

Vous devez utiliser une de ces méthodes uniquement si vous voulez transformer votre modèle de texte dans Visual Studio ou 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.

Déploiement d'un processeur de directive dans une extension VSIX

Vous pouvez ajouter un processeur de directives personnalisé à une Extension Visual Studio (VSIX).

Vous devez vérifier que les deux éléments suivants figurent dans le fichier .vsix :

  • L'assembly (.dll) qui contient la classe du processeur de directive personnalisé.

  • Un fichier .pkgdef qui inscrit le processeur de directive. Le nom racine du fichier doit être identique à celui de l'assembly. Par exemple, vos fichiers peuvent être nommés CDP.dll et CDP.pkgdef.

Pour inspecter ou modifier le contenu d'un fichier .vsix, remplacez son extension de nom par .zip, puis ouvrez-le. Après avoir modifié le contenu, réaffectez l'extension .vsix au nom de fichier.

Un fichier .vsix peut être créé de plusieurs façons. La procédure suivante décrit une de ces méthodes.

Pour développer un processeur de directive personnalisé dans un projet VSIX

  1. Créez un projet VSIX.

  2. Dans source.extension.vsixmanifest, définissez le type de contenu et les éditions prises en charge.

    1. Dans l’éditeur de manifeste VSIX, sous l’onglet Ressources, choisissez Nouveau, puis définissez les propriétés du nouvel élément :

      Type de contenu = VSPackage

      Projet source = <le projet actuel>

    2. Cliquez sur Éditions sélectionnées et vérifiez les types d’installation sur lesquels vous voulez utiliser le processeur de directives.

  3. Ajoutez un fichier .pkgdef et définissez ses propriétés de sorte qu'il soit inclus dans l'extension VSIX.

    1. Créez un fichier texte et nommez-le <assemblyName>.pkgdef.

      <assemblyName> est généralement identique au nom du projet.

    2. Sélectionnez-le dans l'Explorateur de solutions et définissez ses propriétés comme suit :

      Action de génération = Contenu

      Copier dans le répertoire de sortie = Toujours copier

      Ajouter dans VSIX = True

    3. Définissez le nom de l'extension VSIX et assurez-vous que l'ID est unique.

  4. Ajoutez le texte suivant au fichier .pkgdef.

    [$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.

  5. Ajoutez les références suivantes au projet :

    • Microsoft.VisualStudio.TextTemplating.*.0

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

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

  6. Ajoutez la classe de votre processeur de directive personnalisé au projet.

    Il s'agit d'une classe publique qui doit implémenter DirectiveProcessor ou RequiresProvidesDirectiveProcessor.

Pour installer le processeur de directive Personnalisé

  1. Dans l’Explorateur Windows, ouvrez le répertoire de build (en général, bin\Debug ou bin\Release).

  2. Si vous voulez installer le processeur de directive sur un autre ordinateur, copiez sur ce dernier le fichier .vsix.

  3. Double-cliquez sur le fichier .vsix. Le programme d’installation des extensions Visual Studio s’affiche.

  4. Démarrez 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é. Chaque directive se présente comme suit :

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

Pour désinstaller ou temporairement désactiver le processeur de directive personnalisé

  1. Dans le menu Visual Studio Outils, cliquez sur Gestionnaire d’extensions.

  2. Sélectionnez l’extension VSIX qui contient le processeur de directives, puis cliquez sur Désinstaller ou Désactiver.

Dépannage d'un processeur de directive dans une extension VSIX

Si le processeur de directive ne fonctionne pas, les suggestions suivantes peuvent vous aider :

  • 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.

  • Votre méthode IsDirectiveSupported doit retourner la valeur true lorsque le nom de votre CustomDirective lui est passé.

  • Si vous ne voyez pas l’extension dans le Gestionnaire d’extensions, mais que le système ne vous permet pas de l’installer, supprimez-la dans %localappdata%\Microsoft\VisualStudio \*.0\Extensions\.

  • Ouvrez le fichier .vsix et inspectez son contenu. Pour l'ouvrir, remplacez l'extension de nom du fichier par .zip. Vérifiez qu'il contient les fichiers .dll, .pkgdef et extension.vsixmanifest. 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 :

    <Content>

    <VsPackage>CustomDirectiveProcessor.dll</VsPackage>

    </Content>

Déploiement d'un processeur de directive dans un 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.

Placez l'attribut suivant sur la classe de votre package :

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

Notes

Cet attribut est placé sur la classe du package, et non pas sur la classe du processeur de directive.

Le fichier .pkgdef sera généré en même temps que le projet. Lorsque vous installerez le VSPackage, le fichier .pkgdef inscrira le processeur de directive.

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. S'il ne s'affiche pas, ouvrez le fichier .csproj dans un éditeur de texte et supprimez le nœud suivant : <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Pour plus d'informations, consultez VSPackages.

Définition d'une clé de Registre

Cette méthode d'installation d'un processeur de directive personnalisé est la moins recommandée. 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.

Attention

Une modification incorrecte du Registre peut sérieusement endommager votre système. Avant d'apporter des modifications au Registre, veillez à sauvegarder toutes les données importantes qui se trouvent sur l'ordinateur.

Pour inscrire un processeur de directive en définissant une clé de Registre

  1. Exécutez regedit.

  2. Dans regedit, accédez à

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

    Si vous voulez installer le processeur de directives dans la version expérimentale de Visual Studio, insérez « Exp » après « 11.0 ».

  3. Ajoutez une clé de Registre ayant le même nom que la classe du processeur de directive.

    • Dans l’arborescence du Registre, cliquez avec le bouton droit sur le nœud DirectiveProcessors, pointez sur Nouveau, puis cliquez sur Clé.

  4. Dans le nouveau nœud, ajoutez des valeurs de chaîne pour Class, CodeBase ou Assembly, en fonction des tableaux suivants.

    1. Cliquez avec le bouton droit sur le nœud que vous avez créé, pointez sur Nouveau, puis cliquez sur Valeur de chaîne.

    2. Modifiez le nom de la valeur.

    3. Double-cliquez sur le nom et modifiez les données.

    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 :

Nom Type Données
(Par défaut) REG_SZ (valeur non définie)
Classe REG_SZ <Nom de l’espace de noms>.<Nom de la classe>
CodeBase REG_SZ <Votre chemin>\<Le nom de votre assembly>

Si l'assembly se trouve dans le GAC, les sous-clés de Registre doivent se présenter comme dans le tableau suivant :

Nom Type Données
(Par défaut) REG_SZ (valeur non définie)
Classe REG_SZ <Le nom complet de votre classe>
Assembly REG_SZ <Nom de votre assembly dans le GAC>

Contenu connexe