Comment : utiliser le contexte d’interface utilisateur basée sur une règle pour les extensions Visual StudioHow to: Use rule-based UI Context for Visual Studio extensions

Visual Studio permet le chargement de VSPackages lorsque certains connu UIContexts sont activés.Visual Studio allows loading of VSPackages when certain well-known UIContexts are activated. Toutefois, ces contextes d’interface utilisateur ne sont pas bien plus précis, ce qui ne laisse les auteurs de l’extension aucun choix mais permettant de sélectionner un contexte d’interface utilisateur disponible qui active avant la virgule, ils voulaient réellement le VSPackage à charger.However, these UI Contexts aren't fine grained, which leaves extension authors no choice but to pick an available UI Context that activates before the point they really wanted the VSPackage to load. Pour obtenir la liste des contextes d’interface utilisateur bien connus, consultez KnownUIContexts.For a list of well-known UI contexts, see KnownUIContexts.

Le chargement de packages peut avoir un impact sur les performances et leur chargement plus tôt que nécessaire n’est pas la meilleure pratique.Loading packages can have a performance impact and loading them sooner than needed is not the best practice. Visual Studio 2015 introduit le concept de contextes d’interface utilisateur basée sur des règles, un mécanisme qui permet aux auteurs d’extension définir les conditions précises sous lesquelles un contexte d’interface utilisateur est activé et VSPackages associés sont chargés.Visual Studio 2015 introduced the concept of Rules-based UI Contexts, a mechanism that allows extension authors to define the precise conditions under which a UI Context is activated and associated VSPackages are loaded.

Contexte de l’interface utilisateur basée sur la règleRule-based UI Context

Une « règle » se compose d’un nouveau contexte de l’interface utilisateur (un GUID) et une expression booléenne qui fait référence à un ou plusieurs « conditions » associé logique « et », « ou », « non » les opérations.A "Rule" consists of a new UI Context (a GUID) and a Boolean expression that references one or more "Terms" combined with logical "and", "or", "not" operations. « Conditions » sont évaluées de manière dynamique lors de l’exécution et l’expression est réévaluée chaque fois qu’un de ses modifications des termes du contrat."Terms" are evaluated dynamically at runtime and the expression is reevaluated whenever any of its terms changes. Lorsque l’expression a la valeur true, le contexte de l’interface utilisateur associée est activé.When the expression evaluates to true, the associated UI Context is activated. Sinon, le contexte de l’interface utilisateur est désactivé.Otherwise, the UI Context is de-activated.

En fonction des règles de contexte de l’interface utilisateur peut être utilisé de différentes manières :Rule-based UI Context can be used in various ways:

  1. Spécifier des contraintes de visibilité pour les commandes et fenêtres Outil.Specify visibility constraints for commands and tool windows. Vous pouvez masquer les commandes/outils windows jusqu'à ce que la règle du contexte d’interface utilisateur est remplie.You can hide the commands/tools windows until the UI Context rule is met.

  2. Contraintes de charge en tant qu’automatique : de charge automatique des packages uniquement lorsque la règle est remplie.As auto load constraints: auto load packages only when the rule is met.

  3. Comme une tâche différée : retarder le chargement jusqu'à ce qu’un intervalle spécifié écoulé et la règle est toujours respectée.As a delayed task: delay loading until a specified interval has passed and the rule is still met.

    Le mécanisme peut être utilisé par n’importe quelle extension de Visual Studio.The mechanism may be used by any Visual Studio extension.

Créer un contexte d’interface utilisateur basée sur la règleCreate a rule-based UI Context

