Compartilhar via

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

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 para o usuário. Um exemplo de uma regra de ativação baseada em contexto é a VisibleWhen propriedade na configuração de um comando que declara quando o comando fica visível.

Tipos de restrição

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

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

Definição de exemplo

No exemplo a seguir, a propriedade EnabledWhen de configuração de comando define quando o comando está no estado habilitado. O método ClientContext é um dos métodos de criação de restrições de ativação. Ele gera a restrição de ativação, considerando os dois argumentos, uma cadeia de caracteres e um padrão de expressão regular para corresponder a essa cadeia de caracteres. 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 ClientContextKey classe fornece o intervalo de informações de estado IDE que você pode testar; para obter uma tabela de valores, consulte as 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, mais sucintamente, usando o & operador:

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

Propriedades de restrição de ativação

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 o estado habilitado ou visível de um comando. Os tipos de configuração contêm propriedade do tipo ActivationConstraint, normalmente com um When sufixo que implica que algo é ativado quando as condições especificadas são atendidas.

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

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

Prazo Description
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True quando a chave de contexto do 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 funcionalidades correspondentes à subexpressão fornecida. Uma expressão pode ser algo como VB | CSharp. Para obter mais informações sobre os recursos do projeto, consulte a visão geral da API de consulta do Project.
ProjectAddedItem(<padrão>=<regex>) O termo é verdadeiro quando um arquivo que corresponde ao "padrão" é adicionado a um projeto na solução aberta.
SolutionHasProjectCapability(<expression>=ProjectCapability) True sempre que a solução tiver um projeto com funcionalidades correspondentes à subexpressão fornecida. Uma expressão pode ser algo como VB | CSharp. Para obter mais informações sobre os recursos do projeto, consulte a visão geral da API de consulta do Project.
SolutionState(<state>=SolutionState) True quando o estado da solução corresponder ao valor fornecido, consulte os 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 motivos de compatibilidade, também há suporte para as seguintes restrições de ativação herdadas:

Prazo Description
ActiveProjectBuildProperty(<property>=<regex>) O termo é verdadeiro quando o projeto selecionado tem a propriedade "build" especificada e o valor da propriedade corresponde ao padrão regex fornecido.
ActiveProjectFlavor(<GUID>) Verdadeiro sempre que o projeto selecionado tiver uma variante que corresponda ao GUID do tipo de projeto fornecido.
SolutionHasProjectBuildProperty(<property>=<regex>) O termo é verdadeiro quando a solução tem um projeto carregado com a propriedade de build especificada e o valor da propriedade corresponde ao filtro regex fornecido.
SolutionHasProjectFlavor(<GUID>) True sempre que uma solução tiver um projeto personalizado (ou agregado) e possuir uma variação que corresponda ao GUID do tipo de projeto fornecido.
UIContext(<GUID>) True quando o UI Context especificado estiver ativo na instância do Visual Studio.

Estados do sistema de solução

O estado da solução refere-se ao estado da solução e seus projetos, se uma solução está carregada, se ela possui zero, um ou vários projetos, e se está em processo de compilação.

As restrições de ativação que correspondem aos estados da solução podem ser combinadas da mesma forma que qualquer outra restrição de ativação. Por exemplo, você pode combinar uma restrição de ativação que especifica uma FullyLoaded solução e uma SingleProject solução para identificar soluções de projeto único quando estão completamente carregadas.

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

Chaves de contexto do cliente

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

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

Conteúdo relacionado

  • Last updated on