Impostazioni e opzioni

Definire le impostazioni configurabili che gli utenti possono modificare per influire sul comportamento dell'estensione. Le impostazioni si integrano automaticamente con l'esperienza Impostazioni unificate di Visual Studio.

Note

Questa guida usa l'SDK VisualStudio.Extensibility. Vedi Scegliere il modello di estendibilità corretto per il confronto dei modelli.

Esempio completo

Registrazione completa delle impostazioni:

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

namespace SettingsSample;

using Microsoft.VisualStudio.Extensibility;
using Microsoft.VisualStudio.Extensibility.Settings;

internal static class SettingDefinitions
{
    [VisualStudioContribution]
    internal static SettingCategory SettingsSampleCategory { get; } = new("settingsSample", "%SettingsSample.Settings.Category.DisplayName%")
    {
        Description = "%SettingsSample.Settings.Category.Description%",
        GenerateObserverClass = true,
        Actions =
        [
            new("%SettingsSample.Settings.Category.OpenToolWindow%")
            {
                Execute = (setting, context, cancellationToken) =>
                    context.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken),
            },
        ],
        Preview = new()
        {
            Factory = SettingPreviewFactory.Create(SettingsPreviewControl.CreateAsync),
        },
    };

    [VisualStudioContribution]
    internal static Setting.Boolean AutoUpdateSetting { get; } = new("autoUpdate", "%SettingsSample.Settings.AutoUpdate.DisplayName%", SettingsSampleCategory, defaultValue: true)
    {
        Description = "%SettingsSample.Settings.AutoUpdate.Description%",
    };

    [VisualStudioContribution]
    internal static Setting.Integer TextLengthSetting { get; } = new("textLength", "%SettingsSample.Settings.TextLength.DisplayName%", SettingsSampleCategory, defaultValue: 10)
    {
        Description = "%SettingsSample.Settings.TextLength.Description%",
        Minimum = 1,
        Maximum = MyToolWindowData.LoremIpsumText.Length,
    };

    [VisualStudioContribution]
    internal static Setting.Enum QuoteStyleSetting { get; } = new(
        "quoteStyle",
        "%SettingsSample.Settings.QuoteStyle.DisplayName%",
        SettingsSampleCategory,
        [new EnumSettingEntry("none", "%SettingsSample.Settings.QuoteStyle.None%"), new EnumSettingEntry("single", "%SettingsSample.Settings.QuoteStyle.Single%"), new EnumSettingEntry("double", "%SettingsSample.Settings.QuoteStyle.Double%")],
        defaultValue: "double")
    {
        Description = "%SettingsSample.Settings.QuoteStyle.Description%",
    };

    [VisualStudioContribution]
    internal static Setting.StringArray SampleWordsSetting { get; } = new(
        "sampleWords",
        "%SettingsSample.Settings.SampleWords.DisplayName%",
        SettingsSampleCategory,
        ["Lorem", "ipsum"])
    {
        Description = "%SettingsSample.Settings.SampleWords.Description%",
        UniqueItems = true,
        AllowAdditions = true,
        AllowRemovals = true,
    };
}

Tip

Consulta l'esempio completo e funzionante: SettingsSample ↗

Concetti correlati:Contributi e configurazioni : modalità di registrazione delle impostazioni come contributi

Capire l’esempio

Definire un'impostazione

internal static class SettingDefinitions
{
    [VisualStudioContribution]
    internal static SettingCategory MyCategory { get; } = new("myCategory", "My Extension")
    {
        GenerateObserverClass = true,
    };

    [VisualStudioContribution]
    internal static Setting.Boolean EnableFeature { get; } = new(
        "enableFeature", "Enable feature", MyCategory, defaultValue: true);

    [VisualStudioContribution]
    internal static Setting.String OutputFormat { get; } = new(
        "outputFormat", "Output format", MyCategory, defaultValue: "json")
    {
        MaxStringLength = 50,
    };
}

Leggi un valore di un'impostazione

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
    var result = await Extensibility.Settings()
        .ReadEffectiveValueAsync(SettingDefinitions.EnableFeature, ct);
    if (!result.Succeeded)
    {
        throw new InvalidOperationException("Could not read EnableFeature.", result.Error);
    }

    bool isEnabled = result.Value;
}