Supposons que vous avez une extension appelée TestPackage, qui offre une commande de menu qui s’applique uniquement aux fichiers avec .config extension.Suppose you have an extension called TestPackage, which offers a menu command that applies only to files with .config extension. Avant de VS2015, la meilleure option a été charger TestPackage lorsque SolutionExistsAndFullyLoadedContext contexte d’interface utilisateur a été activé.Before VS2015, the best option was to load TestPackage when SolutionExistsAndFullyLoadedContext UI Context was activated. Le chargement de TestPackage de cette façon n’est pas efficace, étant donné que la solution chargée ne peut pas contenir de même un .config fichier.Loading TestPackage in this way is not efficient, since the loaded solution may not even contain a .config file. Ces étapes indiquent le contexte d’interface utilisateur basée sur les règles peuvent être utilisées pour activer un contexte d’interface utilisateur uniquement quand un fichier avec .config extension est sélectionné, puis charger TestPackage lorsque ce contexte d’interface utilisateur est activé.These steps show how rules-based UI Context can be used to activate a UI Context only when a file with .config extension is selected, and load TestPackage when that UI Context is activated.

  1. Définir un nouveau GUID UIContext et ajouter à la classe VSPackage ProvideAutoLoadAttribute et ProvideUIContextRuleAttribute.Define a new UIContext GUID and add to the VSPackage class ProvideAutoLoadAttribute and ProvideUIContextRuleAttribute.

    Par exemple, supposons un nouveau UIContext « UIContextGuid » doit être ajoutée.For example, let's assume a new UIContext "UIContextGuid" is to be added. Le GUID créé (vous pouvez créer un GUID en cliquant sur outils > créer un GUID) est « 8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B ».The GUID created (you can create a GUID by clicking on Tools > Create GUID) is "8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B". Ensuite, vous ajoutez la déclaration suivante à l’intérieur de votre classe de package :You then add the following declaration inside your package class:

    public const string UIContextGuid = "8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B";  
    

    Pour les attributs, ajoutez les valeurs suivantes : (les détails de ces attributs seront expliquées plus loin)For the attributes, add the following values: (Details of these attributes will be explained later)

    [ProvideAutoLoad(TestPackage.UIContextGuid)]      
    [ProvideUIContextRule(TestPackage.UIContextGuid,  
        name: "Test auto load",   
        expression: "DotConfig",  
        termNames: new[] { "DotConfig" },  
        termValues: new[] { "HierSingleSelectionName:.config$" })]  
    

    Ces métadonnées définir le nouveau GUID UIContext (8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B) et une expression faisant référence à un terme unique, « DotConfig ».These metadata define the new UIContext GUID (8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B) and an expression referring to a single term, "DotConfig". Le terme « DotConfig » a la valeur true lorsque la sélection actuelle dans la hiérarchie active a un nom qui correspond au modèle d’expression régulière «\.config$ » (se termine par .config).The "DotConfig" term evaluates to true whenever the current selection in the active hierarchy has a name that matches the regular expression pattern "\.config$" (ends with .config). La valeur (valeur par défaut) définit un nom facultatif pour la règle utile pour le débogage.The (Default) value defines an optional name for the rule useful for debugging.

    Les valeurs de l’attribut sont ajoutées à pkgdef généré pendant la génération par la suite.The values of the attribute are added to pkgdef generated during build time afterwards.

  2. Dans le fichier VSCT pour les commandes de la TestPackage, ajoutez l’indicateur « DynamicVisibility » pour les commandes appropriées :In the VSCT file for the TestPackage's commands, add the "DynamicVisibility" flag to the appropriate commands:

    <CommandFlag>DynamicVisibility</CommandFlag>  
    
  3. Dans la section de la visibilité de la VSCT, lier les commandes appropriées pour le nouveau UIContext GUID défini dans #1 :In the Visibilities section of the VSCT, tie the appropriate commands to the new UIContext GUID defined in #1:

    <VisibilityConstraints>   
        <VisibilityItem guid="guidTestPackageCmdSet" id="TestId"  context="guidTestUIContext"/>   
    </VisibilityConstraints>  
    
  4. Dans la section Symbols, ajoutez la définition de la UIContext :In the Symbols section, add the definition of the UIContext:

    <GuidSymbol name="guidTestUIContext" value="{8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B}" />  
    

    À présent, les commandes du menu contextuel pour *.config fichiers seront visibles uniquement lorsque l’élément sélectionné dans l’Explorateur de solutions est un .config fichier et le package ne seront pas chargés tant qu’un de ceux les commandes est activée.Now, the context menu commands for *.config files will be visible only when the selected item in the solution explorer is a .config file and the package will not be loaded until one of those commands is selected.

    Ensuite, utilisez un débogueur pour confirmer que le package est chargé uniquement lorsque vous attendez.Next, use a debugger to confirm that the package loads only when you expect it to. Pour déboguer TestPackage :To debug TestPackage:

  5. Définir un point d’arrêt dans le Initialize (méthode).Set a breakpoint in the Initialize method.

  6. Générer le TestPackage et démarrer le débogage.Build the TestPackage and start debugging.

  7. Créez un projet ou ouvrez un.Create a project or open one.

  8. Sélectionnez n’importe quel fichier avec une extension autre que .config. Le point d’arrêt ne doit pas être atteint.Select any file with an extension other than .config. The breakpoint should not be hit.

  9. Sélectionnez le App.Config fichier.Select the App.Config file.

    Le TestPackage charge et s’arrête au point d’arrêt.The TestPackage loads and stops at the breakpoint.

