Restricciones de activación basadas en reglas
Uno de los conceptos comunes de VisualStudio.Extensibility es el uso de reglas de activación basadas en contexto. Estas reglas 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 VisibleWhen en la 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 tipo ActivationConstraint creado con uno de los métodos de fábrica de ActivationConstraint, como ClientContext.
Se pueden combinar varias restricciones de activación mediante los métodos And, Or y 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 método ClientContext 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 selecciona 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 clase ClientContextKey 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.
El siguiente ejemplo 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 sufijo When 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 Factory Method en el tipo ActivationConstraint.
| 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 del proyecto. |
ProjectAddedItem(<pattern>=<regex>) |
El término es true cuando se agrega un archivo que coincide con el “pattern” a un proyecto de la solución que está abierto. |
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 del proyecto. |
SolutionState(<state>=SolutionState) |
Verdadero cuando el estado de la solución coincide con el valor proporcionado, consulte los estados de la solución para ver la lista de valores. |
EditorContentType(<contentType>) |
True cuando el tipo de contenido del editor activo es o hereda de un tipo de contenido específico. |
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 construcción especificada y el valor de la 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 dado. |
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 la solución presente un tipo (agregado) y tenga un tipo que coincida con el GUID de tipo de proyecto especificado. |
UIContext(<guid>) |
True cuando el contexto de interfaz de usuario especificado está activo en la instancia de Visual Studio. |
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 solución FullyLoaded y una solución SingleProject 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 del 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.