Создание запросов пользователей Visual Studio

Запросы пользователей — это простой механизм пользовательского интерфейса для запроса пользователя на выбор. Запрос пользователя создает диалоговое окно с сообщением, одной до трех кнопок для выбора и кнопкой закрытия.

Примечание.

Точный пользовательский интерфейс, используемый для запроса пользователей, может измениться в будущих версиях на основе отзывов пользователей или других факторов.

Распространенные примеры: запрос подтверждения с помощью запроса ОК или отмены или запрос пользователя выбрать один из небольших наборов параметров (не более трех).

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

Выбранные пользователю варианты сопоставляются с возвращаемыми значениями типа, определенного в параметре TResult типа.

Части запроса пользователя

1. Message
2. Кнопки выбора
3. Кнопка "Закрыть"

Начать

Чтобы приступить к работе, следуйте инструкциям по созданию раздела проекта в разделе "Начало работы".

Работа с запросами пользователей

В этом руководстве рассматриваются следующие сценарии работы с пользовательскими запросами:

• Отображение запроса пользователя
• Использование встроенных параметров
• Создание запроса с настраиваемыми параметрами

Отображение запроса пользователя

Создание запроса пользователя с помощью новой модели расширяемости так же просто, как вызов ShowPromptAsync метода из вспомогательных элементов ShellExtensibility и передачи параметров.

ShellExtensibility.ShowPromptAsync<TResult>()

Метод ShowPromptAsync принимает три следующих параметра.

Параметр	Type	Обязательно	Описание
message	string	yes	Текст сообщения для запроса.
options	PromptOptions<TResult>	yes	Определяет варианты пользователя, сопоставляя их с возвращаемыми значениями.
cancellationToken	CancellationToken	Да	Асинхронная CancellationToken операция. При активации запрос закрывается принудительно.

Пример

В приведенном ниже коде Command отображается запрос пользователя с простым сообщением и кнопкой "ОК".

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    await this.Extensibility.Shell().ShowPromptAsync("This is a user prompt.", PromptOptions.OK, cancellationToken))
}

Использование встроенных параметров

Несколько наборов предопределенных PromptOptions доступны в пакете SDK.

ОК

Выбранный вариант	По умолчанию	Возвращаемое значение
"ОК"	Да	true
Уволен		false

OKCancel

Выбранный вариант	По умолчанию	Возвращаемое значение
"ОК"	Да	true
"Отмена"	No	false
Уволен		false

RetryCancel

Выбранный вариант	По умолчанию	Возвращаемое значение
Повторная попытка	Да	true
"Отмена"	No	false
Уволен		false

Пример

Создайте запрос с одним выбором "ОК".

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
    // Asking the user to confirm an operation.
    if (!await this.Extensibility.Shell().ShowPromptAsync("Continue with executing the command?", PromptOptions.OKCancel, ct))
    {
      return;
    }
    
    ...
}

Если пользователь нажимает кнопку "ОК", ShowPromptAsync возвращается true после ожидания. Если пользователь нажимает кнопку "Закрыть", он возвращается false.

Измените выбор по умолчанию встроенного параметра на "Отмена"

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Asking the user to confirm an operation.
  if (!await this.Extensibility.Shell().ShowPromptAsync("Continue with executing the command?", PromptOptions.OKCancel.WithCancelAsDefault(), ct))
  {
    return;
  }
  
  ...
}

Создание запроса с настраиваемыми параметрами

Помимо встроенных параметров, можно настроить варианты, представленные пользователю, и возвращаемое значение, сопоставленное с каждым.

Вместо использования наборов, определенных в PromptOptions, создайте новый экземпляр PromptOptions<TResult> и передайте его ShowPromptAsyncв .

Пример

Сначала создайте тип значения, чтобы определить возвращаемые значения:

public enum TokenThemeResult
{
  None,
  Solarized,
  OneDark,
  GruvBox,
}

Затем создайте PromptOptions<TResult> экземпляр и передайте его ShowPromptAsync вместе с необходимыми message и cancellationToken аргументами:

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Custom prompt
  var themeResult = await this.Extensibility.Shell().ShowPromptAsync(
    "Which theme should be used for the generated output?",
    new PromptOptions<TokenThemeResult>
    {
      Choices =
      {
        { "Solarized Is Awesome", TokenThemeResult.Solarized },
        { "OneDark Is The Best", TokenThemeResult.OneDark },
        { "GruvBox Is Groovy", TokenThemeResult.GruvBox },
      },
      DismissedReturns = TokenThemeResult.None,
      DefaultChoiceIndex = 2,
    },
    ct);

  Debug.WriteLine($"Selected Token Theme: {themeResult}");
}

Коллекция Choices сопоставляет выбранные пользователем значения в перечислении TokenThemeResult . DismissedReturns задает значение, возвращаемое, если пользователь нажимает кнопку закрытия. DefaultChoiceIndex — это отсчитываемый от нуля индекс в Choices коллекции, которая определяет выбор по умолчанию.

Следующие шаги

В следующих примерах показано, как работать с запросами пользователей:

• UserPromptSample
• MarkdownLinter