Vincoli di attivazione basati su regole

Uno dei concetti comuni di VisualStudio.Extensibility è l'uso di regole di attivazione basate sul contesto. Queste regole regolano le condizioni in base alle quali viene presentata un'estensione o un comando per l'utente. Un esempio di regola di attivazione contestuale è la proprietà VisibleWhen ↗ nella configurazione di un comando, che specifica quando il comando viene visualizzato.

Tipi di vincolo

Ogni vincolo è definito come un'istanza del tipo ActivationConstraint ↗ creata con uno dei metodi factory di ActivationConstraint, ad esempio ClientContext ↗.

È possibile combinare più vincoli di attivazione con i metodi And ↗, Or ↗ e 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 per i vincoli 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 seleziona 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'insieme delle informazioni sullo stato dell'IDE rispetto alle quali è possibile eseguire test; per la tabella dei 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)$"),

Per abilitare un comando quando un'impostazione ha un valore specifico, usare ActivationConstraint.Setting. Ad esempio, ActivationConstraint.Setting(SettingDefinitions.AutoUpdateSetting, false) abilita il comando ↗ SettingsSample quando gli aggiornamenti automatici sono disattivati. Il vincolo supporta le impostazioni booleane, di stringa, intere e decimali; vedere settings per le definizioni.

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 il suffisso When che implica che qualcosa si attiva quando vengono soddisfatte le condizioni specificate.

Metodi factory per 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 Description
ClientContext ↗ (<key>=ClientContextKey ↗ , <pattern>=<regex>) True quando la chiave di contesto client specificata corrisponde all'espressione regolare. Consultare le chiavi di contesto del client.
ActiveProjectCapability ↗(<expression>=ProjectCapability ↗) True ogni volta che la soluzione ha un progetto con funzionalità corrispondenti alla sottoespressione specificata. Un'espressione può essere simile a VB | CSharp. Per altre informazioni sulle funzionalità del progetto, vedere Panoramica dell'API query di Project.
ProjectAddedItem ↗ (<pattern>=<regex>) La condizione è vera 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 a VB | CSharp. 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.
EditorContentType ↗(<contentType>) True se il tipo di contenuto dell'editor attivo è o eredita da un tipo di contenuto specifico.
Setting(<impostazione>, <expectedValue>) True se un'impostazione booleana, stringa, integer o decimale è uguale al valore previsto.

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

Termine Description
ActiveProjectBuildProperty ↗ (<property>=<regex>) Il termine è vero quando il progetto selezionato ha la proprietà di compilazione specificata e il valore della proprietà corrisponde al pattern 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 è vero quando la soluzione ha un progetto caricato nel quale la proprietà di compilazione specificata e il valore della proprietà corrispondono al filtro regex fornito.
SolutionHasProjectFlavor ↗ (<guid>) True ogni volta che una soluzione ha un progetto con variante (aggregato) e ha una variante che corrisponde al GUID del tipo di progetto specificato.
UIContext ↗ (<guid>) True quando il contesto dell'interfaccia utente ↗ specificato è attivo nell'istanza di Visual Studio.

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 è in fase di compilazione.

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.