Skip to content

Commit f911355

Browse files
learn-build-service-prod[bot]learn-build-service-prod[bot]
authored
Merge pull request #5664 from MicrosoftDocs/main
Auto Publish – main to live - 2025-08-06 05:00 UTC
2 parents df7d82c + c620bb4 commit f911355

File tree

2 files changed

+122
-32
lines changed

2 files changed

+122
-32
lines changed

‎hub/apps/design/controls/dialogs-and-flyouts/dialogs.md

Lines changed: 118 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: Dialogs display transient UI elements that appear when the user req
33
title: Dialog controls
44
label: Dialogs
55
template: detail.hbs
6-
ms.date: 02/26/2025
6+
ms.date: 08/05/2025
77
ms.topic: article
88
ms.assetid: ad6affd9-a3c0-481f-a237-9a1ecd561be8
99
doc-status: Published
@@ -39,20 +39,20 @@ For recommendations on when to use a dialog vs. when to use a flyout (a similar
3939
- The "do it" action button(s) should appear as the leftmost buttons. The safe, nondestructive action should appear as the rightmost button.
4040
- You may optionally choose to differentiate one of the three buttons as the dialog's default button. Use the DefaultButton API to differentiate one of the buttons.
4141
- Don't use dialogs for errors that are contextual to a specific place on the page, such as validation errors (in password fields, for example), use the app's canvas itself to show inline errors.
42-
- Use the [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog) to build your dialog experience. Don't use the deprecated MessageDialog API.
42+
- Use the [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog) to build your dialog experience. Don't use the deprecated MessageDialog API.
4343

4444
## Create a dialog
4545

4646
> [!div class="checklist"]
4747
>
48-
> - **Important APIs**: [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog)
48+
> - **Important APIs**: [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog)
4949
5050
> [!div class="nextstepaction"]
5151
> [Open the WinUI 3 Gallery app and see the ContentDialog in action](winui3gallery:/item/ContentDialog)
5252
5353
[!INCLUDE [winui-3-gallery](../../../../includes/winui-3-gallery.md)]
5454

55-
To create a dialog, you use the [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog). You can create a dialog in code or markup. Although its usually easier to define UI elements in XAML, in the case of a simple dialog, it's actually easier to just use code. This example creates a dialog to notify the user that there's no WiFi connection, and then uses the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog.ShowAsync) method to display it.
55+
To create a dialog, you use the [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog). You can create a dialog in code or markup. Although its usually easier to define UI elements in XAML, in the case of a simple dialog, it can be easier to just use code. This example creates a dialog to notify the user that there's no WiFi connection, and then uses the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.showasync) method to display it.
5656

5757
```csharp
5858
private async void DisplayNoWifiDialog()
@@ -68,9 +68,96 @@ private async void DisplayNoWifiDialog()
6868
}
6969
```
7070

71-
When the user clicks a dialog button, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog.ShowAsync) method returns a [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialogResult) to let you know which button the user clicks.
71+
If your content dialog is more complex, it can be easier to create it with XAML. You can either create it in the XAML file for your page, or you can create a subclass of ContentDialog with it's own .xaml and code-behind file. For complete examples of both, see the [ContentDialog] class reference.
7272

