创建 Visual Studio 对话框

项目
01/23/2024

对话是提示用户提供信息或允许自定义功能行为的一种方法。例如，“工具/选项”对话框具有单独的页面，允许用户控制主题、编辑器和文档选项卡等功能的行为。

开始使用

若要开始，请按照“入门”部分中的“创建项目”部分进行操作。

使用对话

本指南旨在介绍使用对话时的首要用户方案：

创建对话框
自定义对话框标题
自定义对话框按钮
获取对话框结果

创建对话框

使用新的扩展性模型创建工具窗口非常简单，只需从 ShellExtensibility 帮助程序调用 ShowDialogAsync 方法并传入对话内容即可。

Screenshot of a Dialog.

ShowDialogAsync

ShowDialogAsync 方法有多个重载，你应该熟悉这些重载：

重载

参数

客户	Type	描述
content	Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl	对话框的内容。
title	System.String	对话框的标题。
选项	Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption	用于显示对话框的选项。
cancellationToken	System.Threading.CancellationToken	取消对话框的 CancellationToken 。

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

有关创建 RemoteUserControl 的详细信息，请参阅远程 UI。

自定义对话框标题

扩展显示对话框时，可以提供将在对话框的描述文字区域中显示的自定义标题字符串。

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

自定义对话框按钮

当 IDE 中显示对话时，可以选择预定义对话按钮和默认操作的某些组合。可以在中找到 Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption预定义的按钮和操作组合。

此外，还可以从以下项创建自己的按钮和默认操作组合：

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
}

示例

添加取消按钮：

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

没有对话框按钮：

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

获取对话框结果

如果需要知道用户是肯定地关闭了对话还是将其关闭，可以等待调用 ShowDialogAsync，并且它将返回一个 Microsoft.VisualStudio.RpcContracts.Notifications.DialogResult表示用户执行的操作。

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

后续步骤

有关使用对话框创建扩展的完整示例，请参阅 DialogSample 示例。

Share via