Partager via

Contraintes d’activation basées sur des règles

  • Article

L’un des concepts fréquents de VisualStudio.Extensibility est l’utilisation de règles d’activation basées sur le contexte. Ces règles régissent les conditions dans lesquelles une extension ou une commande est présentée à l’utilisateur. Un exemple de règle d’activation basée sur le contexte est la propriété VisibleWhen dans la configuration d’une commande qui déclare lorsque la commande est rendue visible.

Types de contrainte

Chaque contrainte est définie comme une instance du type ActivationConstraint créé avec l’une des méthodes de fabrique de ActivationConstraint, comme ClientContext.

Plusieurs contraintes d’activation peuvent être combinées à l’aide des méthodes And, Or, et Not. Vous pouvez aussi combiner des contraintes d’activation à l’aide d’opérateurs &, |et !.

Exemple de définition

Dans l’exemple suivant, la propriété de configuration de commande EnabledWhen définit quand la commande est dans l’état activé. La méthode ClientContext est l’une des méthodes de fabrique de contraintes d’activation. Elle produit la contrainte d’activation, en fonction des deux arguments, d’une chaîne et d’un modèle d’expression régulière à mettre en correspondance avec cette chaîne. Par conséquent, le code suivant indique qu’une commande est activée lorsque l’utilisateur sélectionne un fichier avec l’une de ces extensions.

public override CommandConfiguration CommandConfiguration => new("%My command.DisplayName%")
{
    EnabledWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

La classe ClientContextKey fournit la plage d’informations d’état IDE que vous pouvez tester par rapport à une table de valeurs, consultez les clés de contexte client.

L’exemple suivant montre comment combiner plusieurs contraintes :

EnabledWhen = ActivationConstraint.And(
    ActivationConstraint.SolutionState(SolutionState.Exists),
    ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorFileName, @"\.(jpg|jpeg|txt)$")),

ou, plus succinctement, à l’aide de l’opérateur & :

EnabledWhen =
    ActivationConstraint.SolutionState(SolutionState.Exists) &
    ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorFileName, @"\.(jpg|jpeg|txt)$")),

Propriétés de la contrainte d’activation

Les contraintes d’activation peuvent être utilisées pour configurer une variété de fonctionnalités VisualStudio.Extensibility, notamment le chargement d’une extension et l’état activé ou visible d’une commande. Les types de configuration contiennent la propriété de type ActivationConstraint, généralement avec un When suffixe qui suppose que quelque chose s’active lorsque les conditions spécifiées sont satisfaites.

Méthodes de fabrique de contraintes d’activation

Cette section présente la liste des contraintes d’activation prises en charge actuellement. Chaque entrée de la liste est une méthode de fabrique sur le type ActivationConstraint.

Terme Description
ClientContext(<clé>=ClientContextKey, <modèle>=<regex>) Vrai lorsque la clé de contexte client fournie correspond à l’expression régulière. Consultez les clés de contexte client.
ActiveProjectCapability(<expression>=ProjectCapability) Vrai chaque fois que la solution a un projet avec des fonctionnalités correspondant à la sous-expression fournie. Une expression peut être par exemple VB | CSharp. Pour plus d’informations sur les fonctionnalités du projet, consultez vue d’ensemble de l’API de requête de projet.
ProjectAddedItem(<modèle>=<regex>) Le terme sera vrai lorsqu'un fichier correspondant au « modèle » est ajouté à un projet dans la solution ouverte.
SolutionHasProjectCapability(<expression>=ProjectCapability) Vrai chaque fois que la solution a un projet avec des fonctionnalités correspondant à la sous-expression fournie. Une expression peut être par exemple VB | CSharp. Pour plus d’informations sur les fonctionnalités du projet, consultez vue d’ensemble de l’API de requête de projet.
SolutionState(<état>=SolutionState) Vrai lorsque l’état de la solution correspond à la valeur fournie, consultez les états de solution pour obtenir la liste des valeurs.
EditorContentType(<contentType>) Vrai lorsque le type de contenu du rédacteur actif est ou hérite d’un type de contenu spécifique.

Pour des raisons de compatibilité, les contraintes d’activation héritées suivantes sont également prises en charge :

Terme Description
ActiveProjectBuildProperty(<propriété>=<regex>) Le terme sera vrai si le projet sélectionné a la propriété de version spécifiée et que la valeur de propriété correspond au modèle regex fourni.
ActiveProjectFlavor(<guid>) Vrai chaque fois que le projet sélectionné est aromatisé a une saveur correspondant au GUID de type de projet donné.
SolutionHasProjectBuildProperty(<propriété>=<regex>) Le terme sera vrai si la solution a un projet chargé avec la propriété de version spécifiée et que la valeur de propriété correspond au filtre regex fourni.
SolutionHasProjectFlavor(<guid>) Vai chaque fois qu’une solution a un projet qui est aromatisé (agrégé) et a une saveur correspondant au GUID de type de projet donné.
UIContext(<guid>) Vrai lorsque le contexte d’IU spécifié est actif dans l’instance de Visual Studio.

États de la solution

L’état de la solution renvoie à l’état de la solution et à ses projets, qu’une solution soit chargée, qu’elle ait zéro, un ou plusieurs projets et qu’elle soit en cours de génération.

Les contraintes d’activation correspondant aux états de solution peuvent être combinées de la même façon que toutes les autres contraintes d’activation. À titre d’exemple, vous pouvez combiner une contrainte d’activation qui spécifie une FullyLoaded solution et une SingleProject solution pour capturer des solutions à projet unique lorsqu’elles sont entièrement chargées.

this.EnabledWhen = ActivationConstraint.And(
    ActivationConstraint.SolutionState(SolutionState.SingleProject),
    ActivationConstraint.SolutionState(SolutionState.FullyLoaded));

Clés des contextes clients

Les règles d’activation peuvent aussi utiliser le contenu du contexte client dans les parties de son expression.

Actuellement, le contexte client est limité à un petit ensemble de valeurs dans l’état de l’IDE.

Contenu connexe