Ajouter des règles pour le contexte d’interface utilisateurAdd more rules for UI Context

Étant donné que les règles de contexte d’interface utilisateur sont des expressions booléennes, vous pouvez ajouter des règles plus restreintes pour un contexte d’interface utilisateur.Since the UI Context rules are Boolean expressions, you can add more restricted rules for a UI Context. Par exemple, dans le contexte de l’interface utilisateur ci-dessus, vous pouvez spécifier que la règle s’applique uniquement quand une solution avec un projet est chargée.For example, in the above UI Context, you can specify that the rule applies only when a solution with a project is loaded. De cette façon, les commandes ne s’afficheront si vous ouvrez un .config fichier comme un fichier autonome, et non comme partie d’un projet.In this way, the commands won't show up if you open up a .config file as a standalone file, not as part of a project.

[ProvideAutoLoad(TestPackage.UIContextGuid)]      
[ProvideUIContextRule(TestPackage.UIContextGuid,    
    name: "Test auto load",  
    expression: "(SingleProject | MultipleProjects) & DotConfig",    
    termNames: new[] { "SingleProject", "MultipleProjects","DotConfig" },     
    termValues: new[] { VSConstants.UICONTEXT_SolutionHasSingleProject_string , VSConstants.UICONTEXT_SolutionHasMultipleProjects_string , "HierSingleSelectionName:.config$" })]  

Maintenant l’expression fait référence à trois termes.Now the expression references three terms. Les deux premiers termes, « SingleProject » et « MultipleProjects », font référence à d’autres contextes d’interface utilisateur bien connue (par leurs GUID).The first two terms, "SingleProject" and "MultipleProjects", refer to other well-known UI Contexts (by their GUIDs). Le troisième « DotConfig » est le contexte d’interface utilisateur de base de règles définis précédemment dans cet article.The third term, "DotConfig" is the rule-based UI Context defined earlier in this article.

Délai d’activationDelayed activation

Règles peuvent avoir un délai « facultatif ».Rules can have an optional "Delay". Le délai spécifié en millisecondes.The delay is specified in milliseconds. Le cas échéant, le délai provoque l’activation ou la désactivation de contexte d’interface utilisateur d’une règle peut être différé par cet intervalle de temps.If present, the delay causes the activation or deactivation of a Rule's UI Context to be delayed by that time interval. Si les modifications de règle au avant l’intervalle du délai, puis rien ne se produit.If the rule changes back before the delay interval, then nothing happens. Ce mécanisme peut être utilisé pour « échelonner les étapes d’initialisation - en particulier l’initialisation unique sans s’appuyer sur les minuteurs ou de l’inscription aux notifications inactives ».This mechanism can be used to "stagger" initialization steps - especially one-time initialization without relying on timers or registering for idle notifications.

