Partilhar via

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

Um dos conceitos comuns no VisualStudio.Extensibility é o uso de regras de ativação baseadas no contexto. Essas regras regem as condições sob as quais uma extensão ou um comando é apresentado ao usuário. Um exemplo de uma regra de ativação baseada no contexto é a VisibleWhen propriedade 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 ActivationConstraint tipo criada com um dos métodos de fábrica do ActivationConstraint, como ClientContext.

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

Exemplo de definição

No exemplo a seguir, a propriedade EnabledWhen de configuração do comando define quando o comando está no estado habilitado. O ClientContext método é um dos métodos de fábrica de restrição de ativação. Ele gera a restrição de ativação, dados 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 é 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 do IDE que você pode testar; para 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.Extensibilidade, 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 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 suportadas. Cada entrada na lista é um método de fábrica do tipo ActivationConstraint.

Term Description
ClientContext(<chave>=ClientContextKey, <padrão>=<regex>) True quando a chave de contexto do cliente fornecida corresponde à expressão regular. Consulte as chaves de contexto do cliente.
ActiveProjectCapability(<expressão>=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 do projeto.
ProjectAddedItem(<padrão>=<regex>) O termo é verdadeiro quando um arquivo correspondente ao "padrão" é adicionado a um projeto na solução que é aberta.
SolutionHasProjectCapability(<expressão>=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 do projeto.
SolutionState(<estado>=SolutionState) True quando o estado da solução corresponde ao valor fornecido, consulte estados da solução para obter a lista de valores.
EditorContentType(<conteúdoTipo)> True quando o tipo de conteúdo do editor ativo é ou herda de um tipo de conteúdo específico.

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

Term Description
ActiveProjectBuildProperty(<propriedade>=<regex>) O termo é verdadeiro quando o projeto selecionado tem a propriedade de construção especificada e o valor da propriedade corresponde ao padrão regex fornecido.
ActiveProjectFlavor(<GUID>) True sempre que o projeto selecionado tiver uma variante correspondente ao GUID do tipo de projeto dado.
SolutionHasProjectBuildProperty(<propriedade>=<regex>) O termo é verdadeiro quando a solução tem um projeto carregado com a propriedade de compilação especificada e o valor da propriedade corresponde ao filtro regex fornecido.
SolutionHasProjectFlavor(<GUID>) True sempre que uma solução tem um projeto que é aromatizado (agregado) e tem um sabor correspondente ao GUID do tipo de projeto dado.
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 está carregada, se tem zero, um ou vários projetos e se está sendo construída.

As restrições de ativação que correspondem aos estados da solução podem ser combinadas da mesma forma que quaisquer outras restrições 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 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 do 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 IDE.

Conteúdo relacionado

  • Last updated on