Vincoli di attivazione basati su regole

  • Articolo

Uno dei concetti comuni in VisualStudio.Extensibility è l'uso di regole di attivazione basate sul contesto. Si tratta di regole che regolano le condizioni in base alle quali viene visualizzata un'estensione o un comando all'utente. Un esempio di regola di attivazione basata sul contesto è la VisibleWhen proprietà nella configurazione di un comando che dichiara quando il comando viene reso visibile.

Tipi di vincolo

Ogni vincolo viene definito come un'istanza del ActivationConstraint tipo creato con uno dei ActivationConstraintmetodi factory di , ad esempio ClientContext.

È possibile combinare più vincoli di attivazione usando i Andmetodi , Ore Not . È anche possibile combinare vincoli di attivazione usando operatori &, |e !.

Definizione di esempio

Nell'esempio seguente la proprietà EnabledWhen di configurazione del comando definisce quando il comando si trova nello stato abilitato. Il ClientContext metodo è uno dei metodi factory del vincolo di attivazione. Genera il vincolo di attivazione, dato i due argomenti, una stringa e un criterio di espressione regolare per la corrispondenza con tale stringa. Di conseguenza, il codice seguente indica che un comando è abilitato quando l'utente ha selezionato un file con una di queste estensioni.

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

La ClientContextKey classe fornisce l'intervallo di informazioni sullo stato dell'IDE che è possibile testare. Per una tabella di valori, vedere Chiavi di contesto client.

L'esempio seguente illustra come combinare più vincoli:

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

o, più concisamente, usando l'operatore & :

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

Proprietà del vincolo di attivazione

I vincoli di attivazione possono essere usati per configurare un'ampia gamma di funzionalità di VisualStudio.Extensibility, tra cui il caricamento di un'estensione e lo stato abilitato o visibile di un comando. I tipi di configurazione contengono proprietà di tipo ActivationConstraint, in genere con un When suffisso che implica l'attivazione di un elemento quando vengono soddisfatte le condizioni specificate.

Metodi factory vincoli di attivazione

Questa sezione mostra l'elenco dei vincoli di attivazione attualmente supportati. Ogni voce nell'elenco è un metodo factory sul ActivationConstraint tipo .

Termine Descrizione
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True quando la chiave di contesto client specificata corrisponde all'espressione regolare. Vedere chiavi di contesto client.
ActiveProjectCapability(<expression>=ProjectCapability) True ogni volta che la soluzione ha un progetto con funzionalità corrispondenti alla sottoespressione specificata. Un'espressione può essere simile VB | CSharpa . Per altre informazioni sulle funzionalità del progetto, vedere Panoramica dell'API query di Project.
ProjectAddedItem(<pattern>=<regex>) Il termine è true quando un file corrispondente al "pattern" viene aggiunto a un progetto nella soluzione aperta.
SolutionHasProjectCapability(<expression>=ProjectCapability) True ogni volta che la soluzione ha un progetto con funzionalità corrispondenti alla sottoespressione specificata. Un'espressione può essere simile VB | CSharpa . Per altre informazioni sulle funzionalità del progetto, vedere Panoramica dell'API query di Project.
SolutionState(<state>=SolutionState) True quando lo stato della soluzione corrisponde al valore specificato, vedere stati della soluzione per l'elenco di valori.

Per motivi di compatibilità, sono supportati anche i vincoli di attivazione legacy seguenti:

Termine Descrizione
ActiveProjectBuildProperty(<property>=<regex>) Il termine è true quando il progetto selezionato ha la proprietà di compilazione specificata e il valore della proprietà corrisponde al modello regex specificato.
ActiveProjectFlavor(<guid>) True ogni volta che il progetto selezionato ha un sapore corrispondente al GUID del tipo di progetto specificato.
SolutionHasProjectBuildProperty(<property>=<regex>) Il termine è true quando la soluzione ha un progetto caricato con la proprietà di compilazione e il valore della proprietà specificati corrisponde al filtro regex fornito.
SolutionHasProjectFlavor(<guid>) True ogni volta che una soluzione ha un progetto con sapore (aggregato) e ha un sapore corrispondente al GUID del tipo di progetto specificato.

Stati della soluzione

Lo stato della soluzione si riferisce allo stato della soluzione e ai relativi progetti, indipendentemente dal fatto che una soluzione venga caricata, indipendentemente dal fatto che abbia zero, uno o più progetti e se si sta compilando.

I vincoli di attivazione che corrispondono agli stati della soluzione possono essere combinati nello stesso modo di qualsiasi altro vincolo di attivazione. Ad esempio, è possibile combinare un vincolo di attivazione che specifica una FullyLoaded soluzione e una SingleProject soluzione per acquisire soluzioni a progetto singolo quando vengono caricate completamente.

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

Chiavi di contesto client

Le regole di attivazione possono anche usare il contenuto del contesto client come parti dell'espressione.

Attualmente, il contesto client è limitato a un piccolo set di valori nello stato IDE.

Contenuto correlato