Par exemple, vous pouvez spécifier votre règle de charge de test pour avoir un délai de 100 millisecondes :For example, you can specify your test load rule to have a delay of 100 milliseconds:

[ProvideAutoLoad(TestPackage.UIContextGuid)]  
[ProvideUIContextRule(TestPackage.UIContextGuid,   
    name: "Test auto load",  
    expression: "DotConfig",   
    termNames: new[] { "DotConfig" },  
    termValues: new[] { "HierSingleSelectionName:.config$" },   
    delay: 100)]  

Types de termeTerm types

Voici les différents types de terme qui sont prises en charge :Here are the various types of term that are supported:

TermeTerm DescriptionDescription
{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn} Le GUID fait référence à un contexte d’interface utilisateur.The GUID refers to a UI Context. Le terme sera true chaque fois que le contexte de l’interface utilisateur est active et false sinon.The term will be true whenever the UI Context is active and false otherwise.
HierSingleSelectionName :<modèle >HierSingleSelectionName:<pattern> Le terme sera true chaque fois que la sélection dans la hiérarchie active est un élément unique et le nom de l’élément sélectionné correspond à l’expression régulière .net donnée par « pattern ».The term will be true whenever the selection in the active hierarchy is a single item and the name of the selected item matches the .Net regular expression given by "pattern".
UserSettingsStoreQuery :<requête >UserSettingsStoreQuery:<query> « query » représente un chemin d’accès complet dans la banque de paramètres utilisateur, qui doit correspondre à une valeur différente de zéro."query" represents a full path into the user settings store, which must evaluate to a non-zero value. La requête est divisée en une « collection » et le « propertyName » à la dernière barre oblique.The query is split into a "collection" and "propertyName" at the last slash.
ConfigSettingsStoreQuery :<requête >ConfigSettingsStoreQuery:<query> « query » représente un chemin d’accès complet dans le magasin de paramètres de configuration, qui doit correspondre à une valeur différente de zéro."query" represents a full path into the config settings store, which must evaluate to a non-zero value. La requête est divisée en une « collection » et le « propertyName » à la dernière barre oblique.The query is split into a "collection" and "propertyName" at the last slash.
ActiveProjectFlavor :<projectTypeGuid >ActiveProjectFlavor:<projectTypeGuid> Le terme sera true chaque fois que le projet actuellement sélectionné est versionné (agrégé) et a une version de mise en correspondance du GUID du type de projet donné.The term will be true whenever the currently selected project is flavored (aggregated) and has a flavor matching the given project type GUID.
ActiveEditorContentType :<contentType >ActiveEditorContentType:<contentType> Le terme aura la valeur true lorsque le document sélectionné est un éditeur de texte avec le type de contenu donné.The term will be true when the selected document is a text editor with the given content type.
ActiveProjectCapability :<Expression >ActiveProjectCapability:<Expression> Le terme est true lorsque les fonctionnalités de projet actif correspond à l’expression fournie.The term is true when active project capabilities match the provided expression. Une expression peut être quelque chose comme VB | CSharp.An expression can be something like VB | CSharp.
SolutionHasProjectCapability :<Expression >SolutionHasProjectCapability:<Expression> Similaire à ci-dessus mais terme a la valeur true lorsque la solution a n’importe quel projet chargé qui correspond à l’expression.Similar to above but term is true when solution has any loaded project that matches to the expression.
SolutionHasProjectFlavor :<projectTypeGuid >SolutionHasProjectFlavor:<projectTypeGuid> Le terme sera true chaque fois qu’une solution de projet qui est versionnés (agrégé) et a une version de mise en correspondance du GUID du type de projet donné.The term will be true whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.

Compatibilité avec l’extension d’entre versionsCompatibility with cross-version extension

