Compartilhar via

Restrições de ativação baseadas em regra

  • Artigo

Um dos conceitos comuns no VisualStudio.Extensibility é o uso de regras de ativação baseadas em contexto. Essas regras regem as condições sob as quais uma extensão ou um comando é exibido ao usuário. Um exemplo de uma regra de ativação baseada em contexto é a propriedade VisibleWhen na configuração de um comando que declara quando o comando é tornado visível.

Tipos de restrição

Cada restrição é definida como uma instância do tipo ActivationConstraint criado com um dos métodos de fábrica do ActivationConstraint, como ClientContext.

Várias restrições de ativação podem ser combinadas juntas usando os métodos And, Or e Not. Você também pode combinar restrições de ativação usando os operadores &, | e !.

Definição de exemplo

No exemplo a seguir, a propriedade de configuração de comandos EnabledWhen define quando o comando está no estado habilitado. O método ClientContext é um dos métodos de fábrica de restrição de ativação. Ele gera a restrição de ativação, considerando os dois argumentos, uma sequência e um padrão de expressão regular para corresponder a essa sequência. Portanto, o código a seguir indica que um comando está habilitado quando o usuário seleciona um arquivo com uma dessas extensões.

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

A classe ClientContextKey fornece o intervalo de informações de estado do IDE que você pode testar; para obter uma tabela de valores, consulte Chaves de contexto do cliente.

O exemplo a seguir mostra como combinar várias restrições:

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

ou, de forma mais sucinta, utilizando o operador:&

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

Propriedades de restrição de ativação

As restrições de ativação podem ser usadas para configurar uma variedade de funcionalidades do VisualStudio.Extensibility, incluindo o carregamento de uma extensão e estado habilitado ou visível de um comando. Os tipos de configuração contêm propriedade do tipo ActivationConstraint, normalmente com um sufixo When que implica que algo é ativado quando as condições especificadas são satisfeitas.

Métodos de fábrica de restrição de ativação

Esta seção mostra a lista de restrições de ativação atualmente com suporte. Cada entrada na lista é um método de fábrica no tipo ActivationConstraint.

Termo Descrição
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True quando a chave de contexto de cliente fornecida corresponde à expressão regular. Consulte as chaves de contexto do cliente.
ActiveProjectCapability(<expression>=ProjectCapability) True sempre que a solução tiver um projeto com recursos correspondentes à subexpressão fornecida. Uma expressão pode ser algo como VB | CSharp. Para obter mais informações sobre os recursos do projeto, consulte Visão geral da API de Consulta de Projetos.
ProjectAddedItem(<pattern>=<regex>) O termo será true quando um arquivo correspondente ao "padrão" for adicionado a um projeto na solução que foi aberta.
SolutionHasProjectCapability(<expression>=ProjectCapability) True sempre que a solução tiver um projeto com recursos correspondentes à subexpressão fornecida. Uma expressão pode ser algo como VB | CSharp. Para obter mais informações sobre os recursos do projeto, consulte Visão geral da API de Consulta de Projetos.
SolutionState(<state>=SolutionState) True quando o estado da solução corresponde ao valor fornecido, consulte estados da solução para obter a lista de valores.
EditorContentType(<contentType>) True quando o tipo de conteúdo do editor ativo é ou herda de um tipo de conteúdo específico.

Por questões de compatibilidade, as seguintes restrições de ativação herdadas também são aceitas:

Termo Descrição
ActiveProjectBuildProperty(<property>=<regex>) O termo será true quando o projeto selecionado tiver um uma propriedade de compilação especificada e o valor da propriedade corresponder ao padrão de regex fornecido.
ActiveProjectFlavor(<guid>) True sempre que o projeto selecionado tiver uma variante correspondente ao GUID do tipo de projeto fornecido.
SolutionHasProjectBuildProperty(<property>=<regex>) O termo será true quando a solução tiver um projeto carregado com a propriedade de compilação especificada e o valor da propriedade corresponde ao filtro regex fornecido.
SolutionHasProjectFlavor(<guid>) Sempre que uma solução tiver um projeto com uma variante (agregado) e tiver uma variante correspondente ao GUID do tipo de projeto fornecido.
UIContext(<guid>) True quando o Contexto da interface do usuário especificado está ativo na instância do Visual Studio.

Estados da solução

O estado da solução refere-se ao estado da solução e seus projetos, se uma solução é carregada, se tem zero, um ou vários projetos e se está sendo compilada.

As restrições de ativação que correspondem aos estados da solução podem ser combinadas da mesma maneira que quaisquer outras restrições de ativação. Por exemplo, você pode combinar uma restrição de ativação que especifica uma solução FullyLoaded e uma solução SingleProject para capturar soluções de projeto único quando elas estiverem totalmente carregadas.

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

Chaves de contexto de cliente

As regras de ativação também podem utilizar o conteúdo do contexto do cliente como partes de sua expressão.

Atualmente, o contexto do cliente é limitado a um pequeno conjunto de valores no estado do IDE.

Conteúdo relacionado