Freigeben über

Erstellen von Visual Studio-Benutzeraufforderungen

  • Artikel

Benutzeraufforderungen sind ein einfacher UI-Mechanismus, mit dem der Benutzer aufgefordert wird, eine Auswahl vorzunehmen. Durch Die Aufforderung des Benutzers wird ein Dialogfeld mit einer Nachricht, einer bis drei Schaltflächen für die Auswahl und einer Schaltfläche zum Schließen erstellt.

Hinweis

Die genaue Benutzeroberfläche, die verwendet wird, um Benutzer auf der Grundlage von Benutzerfeedback oder anderen Faktoren zu benachrichtigen, kann sich in zukünftigen Versionen ändern.

Häufig verwendete Beispiele fordern eine Bestätigung mit einer Eingabeaufforderung "OK/Abbrechen" an oder bitten den Benutzer, zwischen einer kleinen Gruppe von Optionen (nicht mehr als drei) auszuwählen.

Der Benutzer hat immer die Möglichkeit, die Eingabeaufforderung zu schließen, ohne eine Auswahl vorzunehmen.

Die optionen, die dem Benutzer angezeigt werden, werden den Rückgabewerten des typs zugeordnet, der TResult im Typparameter definiert ist.

Teile einer Benutzeraufforderung

Screenshot showing the parts of a user prompt.

  1. `Message`
  2. Auswahlschaltflächen
  3. Schaltfläche "Schließen"

Erste Schritte

Folgen Sie zunächst dem Abschnitt "Projekt erstellen" im Abschnitt "Erste Schritte".

Arbeiten mit Benutzeraufforderungen

In diesem Handbuch werden die folgenden Szenarien für das Arbeiten mit Benutzeraufforderungen behandelt:

Anzeigen einer Benutzeraufforderung

Das Erstellen einer Benutzeraufforderung mit dem neuen Erweiterbarkeitsmodell ist so einfach wie das Aufrufen der ShowPromptAsync Methode über die ShellExtensibility-Hilfsprogramme und das Übergeben Ihrer Optionen.

ShellExtensibility.ShowPromptAsync<TResult>()

Die Methode ShowPromptAsync akzeptiert drei Parameter:

Parameter Type Erforderlich Beschreibung
Nachricht string ja Der Text der Nachricht für die Eingabeaufforderung.
Optionen PromptOptions<TResult> ja Definiert die Benutzerauswahl, ordnet sie den Rückgabewerten zu.
cancellationToken CancellationToken Ja Der CancellationToken für den asynchronen Vorgang. Wenn die Eingabeaufforderung ausgelöst wird, wird die Eingabeaufforderung erzwungen geschlossen.

Beispiel

Der folgende Code in einer Abbildung Command zeigt eine Benutzeraufforderung mit einer einfachen Nachricht und einer Schaltfläche "OK".

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

Verwenden von integrierten Optionen

Im SDK sind mehrere Vordefinierte Sätze PromptOptions verfügbar.

OK

Option Standard Rückgabewert
"OK" Ja true
Verworfen false

OKCancel

Option Standard Rückgabewert
"OK" Ja true
"Abbrechen" Nein false
Verworfen false

RetryCancel

Option Standard Rückgabewert
"Wiederholen" Ja true
"Abbrechen" Nein false
Verworfen false

Beispiel

Screenshot showing a user prompt with OK.

Erstellen Sie eine Eingabeaufforderung mit einer einzigen "OK"-Auswahl.

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

Wenn der Benutzer auf "OK" klickt, ShowPromptAsync wird er beim Warten zurückgegeben true . Wenn der Benutzer auf die Schaltfläche "Schließen" klickt, wird sie zurückgegeben false.

Ändern der Standardauswahl einer integrierten Option in "Abbrechen"

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

Erstellen einer Eingabeaufforderung mit benutzerdefinierten Optionen

Screenshot showing a custom user prompt.

Zusätzlich zu den integrierten Optionen können Sie die für den Benutzer dargestellten Optionen und den jeweils jeweils zugeordneten Rückgabewert anpassen.

Statt die in PromptOptionsdefinierten Sets zu verwenden, erstellen Sie eine neue Instanz, PromptOptions<TResult> und übergeben Sie sie an ShowPromptAsync.

Beispiel

Erstellen Sie zunächst einen Werttyp, um die Rückgabewerte zu definieren:

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

Erstellen Sie dann die PromptOptions<TResult> Instanz, und übergeben Sie sie ShowPromptAsync zusammen mit den erforderlichen message und cancellationToken Argumenten:

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

Die Choices Auflistung ordnet die Benutzerauswahl werten in der TokenThemeResult Enumeration zu. DismissedReturns legt den Wert fest, der zurückgegeben wird, wenn der Benutzer auf die Schaltfläche "Schließen" klickt. DefaultChoiceIndex ist ein nullbasierter Index in der Choices Auflistung, der die Standardauswahl definiert.

Nächste Schritte

Die folgenden Beispiele veranschaulichen, wie Sie mit Benutzeraufforderungen arbeiten: