Benutzerdefinierte Einstellungen und Optionen in Visual Studio-Erweiterungen

2025-06-12

Das Speichern und Abrufen von Einstellungen ist für viele Erweiterungen erforderlich. Sehen wir uns an, wie Sie mit Einstellungen mit diesen Zielen arbeiten können:

Eine einfache Möglichkeit, benutzerdefinierte Optionen bereitzustellen.
Machen Sie die Optionen im Dialogfeld "Extras-Optionen>" verfügbar.
Threadsichere Möglichkeit, auf die Einstellungen zuzugreifen und sie zu ändern.
Synchrone und asynchrone Unterstützung.
Das Paket muss nicht geladen werden, damit die Einstellungen initialisiert werden.

Das folgende Video zeigt, wie Sie einer Erweiterung Optionen hinzufügen.

So sollte es im Dialogfeld "Extras-Optionen>" aussehen.

Seite "Optionen hinzufügen"

Klicken Sie mit der rechten Maustaste auf Ihr Projekt, und wählen Sie " Neues Element hinzufügen > " aus, um die verfügbaren Vorlagen anzuzeigen. Wählen Sie dann die Erweiterbarkeitskategorie auf der linken Seite und dann die Vorlage "Optionsseite (Community)" aus. Schreiben Sie im feld "Name " unten " Allgemein".

Adding an options page from the Add New Item dialog.

Dadurch wird /Options/General.cs im Stammverzeichnis des Projekts erstellt.

The Options Page C# file added to the project.

Dies ist der Inhalt der Datei "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 ist kurz und einfach, und wir werden die Details übergehen. Zuerst müssen wir jedoch die Seite "Optionen" registrieren.

Registrieren der Seite "Optionen"

In einem Codekommentar in der Datei "General.cs " finden Sie Anweisungen zum Registrieren der Seite "Optionen".

Wir müssen nur diese beiden Attribute in unsere Package-Klasse kopieren. Das könnte etwa wie folgt aussehen:

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

Beim Ausführen der Erweiterung sollte nun die Seite "MyExtension/Allgemeine Optionen" im Dialogfeld "Extras > " angezeigt werden.

Custom options page registered.

Die beiden Attribute sind sehr ähnlich, behandeln jedoch unterschiedliche Szenarien.

Das ProvideOptionsPage Attribut bewirkt, dass die Seite "Optionen" im Dialogfeld "Extras > " angezeigt wird. Sie können dieses Attribut weglassen, wenn die Optionsseite für Ihre Benutzer nicht sichtbar sein soll.

ProvideProfile registriert die Optionen für das Roamingprofil. Dies bedeutet, dass die einzelnen Einstellungen mit dem Konto des Benutzers über Instanzen und Installationen von Visual Studio hinweg übertragen werden. Außerdem wird das Feature für Import-/Exporteinstellungen von Visual Studio aktiviert. Dieses Attribut ist optional.

Die einzelnen Optionen

In der Datei "General.cs" können Sie sehen, wie einzelne Optionen nicht mehr als einfache C#-Eigenschaften sind, die mit Attributen versehen sind.

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

Einfache Datentypen wie string, bool, intwerden alle standardmäßig unterstützt und umfassen die meisten Anwendungsfälle. Für andere Datentypen müssen wir Typkonverter verwenden. Einige sind in Visual Studio integriert, z. B. die EnumConverter.

Betrachten Sie diese Enumeration:

public enum Numbers
{
    First,
    Second,
    Third,
}

Wir können diese Werte als Optionen in einer Dropdownliste verfügbar machen, indem wir folgendes TypeConverter deklarieren:

[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.

Lese- und Schreiboptionen

Nachdem Sie die Optionen registriert haben, damit Ihre Benutzer ihre Werte ändern können, ist es an der Zeit, diese Werte zu lesen, die in unserer Erweiterung verwendet werden sollen.

Sie können mit Einstellungen aus synchronen und asynchronen Kontexten arbeiten. Beginnen wir mit dem synchronen:

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

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

Die API zum Lesen und Schreiben in die Einstellungen ist sehr einfach und direkt.

Bei der Arbeit in einem asynchronen Kontext sieht die API sehr ähnlich aus.

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

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

Ereignisse

Wenn die Einstellungen gespeichert werden, wird das statische Ereignis General.Saved ausgelöst. Sie können dieses Ereignis wie jedes andere Ereignis in .NET abonnieren und sieht wie folgt aus:

General.Saved += OnSettingsSaved;

...

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

Herunterladen des Quellcodes

Den Quellcode für diese Erweiterung finden Sie im Beispiel-Repository.

Lesen Sie die Dokumente für alle Details zu diesen Szenarien, beachten Sie jedoch, dass sie zwar detailliertere Dokumentationen bereitstellen, aber sie befolgen nicht die in diesem Beispiel beschriebenen bewährten Methoden. Sie verwenden auch nicht das Community-Toolkit, das das Arbeiten mit Einstellungen so viel einfacher macht.

Freigeben über