Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 = trueper le categorie che si desidera osservare - Controllare
SucceededeErrorquando devono essere segnalati errori di lettura; usareValueOrDefault()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
WriteAsyncchiamata - Chiama
serviceCollection.AddSettingsObservers()inInitializeServices
❌ 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
- Provider di impostazioni esterne — archivia le impostazioni nel tuo archivio
- Aggiungi un comando — usa le impostazioni per controllare il comportamento del comando
- Inserimento delle dipendenze : modalità di inserimento degli osservatori
- Localizzare i metadati — localizzare i nomi visualizzati delle opzioni