建立 Visual Studio 使用者提示

使用者提示是簡單的 UI 機制，可提示使用者進行選取。 提示使用者會建立一個包含訊息的對話框、一到三個用於選擇的按鈕，以及一個關閉按鈕。

注意

用來提示使用者的確切 UI，在未來的版本中可能會根據使用者意見反應或其他因素而變更。

常見的範例是使用 [確定/取消] 提示請求確認，或要求使用者從一組小選項 (不超過 3 個) 中進行選擇。

使用者始終可以選擇忽略提示而不進行選取。

提供給使用者的選項，會對應至在 TResult 類型參數中定義的類型傳回值。

使用者提示的組成

1. 訊息
2. 選擇按鈕
3. 關閉按鈕

開始使用

若要開始，請遵循《使用者入門》一節中的建立專案一節。

使用使用者提示

本指南介紹了下列使用使用者提示的案例：

• 顯示使用者提示
• 使用內建選項
• 使用自訂選項建立提示

顯示使用者提示

使用新的 [擴充性模型] 建立使用者提示，就像從 ShellExtensibility 協助程式呼叫 ShowPromptAsync 方法並傳入選項一樣簡單。

ShellExtensibility.ShowPromptAsync<TResult>()

ShowPromptAsync 方法採用三個參數：

參數	類型​	必要	描述
message	string	是	提示訊息的文字。
電子商務選項中	PromptOptions<TResult>	是	定義使用者選擇，將其對應至傳回值。
cancellationToken	CancellationToken	Yes	非同步作業的 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。

確定

選擇	預設	傳回值
[確定]	Yes	true
已解除		false

OKCancel

選擇	預設	傳回值
[確定]	Yes	true
[取消]	No	false
已解除		false

RetryCancel

選擇	預設	傳回值
[重試]	Yes	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> 執行個體並將它連同必要的 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