Delen via

Visual Studio-gebruikersprompts maken

Gebruikersprompts zijn een eenvoudig UI-mechanisme om de gebruiker te vragen een selectie te maken, een bericht te bevestigen of een invoer voor een tekenreeks met één regel op te geven. Wanneer de gebruiker wordt gevraagd, wordt een dialoogvenster gemaakt met een bericht, een titelbalk, een knop Sluiten en een optioneel pictogram. Wanneer in het dialoogvenster de gebruiker wordt gevraagd uit een set opties te kiezen, bevat het ook een tot drie knoppen voor de keuzen.

Opmerking

De exacte gebruikersinterface die wordt gebruikt om gebruikers te attenderen, kan in toekomstige versies veranderen op basis van gebruikersfeedback of andere factoren.

De gebruikersprompt heeft twee varianten: optieprompts en invoerprompts.

Veelvoorkomende voorbeelden van keuzeprompts vragen om bevestiging met een ok- of annuleringsprompt, of de gebruiker vragen een kleine set opties te kiezen (niet meer dan drie).

De opties die aan de gebruiker worden gepresenteerd, zijn gekoppeld aan terugkerende waarden van het type dat is gedefinieerd in de TResult typeparameter.

Gebruik een invoerprompt om de gebruiker te vragen een tekenreeksinvoer met één regel op te geven, zoals een projectnaam.

De gebruiker heeft altijd de mogelijkheid om de prompt te sluiten zonder een selectie te maken.

Onderdelen van een gebruikersprompt

Schermopname van de onderdelen van een gebruikersprompt.

  1. Bericht
  2. Keuzeknoppen
  3. Knop Sluiten

Aan de slag

Volg de stappen in Uw eerste Visual Studio-extensie maken om aan de slag te gaan.

Werken met gebruikersprompts

In dit artikel worden de volgende scenario's beschreven voor het werken met gebruikersprompts:

Een gebruikersprompt weergeven

Het maken van een gebruikersprompt met het nieuwe Extensibility-model is net zo eenvoudig als het aanroepen van de ShowPromptAsync methode vanuit de ShellExtensibility-helpers en het doorgeven van uw opties.

ShellExtensibility.ShowPromptAsync()

De methode ShowPromptAsync heeft drie parameters:

Kenmerk Typologie Verplicht Beschrijving
message string Ja De tekst van het bericht voor de prompt.
options PromptOptions<TResult> Ja Definieert de gebruikerskeuzes en koppelt deze aan terugkeerwaarden.
cancellationToken CancellationToken Ja De CancellationToken voor de asynchrone bewerking. Wanneer deze wordt geactiveerd, wordt de prompt geforceerd gesloten.

Voorbeeld

De volgende code in een Command bericht toont een gebruikersprompt met een eenvoudig bericht en een knop OK .

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

Ingebouwde opties gebruiken

Er zijn verschillende sets vooraf gedefinieerd PromptOptions beschikbaar in de SDK.

OK

Keuze Verstek Retourwaarde
OK- Ja true
sluiten false

OK Annuleren

Keuze Verstek Retourwaarde
OK- Ja true
annuleren Nee. false
sluiten false

Opnieuw proberenCancel

Keuze Verstek Retourwaarde
Opnieuw proberen Ja true
annuleren Nee. false
sluiten false

Bevestigingen met pictogram

Keuze Verstek Retourwaarde
OK- Ja true
sluiten false
Optie Icoon
ErrorConfirm ImageMoniker.KnownValues.StatusError
WarningConfirm ImageMoniker.KnownValues.StatusWarning
AlertConfirm ImageMoniker.KnownValues.StatusAlert
InformationConfirm ImageMoniker.KnownValues.StatusInformation
HelpConfirm ImageMoniker.KnownValues.StatusConfirm

Voorbeeld

Schermopname van een gebruikersprompt met OK.

Maak een prompt met één OK-keuze .

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

Als de gebruiker OK selecteert, retourneert ShowPromptAsynctrue wanneer erop gewacht wordt. Als de gebruiker de knop Sluiten selecteert, wordt er false geretourneerd.

De standaardkeuze van een ingebouwde optie wijzigen om te annuleren

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

Een prompt maken met aangepaste opties

Schermopname van een aangepaste gebruikersprompt.

U kunt ook de opties aanpassen die aan de gebruiker worden gepresenteerd en de geretourneerde waarde die aan elke waarde is toegewezen.

In plaats van de in PromptOptions gedefinieerde sets te gebruiken, maakt u een nieuw exemplaar van PromptOptions<TResult> aan en geeft u dit door aan ShowPromptAsync.

Voorbeeld

Begin met het maken van een waardetype om de retourwaarden te definiëren:

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

Maak vervolgens het PromptOptions<TResult> exemplaar en geef het door aan ShowPromptAsyncsamen met de vereiste message argumenten.cancellationToken

Pas de titel en het pictogram aan door de Title en Icon eigenschappen in te stellen.

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

De Choices verzameling wijst de gebruikerskeuzes toe aan waarden in de aangepaste Systems opsomming. Als de gebruiker de knop Sluiten selecteert, DismissedReturns stelt u de geretourneerde waarde in. DefaultChoiceIndex is een op nul gebaseerde index in de Choices verzameling die de standaardkeuze definieert.

Een invoerprompt maken

Schermopname van een eenvoudige invoerprompt. 

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

Naast aangepaste pictogrammen, zoals keuzeprompts, ondersteunen invoerprompts ook een standaardwaarde. Stel de DefaultText eigenschap in op het InputPromptOptions exemplaar.

Als de gebruiker de knop Annuleren selecteert, de Sluiten knop om af te sluiten, of de Esc-toets, is de retourwaarde null. Als de gebruiker de invoer leeg laat en de knop OK of enter selecteert, is de retourwaarde de lege tekenreeks.

Anders is de retourwaarde de inhoud van de invoer wanneer de gebruiker de vermelding bevestigt.

Verwante inhoud

In de volgende voorbeelden ziet u hoe u met gebruikersprompts kunt werken: