Create Visual Studio dialogs

Article
01/22/2024

Dialogs are a way to prompt a user for information or to allow for customizations of feature behavior. For example, the Tools/Options dialog has individual pages that let the user control the behavior for features like themes, editors, and document tabs.

Get started

To get started, follow the create the project section in the Getting Started section.

Work with dialogs

This guide is designed to cover the top user scenarios when working with dialogs:

Create a dialog
Customize the dialog title
Customize the dialog buttons
Get the dialog result

Create a dialog

Creating a tool window with the new Extensibility Model is as simple as calling the ShowDialogAsync method from the ShellExtensibility helpers and passing in your dialog content.

Screenshot of a Dialog.

ShowDialogAsync

The ShowDialogAsync method has several overloads that you should become familiar with:

Overloads

Parameters

Name	Type	Description
content	Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl	The content of the dialog.
title	System.String	The title of the dialog.
options	Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption	The options for displaying the dialog.
cancellationToken	System.Threading.CancellationToken	A CancellationToken to cancel the dialog.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    // Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
    #pragma warning disable CA2000 // Dispose objects before losing scope
    var control = new MyDialogControl(null);
    #pragma warning restore CA2000 // Dispose objects before losing scope

    await this.Extensibility.Shell().ShowDialogAsync(control, cancellationToken);
}

For more information on creating a RemoteUserControl, see Remote UI.

Customize the dialog title

When your extension shows a dialog, you can provide a custom title string which will be displayed in the dialog's caption region.

Screenshot showing a Dialog title.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    // Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
    #pragma warning disable CA2000 // Dispose objects before losing scope
    var control = new MyDialogControl(null);
    #pragma warning restore CA2000 // Dispose objects before losing scope

    await this.Extensibility.Shell().ShowDialogAsync(control, "My Dialog Title", cancellationToken);
}

Customize the dialog buttons

When a dialog is shown in the IDE, certain combinations of predefined dialog buttons and default actions can be selected. The predefined button and action combinations can be found in Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption.

Additionally, you can create your own combination of buttons and default actions from:

Microsoft.VisualStudio.RpcContracts.Notifications.DialogButton

public enum DialogButton
{
    // Hides all of the dialog buttons.
    None,
    // Shows a single close button.
    Close,
    // Shows a single OK button.
    OK,
    // Shows an OK and Cancel button.
    OKCancel
}

Microsoft.VisualStudio.RpcContracts.Notifications.DialogResult

public enum DialogResult
{
    // The dialog was closed via the System.Threading.CancellationToken or using an
    // action provided by the Microsoft.Visual Studio.RpcContracts.RemoteUI.IRemoteUserControl
    // content.
    None,
    // The user clicked the Close button.
    Close,
    // The user clicked the OK button.
    OK,
    // The user clicked the Cancel button, or clicked the nonclient close button, or
    // pressed the Esc key.
    Cancel
}

Examples

Adding a cancel button:

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    // Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
    #pragma warning disable CA2000 // Dispose objects before losing scope
    var control = new MyDialogControl(null);
    #pragma warning restore CA2000 // Dispose objects before losing scope

    await this.Extensibility.Shell().ShowDialogAsync(control, DialogOption.OKCancel, cancellationToken);
}

Having no dialog buttons:

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    // Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
    #pragma warning disable CA2000 // Dispose objects before losing scope
    var control = new MyDialogControl(null);
    #pragma warning restore CA2000 // Dispose objects before losing scope

    await this.Extensibility.Shell().ShowDialogAsync(control, new DialogOption(DialogButton.None, DialogResult.None), cancellationToken);
}

Get the dialog result

If you need to know whether a user affirmatively closed a dialog or dismissed it, you can await the call to ShowDialogAsync, and it will return a Microsoft.VisualStudio.RpcContracts.Notifications.DialogResult, which represents the action taken by the user.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    // Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
    #pragma warning disable CA2000 // Dispose objects before losing scope
    var control = new MyDialogControl(null);
    #pragma warning restore CA2000 // Dispose objects before losing scope

    DialogResult result = await this.Extensibility.Shell().ShowDialogAsync(control, "My Dialog Title", DialogOption.OKCancel, cancellationToken);

    if (result == DialogResult.OK)
    {
        // User clicked the OK button
    }
}

Next steps

See the DialogSample sample for a full example of creating an extension with a dialog.

Share via