Create Visual Studio user prompts

User prompts are a simple UI mechanism for prompting the user to make a selection, confirm a message, or provide a single-line string input. Prompting the user creates a dialog box with a message, a title bar, a Close button, and an optional icon. When the dialog prompts the user to choose from a set of options, it also contains one to three buttons for the choices.

The user prompt has two variants: option prompts and input prompts.

Common examples of option prompts are requesting confirmation with an OK or Cancel prompt, or asking the user to choose among a small set of options (no more than three).

The choices presented to the user are mapped to return values of the type defined in the TResult type parameter.

To ask the user to provide a single-line string input, such as a project name, use an input prompt.

The user always has the option of dismissing the prompt without making a selection.

Parts of a user prompt

1. Message
2. Choice buttons
3. Close button

Get started

To get started, follow steps in Create your first Visual Studio extension.

Work with user prompts

This article covers the following scenarios for working with user prompts:

• Display a user prompt
• Use built-in options
• Create a prompt with custom options

Display a user prompt

Creating a user prompt with the new Extensibility model is as simple as calling the ShowPromptAsync method from the ShellExtensibility helpers and passing in your options.

ShellExtensibility.ShowPromptAsync()

The ShowPromptAsync method takes three parameters:

Example

The following code inside a Command shows a user prompt with a simple message and an OK button.

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

Use built-in options

Several sets of predefined PromptOptions are available in the SDK.

OK

OKCancel

RetryCancel

Confirmations with icon

Example

Create a prompt with a single OK choice.

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;
    }
    
    ...
}

If the user selects OK, ShowPromptAsync returns true when awaited. If the user selects the Close button, it returns false.

Change the default choice of a built-in option to cancel

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;
  }
  
  ...
}

Create a prompt with custom options

You can also customize the choices presented to the user and the return value mapped to each one.

Instead of using the sets defined in PromptOptions, create a new instance of PromptOptions<TResult> and pass it to ShowPromptAsync.

Example

Start by creating a value type to define the return values:

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

Then create the PromptOptions<TResult> instance and pass it to ShowPromptAsync along with the required message and cancellationToken arguments.

Customize the title and icon by setting the Title and Icon properties.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Custom prompt
  Systems selectedSystem = await shell.ShowPromptAsync(
      "Select the system to configure:",
      new PromptOptions<Systems>
      {
          Choices =
          {
              { "Core", Systems.CoreSystem },
              { "Auxiliary", Systems.AuxiliarySystem },
              { "Monitoring", Systems.MonitoringSystem },
          },
          DismissedReturns = Systems.CoreSystem,
          DefaultChoiceIndex = 2
          Title = "Configuration Assistant",
          Icon = ImageMoniker.KnownValues.Settings,
      },
      cancellationToken);

  Debug.WriteLine($"Selected system: {selectedSystem}");
}

The Choices collection maps the user choices to values in the custom Systems enum. If the user selects the Close button, DismissedReturns sets the value that's returned. DefaultChoiceIndex is a zero-based index into the Choices collection that defines the default choice.

Create an input prompt

string? projectName = await shell.ShowPromptAsync(
    "Enter the name of the project to configure?",
    InputPromptOptions.Default with { Title = "Configuration Assistant" },
    cancellationToken);

In addition to custom icons like choice prompts, input prompts also support a default value. Set the DefaultText property on the InputPromptOptions instance.

If the user selects the Cancel button, the Close button to dismiss, or the Esc key, the return value is null. If the user leaves the input blank and selects the OK button or the Enter key, the return value is the empty string.

Otherwise, the return value is the content of the input when the user confirms their entry.

Related content

The following samples demonstrate how to work with user prompts:

• UserPromptSample
• MarkdownLinter