Comment : utiliser le contexte de l’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 des VSPackages lorsque certaines connue UIContexts sont activés.Visual Studio allows loading of VSPackages when certain well-known UIContexts are activated. Toutefois, les contextes d’interface utilisateur ne sont pas très fines précise, en laissant auteurs d’extensions aucun choix mais permettant de sélectionner un contexte de l’interface utilisateur disponibles qui active avant le point, ils voulaient réellement le VSPackage à charger.However, these UI Contexts are not very fine grained, leaving 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 de leur chargement plus tôt qu’ils sont requis n’est pas la meilleure pratique.Loading packages can have a performance impact and loading them sooner than they are needed is not the best practice. Visual Studio 2015 a 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 lequel un contexte de l’interface utilisateur est activé et chargé de VSPackages associé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 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 (GUID) et une expression booléenne qui fait référence à un ou plusieurs « termes » combiné avec logique « et », « ou », « not » des 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. « Termes » sont dynamiquement évaluées lors de l’exécution et l’expression est réévaluée chaque fois qu’une de ses modifications termes du contrat."Terms" are evaluated dynamically at runtime and the expression is re-evaluated 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.

Basée sur une règle de contexte de l’interface utilisateur peut être utilisé de plusieurs façons :Rule-based UI Context can be used in a variety of ways:

  1. Spécifier des contraintes de visibilité pour les commandes et les 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 de l’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. Tâche différée : retarder le chargement jusqu'à ce qu’un intervalle spécifié est écoulé et la règle est toujours respectée.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 de l’interface utilisateur basée sur la règleCreate a Rule-based UI Context

Supposons que vous disposez d’une extension appelée TestPackage, qui offre une commande de menu qui s’applique uniquement aux fichiers avec l’extension de « .config ».Suppose you have an extension called TestPackage, which offers a menu command which 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. Ceci n’est pas efficace, car la solution chargée ne contienne pas même un fichier .config.This is not efficient, since the loaded solution may not even contain a .config file. Nous voir comment basée sur les règles de contexte de l’interface utilisateur peut être utilisé pour activer un contexte d’interface utilisateur uniquement lorsqu’un fichier avec une extension .config est sélectionné et charger TestPackage lorsque ce contexte de l’interface utilisateur est activé.Let us see 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é.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". Vous ajoutez ensuite le code suivant à l’intérieur de votre classe de package :You then add the following inside your package class:

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

    Pour les attributs, ajoutez le code suivant : (les détails de ces attributs seront abordées plus loin)For the attributes, add the following: (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 porte un nom qui correspond au modèle d’expression régulière «\.config$ » (qui 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 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 au pkgdef généré pendant le moment de 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 de symboles, 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}" />  
    

    Désormais, les commandes de menu contextuel pour les fichiers *.config sera visibles uniquement lorsque l’élément sélectionné dans l’Explorateur de solutions est un fichier de « .config » et le package ne sera pas chargé tant qu’un de ces commandes est sélectionné.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, nous allons utiliser un débogueur pour confirmer que le package est chargé uniquement quand nous prévu.Next, let's use a debugger to confirm that the package loads only when we 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 un 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 fichier App.Config.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.

Ajout de plusieurs règles pour le contexte de l’interface utilisateurAdding 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 de l’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 lorsqu’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 n’apparaîtront pas si vous ouvrez un fichier de « .config » en tant que 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 du contrat, « SingleProject » et « MultipleProjects », faire référence à d’autres contextes d’interface utilisateur bien connu (par leur GUID).The first two terms, "SingleProject" and "MultipleProjects", refer to other well-known UI Contexts (by their GUIDs). Le terme, « DotConfig » est le contexte de l’interface utilisateur basée sur une règle définie précédemment.The third term, "DotConfig" is the rule-based UI Context we defined earlier.

Délai d’ActivationDelayed Activation

Les règles peuvent avoir un délai « facultatif ».Rules can have an optional "Delay". Le délai d’attente est spécifié en millisecondes.The delay is specified in milliseconds. Le cas échéant, le délai d’attente entraîne l’activation ou la désactivation du contexte de l’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 sauvegarder avant l’intervalle de délai, puis rien ne se produit.If the rule changes back before the delay interval, then nothing happens. Ce mécanisme permet de « échelonner les étapes d’initialisation - en particulier une initialisation unique sans compter sur les minuteurs ou 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 termes qui sont prises en charge :Here are the various types of term that are supported:

{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn} Le GUID fait référence à un contexte de l’interface utilisateur.The GUID refers to a UI Context. Chaque fois que le contexte de l’interface utilisateur est actif et false dans le cas contraire, le terme sera true.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> « requête » représente un chemin d’accès complet dans le magasin 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 fractionnée en « collection » et « propertyName » à la dernière barre oblique.The query is split into a "collection" and "propertyName" at the last slash.
ConfigSettingsStoreQuery :<requête >ConfigSettingsStoreQuery:<query> « requête » 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 fractionnée en « collection » et « propertyName » à la dernière barre oblique.The query is split into a "collection" and "propertyName" at the last slash.
ActiveProjectFlavor :<projectTypeGuid >ActiveProjectFlavor:<projectTypeGuid> La durée de true à chaque fois que le projet sélectionné actuellement est flavored (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 a la valeur true lorsque les fonctionnalités de projet actif correspond à l’expression fournie.The term is true when active project capabilities matches the provided expression. Une expression peut être un nom tel que VB | CSharpAn expression can be something like VB | CSharp
SolutionHasProjectCapability :<Expression >SolutionHasProjectCapability:<Expression> Similaire à ce qui précède, mais terme a la valeur true lorsque la solution a un 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 flavored (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 les extension entre les versionsCompatibility with cross-version extension

La règle en fonction des contextes de l’interface utilisateur 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. Cela crée un problème avec les extensions/packages qui ciblent plusieurs versions de Visual Studio qui doivent être chargés automatiquement dans Visual Studio 2013 et versions antérieures, mais qui peuvent tirer parti de contextes d’interface utilisateur basé sur une règle afin d’éviter d’être chargé automatiquement dans Visual Studio 2015.This creates a problem with extensions/packages that target multiple versions of Visual Studio which 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 de l’interface utilisateur extensibleExtensible UI Context Rules

Parfois, les packages ne pouvez pas utiliser les règles de contexte de l’interface utilisateur statiques.Sometimes, packages cannot use static UI Context rules. Par exemple, supposons que vous avez un package d’extensibilité de la prise en charge telles que l’état de la commande est basée sur les types de l’é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 prise en charge le type de modification en cours d’extension.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 de l’interface utilisateur statique, étant donné que 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, les contextes d’interface utilisateur basé sur une règle prend en charge une expression codé en dur « * » qui indique tous les termes ci-dessous il sera joint à 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. Cela permet le package principal définir une règle connue en fonction de contexte de l’interface utilisateur et lier son état de commande pour 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 conditions d’utilisation des é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 de documentation illustre la syntaxe pour les règles de contexte de l’interface utilisateur extensibles.The constructor ProvideExtensibleUIContextRuleAttribute documentation shows the syntax for extensible UI Context rules.