Contextes d’interface utilisateur basée sur la règle est une nouvelle fonctionnalité dans Visual Studio 2015 et ne serait pas être déplacée vers les versions antérieures.Rule-based UI Contexts is a new feature in Visual Studio 2015 and would not be ported to earlier versions. Ne pas de portage vers des versions antérieures crée un problème avec les extensions/packages qui ciblent plusieurs versions de Visual Studio.Not porting to earlier versions creates a problem with extensions/packages that target multiple versions of Visual Studio. Ces versions doivent être chargées automatiquement dans Visual Studio 2013 et versions antérieures, mais peuvent tirer parti des contextes d’interface utilisateur basée sur la règle afin d’éviter d’être chargées automatiquement dans Visual Studio 2015.Those versions would have to be auto-loaded in Visual Studio 2013 and earlier, but can benefit from rule-based UI Contexts to prevent being auto-loaded in Visual Studio 2015.

Pour prendre en charge ces packages, AutoLoadPackages dans le Registre peuvent maintenant fournir un indicateur dans son champ de valeur pour indiquer que l’entrée doit être ignorée dans Visual Studio 2015 et versions ultérieures.In order to support such packages, AutoLoadPackages entries in the registry can now provide a flag in its value field to indicate that the entry should be skipped in Visual Studio 2015 and above. Cela est possible en ajoutant une option d’indicateurs pour PackageAutoLoadFlags.This can be done by adding a flags option to PackageAutoLoadFlags. Les VSPackages peuvent maintenant ajouter SkipWhenUIContextRulesActive option leurs ProvideAutoLoadAttribute attribut pour indiquer l’entrée doit être ignorée dans Visual Studio 2015 et versions ultérieures.VSPackages can now add SkipWhenUIContextRulesActive option to their ProvideAutoLoadAttribute attribute to indicate the entry should be ignored in Visual Studio 2015 and above.

Règles de contexte d’interface utilisateur extensiblesExtensible UI Context rules

Parfois, les packages ne pouvez pas utiliser les règles de contexte d’interface utilisateur statiques.Sometimes, packages cannot use static UI Context rules. Par exemple, supposons que vous disposez d’un package prenant en charge d’extensibilité, telles que l’état de la commande est basée sur les types d’éditeur qui sont pris en charge par les fournisseurs MEF importés.For example, suppose you have a package supporting extensibility such that the command state is based on editor types that are supported by imported MEF providers. La commande est activée s’il existe une extension prenant en charge le type de modification actuelle.The command is enabled if there is an extension supporting the current edit type. Dans ce cas, le package lui-même ne peut pas utiliser une règle de contexte d’interface utilisateur statique, dans la mesure où les termes du contrat pourrait être modifié selon le MEF extensions sont disponibles.In such cases, the package itself cannot use a static UI Context rule, since the terms would change depending on which MEF extensions are available.

Pour prendre en charge ces packages, contextes d’interface utilisateur basée sur la règle prend en charge une expression codée en dur « * » qui indique tous les termes ci-dessous il sera joint avec ou.In order to support such packages, rule-based UI Contexts support a hardcoded expression "*" that indicates all the terms below it will be joined with OR. Ainsi, le package principal définir un contexte d’interface utilisateur basée sur la règle connus et de lier son état de la commande à ce contexte.This allows for the master package to define a known rule-based UI Context and tie its command state to this context. Par la suite n’importe quelle extension MEF ciblée pour le package principal peut ajouter ses termes du contrat pour les éditeurs, qu'il prend en charge sans affecter les autres conditions ou l’expression de référence.Afterwards any MEF extension targeted for the master package can add its terms for editors it supports without impacting other terms or the master expression.

Le constructeur ProvideExtensibleUIContextRuleAttribute documentation illustre la syntaxe pour les règles de contexte d’interface utilisateur extensibles.The constructor ProvideExtensibleUIContextRuleAttribute documentation shows the syntax for extensible UI Context rules.