73-
The dialog in this example asks a question and uses the returned [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialogResult) to determine the user's response.
73+
There is no item template in Visual Studio to create a new content dialog file, but you can use the Blank Page template and modify the resulting files to create a dialog.
74+
75+
**To create a new content dialog with XAML and code-behind**
76+
77+
1. In the **Solution Explorer** pane, right-click on the project name and select **Add > New Item...**
78+
1. In the **Add New Item** dialog, select **WinUI** in the template list on the left-side of the window.
79+
1. Select the **Blank Page** template.
80+
1. Name the file. (In this example, the file is named `XamlContentDialog`).
81+
1. Press **Add**.
82+
83+
In the new .xaml file, change the opening and closing Page tags to Content Dialog.
84+
85+
```xaml
86+
<!--
87+
<Page
88+
x:Class="ContentDialog_WinUI3.XamlContentDialog"
89+
...>
90+
91+
</Page>
92+
-->
93+
94+
<ContentDialog
95+
x:Class="ContentDialog_WinUI3.XamlContentDialog"
96+
...>
97+
98+
</ContentDialog>
99+
```
100+
101+
In the .xaml.cs file, make your class inherit from ContentDialog instead of Page.
102+
103+
```csharp
104+
// public sealed partial class XamlContentDialog : Page
105+
106+
public sealed partial class XamlContentDialog : ContentDialog
107+
```
108+
109+
### Show the dialog
110+
111+
To show a dialog, call the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.showasync) method.
112+
113+
```csharp
114+
XamlContentDialog xamlDialog = new XamlContentDialog()
115+
{
116+
XamlRoot = this.XamlRoot
117+
};
118+
await xamlDialog.ShowAsync();
119+
```
120+
121+
> [!WARNING]
122+
> There can only be one ContentDialog open per window at a time. Attempting to open two content dialogs will throw an exception.
123+
124+
#### Set the XamlRoot
125+
126+
When you show a ContentDialog, you need to manually set the [XamlRoot](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.xamlroot) of the dialog to the root of the XAML host. To do so, set the ContentDialog's XamlRoot property to the same XamlRoot as an element already in the XAML tree.
127+
128+
If the ContentDialog is shown from a [Page](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page), you can set the ContentDialog's XamlRoot property to the XamlRoot of the Page as shown in the previous example.
129+
130+
[Window](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.window) doesn't have a XamlRoot property, so if the dialog is shown from a Window, set the dialog's XamlRoot property to that of the Window's root content element, as shown here.
131+
132+
```xaml
133+
<Window
134+
... >
135+
<Grid x:Name="rootPanel">
136+
137+
</Grid>
138+
</Window>
139+
``````
140+
141+
```csharp
142+
private async void DisplayNoWifiDialog()
143+
{
144+
ContentDialog noWifiDialog = new ContentDialog
145+
{
146+
XamlRoot = rootPanel.XamlRoot,
147+
Title = "No wifi connection",
148+
Content = "Check your connection and try again.",
149+
CloseButtonText = "Ok"
150+
};
151+
152+
ContentDialogResult result = await noWifiDialog.ShowAsync();
153+
}
154+
```
155+
156+
## Respond to dialog buttons
157+
158+
When the user clicks a dialog button, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.ShowAsync) method returns a [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialogResult) to let you know which button the user clicks.
159+
160+
The dialog in this example asks a question and uses the returned [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialogResult) to determine the user's response.
74161

75162
```csharp
76163
private async void DisplayDeleteFileDialog()
@@ -101,7 +188,9 @@ private async void DisplayDeleteFileDialog()
101188

102189
## Provide a safe action
103190

104-
Because dialogs block user interaction, and because buttons are the primary mechanism for users to dismiss the dialog, ensure that your dialog contains at least one "safe" and nondestructive button such as "Close" or "Got it!". **All dialogs should contain at least one safe action button to close the dialog.** This ensures that the user can confidently close the dialog without performing an action.<br>![An one button dialog](../images/dialogs/dialog_RS2_one_button.png)
191+
Because dialogs block user interaction, and because buttons are the primary mechanism for users to dismiss the dialog, ensure that your dialog contains at least one "safe" and nondestructive button such as "Close" or "Got it!". **All dialogs should contain at least one safe action button to close the dialog.** This ensures that the user can confidently close the dialog without performing an action.
192+
193+
![A one button dialog](../images/dialogs/dialog_RS2_one_button.png)
105194

