Restricciones de activación basadas en reglas

  • Artículo

Uno de los conceptos comunes de VisualStudio.Extensibility es el uso de reglas de activación basadas en contexto. Estas son reglas que rigen las condiciones en las que se muestra una extensión o un comando al usuario. Un ejemplo de una regla de activación basada en contexto es la propiedad en la VisibleWhen configuración de un comando que declara cuándo se hace visible el comando.

Tipos de restricción:

Cada restricción se define como una instancia del ActivationConstraint tipo creado con uno de los ActivationConstraintmétodos de fábrica de , como ClientContext.

Se pueden combinar varias restricciones de activación mediante los Andmétodos , Ory Not . También puede combinar restricciones de activación mediante operadores &, |y !.

Definición de ejemplo

En el ejemplo siguiente, la propiedad EnabledWhen de configuración del comando define cuándo el comando está en estado habilitado. El ClientContext método es uno de los métodos del generador de restricciones de activación. Genera la restricción de activación, dados los dos argumentos, un patrón de cadena y expresión regular para que coincida con esa cadena. Por lo tanto, el código siguiente indica que un comando está habilitado cuando el usuario ha seleccionado un archivo con una de esas extensiones.

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

La ClientContextKey clase proporciona el intervalo de información de estado del IDE con la que puede probar; para obtener una tabla de valores, consulte Claves de contexto de cliente.

En el ejemplo siguiente se muestra cómo combinar varias restricciones:

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

o, más concisamente, mediante el & operador :

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

Propiedades de restricción de activación

Las restricciones de activación se pueden usar para configurar una variedad de funcionalidades de extensibilidad de VisualStudio.Extensibility, incluida la carga de una extensión, y el estado habilitado o visible de un comando. Los tipos de configuración contienen la propiedad de tipo ActivationConstraint, normalmente con un When sufijo que implica que algo se activa cuando se cumplen las condiciones especificadas.

Métodos de factoría de restricciones de activación

En esta sección se muestra la lista de restricciones de activación admitidas actualmente. Cada entrada de la lista es un método factory en el ActivationConstraint tipo .

Término Descripción
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True cuando la clave de contexto de cliente proporcionada coincide con la expresión regular. Consulte claves de contexto de cliente.
ActiveProjectCapability(<expression>=ProjectCapability) True siempre que la solución tenga un proyecto con funcionalidades que coincidan con la subexpresión proporcionada. Una expresión puede ser algo parecido a VB | CSharp. Para más información sobre las funcionalidades del proyecto, consulte Introducción a la API de consulta de Project.
ProjectAddedItem(<pattern>=<regex>) El término es true cuando se agrega un archivo que coincide con el "patrón" a un proyecto de la solución que se abre.
SolutionHasProjectCapability(<expression>=ProjectCapability) True siempre que la solución tenga un proyecto con funcionalidades que coincidan con la subexpresión proporcionada. Una expresión puede ser algo parecido a VB | CSharp. Para más información sobre las funcionalidades del proyecto, consulte Introducción a la API de consulta de Project.
SolutionState(<state>=SolutionState) True cuando el estado de la solución coincide con el valor proporcionado, consulte Los estados de la solución para obtener una lista de valores.

Por motivos de compatibilidad, también se admiten las siguientes restricciones de activación heredadas:

Término Descripción
ActiveProjectBuildProperty(<property>=<regex>) El término es true cuando el proyecto seleccionado tiene la propiedad de compilación especificada y el valor de propiedad coincide con el patrón regex proporcionado.
ActiveProjectFlavor(<guid>) True siempre que el proyecto seleccionado tenga un sabor que coincida con el GUID de tipo de proyecto especificado.
SolutionHasProjectBuildProperty(<property>=<regex>) El término es true cuando la solución tiene un proyecto cargado con la propiedad de compilación y el valor de propiedad especificados coincide con el filtro regex proporcionado.
SolutionHasProjectFlavor(<guid>) True siempre que una solución tenga un proyecto con sabor (agregado) y tenga un sabor que coincida con el GUID de tipo de proyecto especificado.

Estados de la solución

El estado de la solución hace referencia al estado de la solución y sus proyectos, tanto si se carga una solución como si tiene cero, uno o varios proyectos, y si está compilando.

Las restricciones de activación que corresponden a los estados de la solución se pueden combinar de la misma manera que cualquier otra restricción de activación. Por ejemplo, puede combinar una restricción de activación que especifique una FullyLoaded solución y una SingleProject solución para capturar soluciones de un solo proyecto cuando se carguen por completo.

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

Claves de contexto de cliente

Las reglas de activación también pueden usar el contenido del contexto de cliente como partes de su expresión.

Actualmente, el contexto de cliente se limita a un pequeño conjunto de valores en estado IDE.

Contenido relacionado