Skip to content

Commit 94d4d97

Browse files
paulth1paulth1
committed
edit pass: visual-studio-prompts-articles
1 parent f9ec9dc commit 94d4d97

File tree

3 files changed

+133
-133
lines changed

3 files changed

+133
-133
lines changed

‎docs/extensibility/visualstudio.extensibility/dialog/dialog.md

Lines changed: 43 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Dialogs reference
3-
description: A reference for extensibility dialogs
2+
title: Dialogs Reference
3+
description: A reference for extensibility dialogs.
44
ms.topic: overview
55
ms.date: 3/31/2023
66
ms.author: maiak
@@ -12,15 +12,15 @@ ms.subservice: extensibility-integration
1212

1313
# Create Visual Studio dialogs
1414

15-
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.
15+
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.
1616

1717
## Get started
1818

19-
To get started, follow the [create the project](./../get-started/create-your-first-extension.md) section in the Getting Started section.
19+
To get started, follow the steps in [Create your first Visual Studio extension](./../get-started/create-your-first-extension.md).
2020

2121
## Work with dialogs
2222

23-
This guide is designed to cover the top user scenarios when working with dialogs:
23+
This article covers the top user scenarios when you work with dialogs:
2424

2525
- [Create a dialog](#create-a-dialog)
2626
- [Customize the dialog title](#customize-the-dialog-title)
@@ -29,9 +29,9 @@ This guide is designed to cover the top user scenarios when working with dialogs
2929

3030
## Create a dialog
3131

32-
Creating a tool window with the new Extensibility Model is as simple as calling the [ShowDialogAsync](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility.showdialogasync) method from the [ShellExtensibility](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility) helpers and passing in your dialog content.
32+
Creating a tool window with the new Extensibility model is as simple as calling the [ShowDialogAsync](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility.showdialogasync) method from the [ShellExtensibility](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility) helpers and passing in your dialog content.
3333

34-
![Screenshot of a Dialog.](./media/dialog.png)
34+
![Screenshot that shows a dialog.](./media/dialog.png)
3535

3636
### ShowDialogAsync
3737

@@ -48,50 +48,50 @@ The [ShowDialogAsync](/dotnet/api/microsoft.visualstudio.extensibility.shell.she
4848

4949
| Name | Type | Description |
5050
| ---- | ---- | ----------- |
51-
| content | [Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl](/dotnet/api/microsoft.visualstudio.rpccontracts.remoteui.iremoteusercontrol 'Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl') | The content of the dialog. |
52-
| title | [System.String](/dotnet/api/System.String 'System.String') | The title of the dialog. |
53-
| options | Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption | The options for displaying the dialog. |
54-
| cancellationToken | [System.Threading.CancellationToken](/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') | A [CancellationToken](/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') to cancel the dialog. |
51+
| `content` | [Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl](/dotnet/api/microsoft.visualstudio.rpccontracts.remoteui.iremoteusercontrol 'Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl') | The content of the dialog. |
52+
| `title` | [System.String](/dotnet/api/System.String 'System.String') | The title of the dialog. |
53+
| `options` | `Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption` | The options for displaying the dialog. |
54+
| `cancellationToken` | [System.Threading.CancellationToken](/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') | A [CancellationToken](/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') to cancel the dialog. |
5555

5656
```csharp
5757
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
5858
{
59-
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
60-
#pragma warning disable CA2000 // Dispose objects before losing scope
59+
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension.
60+
#pragma warning disable CA2000 // Dispose of objects before losing scope.
6161
var control = new MyDialogControl(null);
62-
#pragma warning restore CA2000 // Dispose objects before losing scope
62+
#pragma warning restore CA2000 // Dispose of objects before losing scope.
6363
6464
await this.Extensibility.Shell().ShowDialogAsync(control, cancellationToken);
6565
}
6666
```
6767

68-
For more information on creating a RemoteUserControl, see [Remote UI](./../inside-the-sdk/remote-ui.md).
68+
For more information on how to create a remote user control, see [Remote UI](./../inside-the-sdk/remote-ui.md).
6969

7070
## Customize the dialog title
7171

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

74-
![Screenshot showing a Dialog title.](./media/dialog-title.png)
74+
![Screenshot that shows a dialog title.](./media/dialog-title.png)
7575

7676
```csharp
7777
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
7878
{
79-
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
80-
#pragma warning disable CA2000 // Dispose objects before losing scope
79+
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension.
80+
#pragma warning disable CA2000 // Dispose of objects before losing scope.
8181
var control = new MyDialogControl(null);
82-
#pragma warning restore CA2000 // Dispose objects before losing scope
82+
#pragma warning restore CA2000 // Dispose of objects before losing scope.
8383
8484
await this.Extensibility.Shell().ShowDialogAsync(control, "My Dialog Title", cancellationToken);
8585
}
8686
```
8787

8888
## Customize the dialog buttons
8989

90-
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`.
90+
When a dialog is shown in the integrated development environment, you can select certain combinations of predefined dialog buttons and default actions. You can find the predefined button and action combinations in `Microsoft.VisualStudio.RpcContracts.Notifications.DialogOption`.
9191

92-
![Screenshot of a Dialog button.](./media/dialog-button.png)
92+
![Screenshot of a dialog button.](./media/dialog-button.png)
9393

94-
Additionally, you can create your own combination of buttons and default actions from:
94+
You can also create your own combination of buttons and default actions from:
9595

9696
- `Microsoft.VisualStudio.RpcContracts.Notifications.DialogButton`
9797

@@ -114,71 +114,71 @@ Additionally, you can create your own combination of buttons and default actions
114114
```csharp
115115
public enum DialogResult
116116
{
117-
// The dialog was closed via the System.Threading.CancellationToken or using an
117+
// The dialog was closed via the System.Threading.CancellationToken or by using an
118118
// action provided by the Microsoft.Visual Studio.RpcContracts.RemoteUI.IRemoteUserControl
119119
// content.
120120
None,
121-
// The user clicked the Close button.
121+
// The user selected the Close button.
122122
Close,
123-
// The user clicked the OK button.
123+
// The user selected the OK button.
124124
OK,
125-
// The user clicked the Cancel button, or clicked the nonclient close button, or
126-
// pressed the Esc key.
125+
// The user selected the Cancel button, or selected the nonclient close button, or
126+
// selected the Esc key.
127127
Cancel
128128
}
129129
```
130130

131131
### Examples
132132

133-
Adding a cancel button:
133+
Add a Cancel button:
134134

135135
```csharp
136136
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
137137
{
138-
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
139-
#pragma warning disable CA2000 // Dispose objects before losing scope
138+
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension.
139+
#pragma warning disable CA2000 // Dispose of objects before losing scope.
140140
var control = new MyDialogControl(null);
141-
#pragma warning restore CA2000 // Dispose objects before losing scope
141+
#pragma warning restore CA2000 // Dispose of objects before losing scope.
142142
143143
await this.Extensibility.Shell().ShowDialogAsync(control, DialogOption.OKCancel, cancellationToken);
144144
}
145145
```
146146

147-
Having no dialog buttons:
147+
No dialog buttons:
148148

149149
```csharp
150150
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
151151
{
152-
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
153-
#pragma warning disable CA2000 // Dispose objects before losing scope
152+
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension.
153+
#pragma warning disable CA2000 // Dispose of objects before losing scope.
154154
var control = new MyDialogControl(null);
155-
#pragma warning restore CA2000 // Dispose objects before losing scope
155+
#pragma warning restore CA2000 // Dispose of objects before losing scope.
156156
157157
await this.Extensibility.Shell().ShowDialogAsync(control, new DialogOption(DialogButton.None, DialogResult.None), cancellationToken);
158158
}
159159
```
160160

161161
## Get the dialog result
162162

163-
If you need to know whether a user affirmatively closed a dialog or dismissed it, you can await the call to [`ShowDialogAsync`](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility.showdialogasync), and it will return a `Microsoft.VisualStudio.RpcContracts.Notifications.DialogResult`, which represents the action taken by the user.
163+
If you need to know whether a user affirmatively closed a dialog or dismissed it, you can await the call to [`ShowDialogAsync`](/dotnet/api/microsoft.visualstudio.extensibility.shell.shellextensibility.showdialogasync). It returns `Microsoft.VisualStudio.RpcContracts.Notifications.DialogResult`, which represents the action taken by the user.
164164

165165
```csharp
166166
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
167167
{
168-
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension
169-
#pragma warning disable CA2000 // Dispose objects before losing scope
168+
// Ownership of the RemoteUserControl is transferred to Visual Studio, so it shouldn't be disposed by the extension.
169+
#pragma warning disable CA2000 // Dispose of objects before losing scope.
170170
var control = new MyDialogControl(null);
171-
#pragma warning restore CA2000 // Dispose objects before losing scope
171+
#pragma warning restore CA2000 // Dispose of objects before losing scope.
172172
173173
DialogResult result = await this.Extensibility.Shell().ShowDialogAsync(control, "My Dialog Title", DialogOption.OKCancel, cancellationToken);
174174

175175
if (result == DialogResult.OK)
176176
{
177-
// User clicked the OK button
177+
// The user selected the OK button.
178178
}
179179
}
180180
```
181181

182-
## Next steps
182+
## Related content
183183

184-
See the [DialogSample](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/DialogSample) sample for a full example of creating an extension with a dialog.
184+
- See [DialogSample](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/DialogSample) for a full example of how to create an extension with a dialog.

0 commit comments

Comments
 (0)