106195
```csharp
107196
private async void DisplayNoWifiDialog()
@@ -177,16 +266,16 @@ Use the ContentDialog.CloseButton API to create this button. This allows you to
177266
- The user presses the ESC button on the keyboard.
178267
- The user presses Gamepad B.
179268

180-
When the user clicks a dialog button, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog.ShowAsync) method returns a [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialogResult) to let you know which button the user clicks. Pressing on the CloseButton returns ContentDialogResult.None.
269+
When the user clicks a dialog button, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.ShowAsync) method returns a [ContentDialogResult](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialogResult) to let you know which button the user clicks. Pressing on the CloseButton returns ContentDialogResult.None.
181270

182271
### PrimaryButton and SecondaryButton
183272

184273
In addition to the CloseButton, you may optionally present the user with one or two action buttons related to the main instruction.
185274
Leverage PrimaryButton for the first "do it" action, and SecondaryButton for the second "do it" action. In three-button dialogs, the PrimaryButton generally represents the affirmative "do it" action, while the SecondaryButton generally represents a neutral or secondary "do it" action.
186275
For example, an app may prompt the user to subscribe to a service. The PrimaryButton as the affirmative "do it" action would host the Subscribe text, while the SecondaryButton as the neutral "do it" action would host the Try it text. The CloseButton would allow the user to cancel without performing either action.
187276

188-
When the user clicks on the PrimaryButton, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog.ShowAsync) method returns ContentDialogResult.Primary.
189-
When the user clicks on the SecondaryButton, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog.ShowAsync) method returns ContentDialogResult.Secondary.
277+
When the user clicks on the PrimaryButton, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.ShowAsync) method returns ContentDialogResult.Primary.
278+
When the user clicks on the SecondaryButton, the [ShowAsync](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog.ShowAsync) method returns ContentDialogResult.Secondary.
190279

191280
![A three button dialog](../images/dialogs/dialog_RS2_three_button.png)
192281

@@ -235,13 +324,27 @@ A typical confirmation dialog has two buttons: an affirmation ("OK") button and
235324
</li>
236325
</ul>
237326

238-
> Some platforms put the affirmation button on the right instead of the left. So why do we recommend putting it on the left? If you assume that the majority of users are right-handed and they hold their phone with that hand, it's actually more comfortable to press the affirmation button when it's on the left, because the button is more likely to be within the user's thumb-arc. Buttons on the right-side of the screen require the user to pull their thumb inward into a less-comfortable position.
239327

240-
## ContentDialog in AppWindow or Xaml Islands
328+
329+
## UWP and WinUI 2
330+
331+
[!INCLUDE [uwp-winui2-note](../../../../includes/uwp-winui-2-note.md)]
332+
333+
APIs for this control exist in the [Windows.UI.Xaml.Controls](/uwp/api/Windows.UI.Xaml.Controls) namespace.
334+
335+
> [!div class="checklist"]
336+
>
337+
> - **UWP APIs:** [ContentDialog class](/uwp/api/Windows.UI.Xaml.Controls.ContentDialog)
338+
> - [Open the WinUI 2 Gallery app and see the ContentDialog in action](winui2gallery:/item/ContentDialog). [!INCLUDE [winui-2-gallery](../../../../includes/winui-2-gallery.md)]
339+
340+
We recommend using the latest [WinUI 2](/windows/uwp/get-started/winui2/) to get the most current styles and templates for all controls. WinUI 2.2 or later includes a new template for this control that uses rounded corners. For more info, see [Corner radius](../../style/rounded-corner.md).
341+
342+
343+
### ContentDialog in AppWindow or Xaml Islands
241344

242345
> NOTE: This section applies only to apps that target Windows 10, version 1903 or later. AppWindow and XAML Islands are not available in earlier versions. For more info about versioning, see [Version adaptive apps](/windows/uwp/debug-test-perf/version-adaptive-apps).
243346
244-
By default, content dialogs display modally relative to the root [ApplicationView](/uwp/api/windows.ui.viewmanagement.applicationview). When you use ContentDialog inside of either an [AppWindow](/uwp/api/windows.ui.windowmanagement.appwindow) or a [XAML Island](../../../desktop/modernize/xaml-islands/xaml-islands.md), you need to manually set the [XamlRoot](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.xamlroot) on the dialog to the root of the XAML host.
347+
By default, content dialogs display modally relative to the root [ApplicationView](/uwp/api/windows.ui.viewmanagement.applicationview). When you use ContentDialog inside of either an [AppWindow](/uwp/api/windows.ui.windowmanagement.appwindow) or a [XAML Island](../../../desktop/modernize/xaml-islands/xaml-islands.md), you need to manually set the [XamlRoot](/uwp/api/windows.ui.xaml.uielement.xamlroot) on the dialog to the root of the XAML host.
245348

246349
To do so, set the ContentDialog's XamlRoot property to the same XamlRoot as an element already in the AppWindow or XAML Island, as shown here.
247350

@@ -267,24 +370,11 @@ private async void DisplayNoWifiDialog()
267370
```
268371

