Erstellen von Visual Studio-Benutzeraufforderungen

Benutzeraufforderungen sind ein einfacher UI-Mechanismus, mit dem der Benutzer aufgefordert wird, eine Auswahl vorzunehmen, eine Nachricht zu bestätigen oder eine einzeilige Zeichenfolgeneingabe bereitzustellen. Wenn der Benutzer aufgefordert wird, wird ein Dialogfeld mit einer Nachricht, einer Titelleiste, einer Schaltfläche " Schließen " und einem optionalen Symbol erstellt. Wenn der Benutzer vom Dialogfeld aufgefordert wird, aus einer Reihe von Optionen auszuwählen, enthält es auch eine bis drei Schaltflächen für die Auswahl.

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.

Die Benutzeraufforderung hat zwei Varianten: Optionsaufforderungen und Eingabeaufforderungen.

Häufige Beispiele für Optionsaufforderungen sind das Anfordern einer Bestätigung mit einer Aufforderung "OK" oder "Abbrechen", oder sie bitten den Benutzer, zwischen einer kleinen Gruppe von Optionen (nicht mehr als drei) auszuwählen.

Die Optionen, die dem Benutzer angezeigt werden, sind den Rückgabewerten des im Typparameter definierten Typs zugeordnet.

Um den Benutzer aufzufordern, eine einzeilige Zeichenfolgeneingabe anzugeben, z. B. einen Projektnamen, verwenden Sie eine Eingabeaufforderung.

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

Teile einer Benutzeraufforderung

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

Loslegen

Führen Sie zunächst die Schritte unter "Erstellen Ihrer ersten Visual Studio-Erweiterung" aus.

Arbeiten mit Benutzeraufforderungen

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

• Anzeigen einer Benutzeraufforderung
• Verwenden von integrierten Optionen
• Erstellen einer Eingabeaufforderung mit benutzerdefinierten Optionen

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()

Die ShowPromptAsync-Methode akzeptiert drei Parameter:

Parameter	Typ	Erforderlich	BESCHREIBUNG
message	string	Ja	Der Text der Nachricht für die Aufforderung.
options	PromptOptions<TResult>	Ja	Definiert die Benutzerauswahl und ordnet sie Rückgabewerten zu.
cancellationToken	CancellationToken	Ja	Die CancellationToken für den asynchronen Vorgang. Wenn die Eingabeaufforderung ausgelöst wird, wird sie zwangsweise geschlossen.

Beispiel

Der folgende Code innerhalb eines 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.

OKAY

Auswahl	Standard	Rückgabewert
OKAY	Ja	true
schließen		false

OKAbbrechen

Auswahl	Standard	Rückgabewert
OKAY	Ja	true
Abbrechen	Nein	false
schließen		false

WiederholenAbbrechen

Auswahl	Standard	Rückgabewert
Wiederholen.	Ja	true
Abbrechen	Nein	false
schließen		false

Bestätigungen mit Symbol

Auswahl	Standard	Rückgabewert
OKAY	Ja	true
schließen		false

Auswahlmöglichkeit	Ikone
ErrorConfirm	ImageMoniker.KnownValues.StatusError
WarningConfirm	ImageMoniker.KnownValues.StatusWarning
AlertConfirm	ImageMoniker.KnownValues.StatusAlert
InformationConfirm	ImageMoniker.KnownValues.StatusInformation
HelpConfirm	ImageMoniker.KnownValues.StatusConfirm

Beispiel

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 OK auswählt, gibt ShowPromptAsync bei Erwartung true zurück. Wenn der Benutzer die Schaltfläche "Schließen" auswählt, wird false zurückgegeben.

Ändern der Standardauswahl einer integrierten Option zum 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

Sie können auch die Auswahlmöglichkeiten anpassen, die dem Benutzer angezeigt werden, und den Rückgabewert, der den einzelnen Optionen zugeordnet ist.

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 an ShowPromptAsync zusammen mit den erforderlichen message und cancellationToken Argumenten.

Passen Sie den Titel und das Symbol an, indem Sie die Eigenschaften von Title und Icon festlegen.

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

Die Choices Auflistung ordnet die Benutzerauswahl den Werten im benutzerdefinierten Systems Enum zu. Wenn der Benutzer die Schaltfläche "Schließen" auswählt, legt DismissedReturns den zurückgegebenen Wert fest. DefaultChoiceIndex ist ein nullbasierter Index in der Choices Auflistung, der die Standardauswahl definiert.

Erstellen einer Eingabeaufforderung

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

Neben benutzerdefinierten Symbolen wie Auswahlaufforderungen unterstützen Eingabeaufforderungen auch einen Standardwert. Legen Sie die DefaultText Eigenschaft für die InputPromptOptions Instanz fest.

Wenn der Benutzer die Schaltfläche "Abbrechen", die Schaltfläche "Schließen" oder die ESC-Taste auswählt, ist der Rückgabewert null. Wenn der Benutzer die Eingabe leer lässt und die Schaltfläche "OK " oder die EINGABETASTE auswählt, ist der Rückgabewert die leere Zeichenfolge.

Andernfalls ist der Rückgabewert der Inhalt der Eingabe, wenn der Benutzer seinen Eintrag bestätigt.

Verwandte Inhalte

Die folgenden Beispiele veranschaulichen, wie Sie mit Benutzeraufforderungen arbeiten:

• UserPromptSample
• MarkdownLinter