ReadEffectiveValueAsync restituisce il valore configurato o l'impostazione predefinita dichiarata se non è stato assegnato alcun valore. Un guasto di lettura è diverso: descritto in result.Error. ValueOrDefault(fallback) restituisce il fallback in caso di errore di lettura, quindi usarlo solo quando tale fallback è intenzionale; controllare Succeeded o usare Value quando il fallimento deve essere segnalato.

Monitorare le impostazioni con un observer

Impostare GenerateObserverClass = true sulla categoria, quindi registrare e iniettare l'osservatore:

// In your Extension class:
protected override void InitializeServices(IServiceCollection serviceCollection)
{
    serviceCollection.AddSettingsObservers();
    base.InitializeServices(serviceCollection);
}

// In a command:
private readonly Settings.MyCategoryObserver settingsObserver;

public MyCommand(Settings.MyCategoryObserver settingsObserver)
{
    this.settingsObserver = settingsObserver;
    this.settingsObserver.Changed += this.OnSettingsChangedAsync;
}

private Task OnSettingsChangedAsync(Settings.MyCategorySnapshot snapshot)
{
    if (!snapshot.EnableFeature.Succeeded)
    {
        System.Diagnostics.Trace.TraceError("Could not read EnableFeature: {0}", snapshot.EnableFeature.Error);
        return Task.CompletedTask;
    }

    bool isEnabled = snapshot.EnableFeature.ValueOrDefault(defaultValue: true);
    // React to change
    return Task.CompletedTask;
}

protected override void Dispose(bool isDisposing)
{
    if (isDisposing)
    {
        this.settingsObserver.Changed -= this.OnSettingsChangedAsync;
    }

    base.Dispose(isDisposing);
}

L'osservatore generato si trova nel namespace figlio Settings. Il Changed gestore viene eseguito almeno una volta con lo snapshot corrente, quindi non è necessaria una lettura iniziale separata. Annullare la sottoscrizione quando il componente consumer viene distrutto; usare GetSnapshotAsync(cancellationToken) se è necessario solo uno snapshot monouso.

Scrivi impostazioni

var writeResult = await Extensibility.Settings().WriteAsync(
    batch =>
    {
        batch.WriteSetting(SettingDefinitions.EnableFeature, value: false);
        batch.WriteSetting(SettingDefinitions.OutputFormat, value: "xml");
    },
    description: "Updated extension settings",
    cancellationToken);

if (writeResult.Result != SettingsWriteResponse.ResultCode.Success)
{
    throw new InvalidOperationException($"Settings were not applied: {writeResult.Result}");
}

PendingApproval indica che la scrittura dei dati non è stata ancora applicata; ChangeError indica che una o più modifiche non sono riuscite. Verificare ChangeResults per errori per impostazione e localizzare la descrizione di scrittura mostrata agli utenti.

Iscriviti a una singola configurazione (senza osservatore)

Per i casi in cui non è necessaria una classe osservatore completa, sottoscrivere direttamente:

IDisposable subscription = await Extensibility.Settings().SubscribeAsync(
    SettingDefinitions.EnableFeature,
    cancellationToken,
    changeHandler: result =>
    {
        if (!result.Succeeded)
        {
            System.Diagnostics.Trace.TraceError("Could not read EnableFeature: {0}", result.Error);
            return;
        }

        bool isEnabled = result.Value;
        // React to the change
    });

Il SubscribeAsync gestore viene attivato almeno una volta con il valore corrente. Mantenere l'oggetto restituito IDisposable finché sono necessari gli aggiornamenti e smaltirlo quando il componente proprietario viene eliminato.

Leggere più impostazioni contemporaneamente

var results = await Extensibility.Settings().ReadEffectiveValuesAsync(
    [SettingDefinitions.EnableFeature, SettingDefinitions.OutputFormat],
    cancellationToken);
bool isEnabled = results.Value(SettingDefinitions.EnableFeature);

Value(setting) genera un'eccezione se non è stato possibile leggere tale impostazione; results.Succeeded indica se tutte le impostazioni richieste sono state lette correttamente.

Tipi di impostazioni comuni

Type Usare per
Setting.Boolean Interruttori on/off
Setting.String Valori di testo libero
Setting.Integer Valori numerici
Setting.Decimal Valori a virgola mobile
Setting.Enum Selezione dell'elenco a discesa da opzioni fisse
Setting.FormattedString Date, URI, messaggi di posta elettronica, percorsi di file
Setting.StringArray Elenco di stringhe
Setting.ObjectArray Elementi strutturati complessi