269372
> [!WARNING]
270-
> There can only be one ContentDialog open per thread at a time. Attempting to open two ContentDialogs will throw an exception, even if they are attempting to open in separate AppWindows.
271-
272-
## UWP and WinUI 2
273-
274-
[!INCLUDE [uwp-winui2-note](../../../../includes/uwp-winui-2-note.md)]
275-
276-
APIs for this control exist in the [Windows.UI.Xaml.Controls](/uwp/api/Windows.UI.Xaml.Controls) namespace.
277-
278-
> [!div class="checklist"]
279-
>
280-
> - **UWP APIs:** [ContentDialog class](/uwp/api/Windows.UI.Xaml.Controls.ContentDialog)
281-
> - [Open the WinUI 2 Gallery app and see the ContentDialog in action](winui2gallery:/item/ContentDialog). [!INCLUDE [winui-2-gallery](../../../../includes/winui-2-gallery.md)]
282-
283-
We recommend using the latest [WinUI 2](/windows/uwp/get-started/winui2/) to get the most current styles and templates for all controls. WinUI 2.2 or later includes a new template for this control that uses rounded corners. For more info, see [Corner radius](../../style/rounded-corner.md).
373+
> There can only be one ContentDialog open per thread at a time. Attempting to open two ContentDialogs will throw an exception, even if they are attempting to open in separate instances of AppWindow.
284374
285375
## Related articles
286376

287377
- [Tooltips](../tooltips.md)
288378
- [Menus and context menu](../menus.md)
289379
- [Flyout class](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.Flyout)
290-
- [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.UI.Xaml.Controls.ContentDialog)
380+
- [ContentDialog class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog)

‎uwp/security/macs-hashes-and-signatures.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,10 @@ namespace SampleMacAlgorithmProvider
124124

125125
A cryptographic hash function takes an arbitrarily long block of data and returns a fixed-size bit string. Hash functions are typically used when signing data. Because most public key signature operations are computationally intensive, it is typically more efficient to sign (encrypt) a message hash than it is to sign the original message. The following procedure represents a common, albeit simplified, scenario:
126126

127-
- Bob and Alice share a secret key and agree on a MAC function to use.
128-
- Bob creates a message and inputs the message and the secret key into a MAC function to retrieve a MAC value.
129-
- Bob sends the \[unencrypted\] message and the MAC value to Alice over a network.
130-
- Alice uses the secret key and the message as input to the MAC function. She compares the generated MAC value to the MAC value sent by Bob. If they are the same, the message was not changed in transit.
127+
- Alice has a public/private key pair and wants to send a signed message to Bob.
128+
- Alice creates a message and calculates a hash of the message using a hash function.
129+
- Alice signs the hash using her private key and sends the \[unencrypted\] message and the signature to Bob over a network.
130+
- Bob calculates a hash of the received message using the same hash function. He then uses Alice's public key to decrypt the signature and compares it to the calculated hash. If they are the same, the message was not changed in transit and came from Alice.
131131

132132
Note that Alice sent an unencrypted message. Only the hash was encrypted. The procedure ensures only that the original message was not altered and, by using Alice's public key, that the message hash was signed by someone with access to Alice's private key, presumably Alice.
133133

0 commit comments

Comments
 (0)