创建 Visual Studio 用户提示

用户提示是一种简单的 UI 机制，用于提示用户进行选择。 提示用户创建一个对话框，其中包含一条消息、一到三个选项按钮和一个关闭按钮。

注意

用于提示用户的确切 UI 可能会根据用户反馈或其他因素在将来版本中更改。

常见示例是请求使用 OK/Cancel 提示进行确认，或要求用户在一组小选项（不超过三个选项）中进行选择。

用户始终可以选择在不做出选择的情况下关闭提示。

向用户提供的选项将映射到返回类型参数中 TResult 定义的类型的值。

用户提示的一部分

1. 消息
2. 选择按钮
3. “消除”按钮

开始使用

若要开始，请按照“入门”部分中的“创建项目”部分进行操作。

使用用户提示

本指南介绍以下使用用户提示的方案：

• 显示用户提示
• 使用内置选项
• 使用自定义选项创建提示

显示用户提示

使用新的扩展性模型创建用户提示非常简单，只需从 ShellExtensibility 帮助程序调用ShowPromptAsync方法并传入选项即可。

ShellExtensibility.ShowPromptAsync<TResult>()

ShowPromptAsync 方法采用三个参数：

参数	类型​​	必需	说明
message	string	是	提示消息的文本。
选项	PromptOptions<TResult>	是	定义用户选择，将其映射到返回值。
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))
}

使用内置选项

SDK 中提供了多个预定义 PromptOptions 集。

确定

选择	默认值	返回值
“确定”	是	true
解雇		false

OKCancel

选择	默认	返回值
“确定”	是	true
“取消”	否	false
解雇		false

RetryCancel

选择	默认	返回值
“重试”	是	true
“取消”	否	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<TResult>并将其传递给 ShowPromptAsync，而不是使用在其中PromptOptions定义的集。

示例

首先创建一个值类型来定义返回值：

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

然后创建PromptOptions<TResult>实例并将其与必需message参数cancellationToken和参数一起传递给ShowPromptAsync：

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