Ad esempio, SettingsSample ↗ consente agli utenti di modificare un elenco di parole di esempio:

[VisualStudioContribution]
internal static Setting.StringArray SampleWords { get; } = new(
    "sampleWords", "Sample words", MyCategory, ["Lorem", "ipsum"])
{
    UniqueItems = true,
    AllowAdditions = true,
    AllowRemovals = true,
};

Per un percorso di file, usare una stringa formattata e la SettingStringFormat.Path factory:

[VisualStudioContribution]
internal static Setting.FormattedString LogFile { get; } = new(
    "logFile", "Log file", MyCategory,
    SettingStringFormat.Path(SettingPathKind.File),
    defaultValue: "");

Queste definizioni appartengono all'interno di SettingDefinitions accanto a MyCategory. Altri formati includono SettingStringFormat.Email() e SettingStringFormat.Uri().

Aggiungere un'azione e un'anteprima in tempo reale a una categoria

La categoria ↗ SettingsSample offre un'azione Apri la finestra degli strumenti Testo di esempio.

La stessa categoria offre un'anteprima in tempo reale del testo di esempio:

[VisualStudioContribution]
internal static SettingCategory SettingsSampleCategory { get; } = new(
    "settingsSample", "%SettingsSample.Settings.Category.DisplayName%")
{
    GenerateObserverClass = true,
    Actions =
    [
        new("%SettingsSample.Settings.Category.OpenToolWindow%")
        {
            Execute = (setting, context, cancellationToken) =>
                context.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(
                    activate: true, cancellationToken),
        },
    ],
    Preview = new()
    {
        Factory = SettingPreviewFactory.Create(SettingsPreviewControl.CreateAsync),
    },
};

Il Execute delegate viene eseguito solo quando l'utente fa clic sull'azione. L'azione da sola non carica l'estensione solo per essere visualizzata. Localizzare il titolo dell'azione come si farebbe con un nome visualizzato dell'impostazione.

Selezionando la categoria viene caricata l'estensione per crearne l'anteprima. SettingPreviewFactory.Create chiama SettingsPreviewControl.CreateAsync, che restituisce un controllo dell'interfaccia utente remota. Il controllo ↗ anteprima di esempio si sottoscrive a TextLengthSetting e visualizza un'anteprima di testo di sola lettura che viene aggiornata man mano che cambia l'impostazione. Viene visualizzato un messaggio di errore se l'impostazione non può essere letta e rilascia la sottoscrizione quando il controllo viene rilasciato. Mantenere la factory asincrona e rilasciare eventuali sottoscrizioni o altre risorse al termine dell'anteprima.

Tips

✅ DO

  • Attiva GenerateObserverClass = true per le categorie che si desidera osservare
  • Controllare Succeeded e Error quando devono essere segnalati errori di lettura; usare ValueOrDefault() solo per un fallback intenzionale
  • Usare stringhe localizzate (%key%) per i nomi visualizzati e le descrizioni
  • Eseguire il batch di più scritture in una singola WriteAsync chiamata
  • Chiama serviceCollection.AddSettingsObservers() in InitializeServices

❌ DON'T

  • Non modificare i moniker di impostazione (nomi) dopo il rilascio: fanno parte del profilo mobile
  • Non leggere le impostazioni in cicli stretti: usare gli osservatori per la notifica delle modifiche
  • Non mantenere un abbonamento dopo il rilascio del proprietario
  • Non dimenticare [VisualStudioContribution] in entrambe le categorie e nelle impostazioni

🔧 Risoluzione dei problemi

Sintomo Correzione
Impostazione non visualizzata nell'interfaccia utente Verificare [VisualStudioContribution] sia la categoria che l'impostazione
Observer non viene attivato Assicurarsi che AddSettingsObservers() venga chiamato in InitializeServices
ReadEffectiveValueAsync restituisce un errore Esaminare result.Error invece di considerare un fallback come lettura riuscita
Classe observer generata non trovata Ricompilare dopo l'impostazione GenerateObserverClass = true; controllare lo spazio dei nomi (Settings.MyCategoryObserver)

Passaggi successivi