Configuración personalizada y opciones en extensiones de Visual Studio

2025-06-12

Almacenar y recuperar la configuración es un elemento necesario para muchas extensiones. Vamos a explorar cómo trabajar con la configuración teniendo en cuenta estos objetivos:

Una manera sencilla de proporcionar opciones personalizadas.
Exponga las opciones en el cuadro de diálogo Opciones de herramientas>.
Forma segura de subprocesos para acceder a la configuración y modificarla.
Compatibilidad sincrónica y asincrónica.
No es necesario cargar el paquete para que la configuración se inicialice.

En el vídeo siguiente se muestra ho para agregar opciones a una extensión.

Este es el aspecto que debería tener en el cuadro de diálogo Opciones de herramientas>.

Página Agregar una opción

Haga clic con el botón derecho en el proyecto y seleccione Agregar > nuevo elemento... para mostrar las plantillas disponibles. A continuación, seleccione la categoría Extensibilidad en el lado izquierdo y, a continuación, la plantilla Página opciones (Comunidad). En el campo nombre siguiente, escriba General.

Adding an options page from the Add New Item dialog.

Esto creará /Options/General.cs en la raíz del proyecto.

The Options Page C# file added to the project.

Este es el contenido del archivo General.cs:

internal partial class OptionsProvider
{
    // Register the options with these attributes on your package class:
    // [ProvideOptionPage(typeof(OptionsProvider.GeneralOptions), "MyExtension", "General", 0, 0, true)]
    // [ProvideProfile(typeof(OptionsProvider.GeneralOptions), "MyExtension", "General", 0, 0, true)]
    public class GeneralOptions : BaseOptionPage<General> { }
}

public class General : BaseOptionModel<General>
{
    [Category("My category")]
    [DisplayName("My Option")]
    [Description("An informative description.")]
    [DefaultValue(true)]
    public bool MyOption { get; set; } = true;
}

Es breve y sencillo y veremos los detalles. Pero en primer lugar, debemos registrar la página Opciones.

Registrar la página Opciones

En un comentario de código del archivo General.cs se indican cómo registrar la página Opciones.

Todo lo que tenemos que hacer es copiar esos dos atributos en nuestra clase Package. Esto podría tener un aspecto similar al siguiente:

[ProvideOptionPage(typeof(OptionsProvider.GeneralOptions), "MyExtension", "General", 0, 0, true)]
[ProvideProfile(typeof(OptionsProvider.GeneralOptions), "MyExtension", "General", 0, 0, true)]
public sealed class OptionsPackage : ToolkitPackage
{
    ...
}

Al ejecutar la extensión, ahora deberíamos ver la página de opciones MyExtension/General que aparece en el cuadro de diálogo Opciones de herramientas>.

Custom options page registered.

Los dos atributos son muy similares, pero controla diferentes escenarios.

El ProvideOptionsPage atributo es lo que hace que la página Opciones aparezca en el cuadro de diálogo Opciones de herramientas>. Puede omitir este atributo si no desea que la página de opciones sea visible para los usuarios.

ProvideProfile registra las opciones en el perfil de itinerancia, lo que significa que la configuración individual se desplazará con la cuenta del usuario entre instancias e instalaciones de Visual Studio. También habilita la característica de configuración de importación y exportación de Visual Studio. Este atributo es opcional.

Las opciones individuales

En el archivo General.cs, puede ver cómo las opciones individuales no son más que propiedades simples de C# decoradas con atributos.

    [Category("My category")]
    [DisplayName("My Option")]
    [Description("An informative description.")]
    [DefaultValue(true)]
    public bool MyOption { get; set; } = true;

Todos los tipos de datos simples como string, bool, int, se admiten de forma predeterminada y que abarcan la mayoría de los casos de uso. Para otros tipos de datos, debemos usar convertidores de tipos. Algunos están integrados en Visual Studio, como .EnumConverter

Tenga en cuenta esta enumeración:

public enum Numbers
{
    First,
    Second,
    Third,
}

Podemos exponer esos valores como opciones en una lista desplegable declarando lo TypeConverter siguiente:

[Category("My category")]
[DisplayName("My Enum")]
[Description("Select the value you want from the list.")]
[DefaultValue(Numbers.First)]
[TypeConverter(typeof(EnumConverter))]
public Numbers MyEnum { get; set; } = Numbers.First;

Dropdown with enum values on the options page.

Opciones de lectura y escritura

Ahora que ha registrado las opciones para permitir que los usuarios cambien sus valores, es el momento de leer esos valores para usarlos en nuestra extensión.

Puede trabajar con la configuración desde contextos sincrónicos y asincrónicos. Comencemos con el sincrónico:

// read settings
var number = General.Instance.MyEnum;

// write settings
General.Instance.MyEnum = Numbers.Second;
General.Instance.Save();

La API para leer y escribir en la configuración es muy sencilla y sencilla.

Al trabajar en un contexto asincrónico, la API tiene un aspecto muy similar.

// read settings
var general = await General.GetLiveInstanceAsync();
var number = general.MyEnum;

// write settings
general.MyEnum = Numbers.Second;
await general.SaveAsync();

Eventos

Cuando se guarda la configuración, se desencadena el evento General.Saved estático. Puede suscribirse a ese evento como cualquier otro evento en .NET y tiene este aspecto:

General.Saved += OnSettingsSaved;

...

private void OnSettingsSaved(object sender, General e)
{
   
}

Obtención del código fuente

Puede encontrar el código fuente de esta extensión en el repositorio de ejemplos.

Lea los documentos para obtener todos los detalles que rodean estos escenarios, pero tenga en cuenta que, aunque proporcionan documentación más detallada, no siguen los procedimientos recomendados descritos en este ejemplo. Tampoco usan el Kit de herramientas de la comunidad que hace que trabajar con la configuración sea mucho más fácil.

Compartir a través de