Пользовательские параметры и параметры в расширениях Visual Studio

2025-06-12

Хранение и извлечение параметров является обязательным для многих расширений. Давайте рассмотрим, как работать с параметрами с этими целями:

Простой способ предоставления настраиваемых параметров.
Предоставление параметров в диалоговом окне "Параметры инструментов>".
Потокобезопасный способ доступа и изменения параметров.
Синхронная и асинхронная поддержка.
Не нужно загружать пакет для инициализации параметров.

В следующем видео показано, как добавить параметры в расширение.

Вот как это должно выглядеть в диалоговом окне "Параметры инструментов>".

Добавление страницы параметров

Щелкните проект правой кнопкой мыши и выберите " Добавить > новый элемент", чтобы отобразить доступные шаблоны. Затем выберите категорию расширяемости в левой части и шаблон страницы параметров (сообщество). В поле имени ниже напишите "Общие".

Adding an options page from the Add New Item dialog.

При этом будет создан /Options/General.cs в корневом каталоге проекта.

The Options Page C# file added to the project.

Ниже приведено содержимое файла 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;
}

Это короткий и простой, и мы рассмотрим детали. Но сначала необходимо зарегистрировать страницу "Параметры".

Регистрация страницы "Параметры"

В комментарии кода в файле General.cs приведены инструкции по регистрации страницы "Параметры".

Все, что нам нужно сделать, заключается в копировании этих двух атрибутов в класс Package. Это может выглядеть примерно так:

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

При запуске расширения теперь должна появиться страница параметров MyExtension/General, отображающаяся в диалоговом окне "Параметры инструментов>".

Custom options page registered.

Два атрибута очень похожи, но обрабатывают различные сценарии.

Атрибут ProvideOptionsPage заключается в том, что страница "Параметры" отображается в диалоговом окне "Параметры инструментов>". Этот атрибут можно опустить, если вы не хотите, чтобы страница параметров отображалось пользователями.

ProvideProfile регистрирует параметры в перемещаемом профиле, что означает, что отдельные параметры будут перемещаться с учетной записью пользователя между экземплярами и установками Visual Studio. Он также включает функцию параметров импорта и экспорта Visual Studio. Этот атрибут является необязательным.

Отдельные параметры

В файле General.cs можно увидеть, как отдельные параметры не являются более простыми свойствами C#, украшенными атрибутами.

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

Простые типы данных, такие как string, boolintподдерживаются вне поля и охватывают большинство вариантов использования. Для других типов данных необходимо использовать преобразователи типов. Некоторые из них встроены в Visual Studio, например EnumConverter.

Рассмотрим эту перечисление:

public enum Numbers
{
    First,
    Second,
    Third,
}

Эти значения можно предоставить в раскрывающемся списке, объявив следующее TypeConverter :

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

Параметры чтения и записи

Теперь, когда вы зарегистрировали параметры, чтобы позволить пользователям изменять свои значения, пришло время читать эти значения, которые будут использоваться в нашем расширении.

Вы можете работать с параметрами синхронных и асинхронных контекстов. Начнем с синхронного:

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

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

API для чтения и записи в параметры очень просто и прямо.

При работе в асинхронном контексте API выглядит очень похоже.

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

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

События

При сохранении параметров запускается статическое событие General.Saved . Вы можете подписаться на это событие, как любое другое событие в .NET, и выглядит следующим образом:

General.Saved += OnSettingsSaved;

...

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

Получение исходного кода

Исходный код этого расширения можно найти в репозитории примеров.

Ознакомьтесь с документацией для всех сведений, связанных с этими сценариями, но обратите внимание, что хотя они предоставляют более подробную документацию, они не следуют рекомендациям, описанным в этом примере. Они также не используют сообщество набор средств, что упрощает работу с параметрами.