Creación de solicitudes de usuario de Visual Studio

Las solicitudes de usuario son un mecanismo de interfaz de usuario simple para pedir al usuario que realice una selección, confirme un mensaje o proporcione una entrada de cadena de una sola línea. Al preguntar al usuario se crea un cuadro de diálogo con un mensaje, una barra de título, un botón Cerrar y un icono opcional. Cuando el cuadro de diálogo pide al usuario que elija entre un conjunto de opciones, también contiene uno a tres botones para las opciones.

El mensaje del usuario tiene dos variantes: avisos de opción y mensajes de entrada.

Algunos ejemplos comunes de avisos de opción son solicitar confirmación con un mensaje Aceptar o Cancelar, o pedir al usuario que elija entre un pequeño conjunto de opciones (no más de tres).

Las opciones presentadas al usuario se asignan a los valores devueltos del tipo definido en el TResult parámetro type.

Para pedir al usuario que proporcione una entrada de cadena de una sola línea, como un nombre de proyecto, use un mensaje de entrada.

El usuario siempre tiene la opción de descartar el mensaje sin realizar una selección.

Partes de un mensaje de usuario

1. Mensaje
2. Botones de elección
3. Cerrar botón

Comienza

Para empezar, siga los pasos descritos en Creación de la primera extensión de Visual Studio.

Trabajar con indicaciones de usuario

En este artículo se describen los siguientes escenarios para trabajar con solicitudes de usuario:

• Mostrar un mensaje de usuario
• Uso de opciones integradas
• Crear un mensaje con opciones personalizadas

Mostrar un mensaje de usuario

La creación de una solicitud de usuario con el nuevo modelo de extensibilidad es tan simple como llamar al método ShowPromptAsync de los asistentes ShellExtensibility y pasar las opciones.

ShellExtensibility.ShowPromptAsync()

El método ShowPromptAsync toma tres parámetros:

Ejemplo

El código siguiente dentro de un Command muestra un mensaje sencillo al usuario y un botón Aceptar.

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

Uso de opciones integradas

Hay varios conjuntos predefinidos PromptOptions disponibles en el SDK.

De acuerdo

AceptarCancelar

Intentar de nuevo / Cancelar

Confirmaciones con icono

Ejemplo

Cree un mensaje con una única opción Aceptar.

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

Si el usuario selecciona Aceptar, ShowPromptAsync devuelve true al ser esperado. Si el usuario selecciona el botón Cerrar , devuelve false.

Cambiar la opción predeterminada de una opción integrada para cancelar

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

Crear un aviso con opciones personalizadas

También puede personalizar las opciones presentadas al usuario y el valor devuelto asignado a cada uno.

En lugar de usar los conjuntos definidos en PromptOptions, cree una nueva instancia de PromptOptions<TResult> y pásela a ShowPromptAsync.

Ejemplo

Empiece por crear un tipo de valor para definir los valores devueltos:

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

A continuación, cree la PromptOptions<TResult> instancia y pásela a ShowPromptAsync junto con los argumentos message y cancellationToken necesarios.

Personalice el título y el icono estableciendo las Title propiedades y Icon .

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}");
}

La colección Choices mapea las elecciones del usuario a valores en la enumeración personalizada Systems. Si el usuario selecciona el botón Cerrar , DismissedReturns establece el valor devuelto. DefaultChoiceIndex es un índice de base cero en la Choices colección que define la opción predeterminada.

Crear un aviso de entrada

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

Además de iconos personalizados como avisos de elección, las indicaciones de entrada también admiten un valor predeterminado. Establezca la propiedad DefaultText en la instancia InputPromptOptions.

Si el usuario selecciona el botón Cancelar , el botón Cerrar para descartar o la tecla Esc, el valor devuelto es null. Si el usuario deja la entrada en blanco y selecciona el botón Aceptar o la tecla Entrar, el valor devuelto es la cadena vacía.

De lo contrario, el valor devuelto es el contenido de la entrada cuando el usuario confirma su entrada.

Contenido relacionado

En los ejemplos siguientes se muestra cómo trabajar con solicitudes de usuario:

• UserPromptSample
• MarkdownLinter