From e28b164759a16015346aa5677e04df848a4527c6 Mon Sep 17 00:00:00 2001 From: James Crutchley Date: Sun, 2 Aug 2026 11:46:15 -0700 Subject: [PATCH] Update Snackbar and Toast documentation to clarify Windows packaging requirements --- docs/maui/alerts/snackbar.md | 3 +++ docs/maui/alerts/toast.md | 4 +++- docs/maui/includes/toast-snackbar-setup.md | 11 +++++++---- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/maui/alerts/snackbar.md b/docs/maui/alerts/snackbar.md index 318d9ec9..8b5d7375 100644 --- a/docs/maui/alerts/snackbar.md +++ b/docs/maui/alerts/snackbar.md @@ -73,6 +73,9 @@ await MyVisualElement.DisplaySnackbar("Snackbar is awesome. It is anchored to My > [!WARNING] > `Snackbar` on Windows can't be anchored to `VisualElement` and is always displayed as a default Windows Notification. +> [!IMPORTANT] +> `Snackbar` on Windows requires a **packaged (MSIX) app**. The underlying `AppNotificationManager` API is only available within a packaged app identity. If your app is not packaged, constructing a `Snackbar` will throw an `InvalidOperationException` with a descriptive message and a `HelpLink` pointing to this documentation. For unpackaged apps, consider using an alternative notification mechanism such as in-app UI alerts. + `SnackBar` contains two events: - `public static event EventHandler Shown` diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index b9788399..679bfb76 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -19,7 +19,7 @@ To access the `Toast` functionality, the following platform specific setup is re ## Syntax -### C# +### C # To display `Toast`, first create it using the static method `Toast.Make()`, then display it using its method `Show()`. @@ -40,6 +40,7 @@ await toast.Show(cancellationTokenSource.Token); When calling `Toast.Make()`, its parameter `string text` is required. All other parameters are optional. Its optional parameter `ToastDuration duration` uses the default duration of `ToastDuration.Short`. Its optional parameter `double fontSize` uses the default value of `14.0`. The following screenshot shows the resulting Toast: + ### [Android](#tab/toast-preview-android) ![Screenshot of an Toast on Android](../images/alerts/toast-android.gif "Toast on Android") @@ -90,3 +91,4 @@ You can find the source code for `Toast` over on the [.NET MAUI Community Toolki 1. The API allows override existing methods with your own implementation or creating your own Toast, by implementing `IToast` interface. 2. Toast is implemented on Android, created by Google. Other platforms use a custom-implemented container (`UIView` for iOS and MacCatalyst, `ToastNotification` on Windows). 3. Toast on Tizen can't be customized with its `Duration` and `TextSize` properties. +4. `Toast` on Windows requires a **packaged (MSIX) app**. The underlying `AppNotificationManager` API is only available within a packaged app identity. diff --git a/docs/maui/includes/toast-snackbar-setup.md b/docs/maui/includes/toast-snackbar-setup.md index 049eefcf..6fd3e33f 100644 --- a/docs/maui/includes/toast-snackbar-setup.md +++ b/docs/maui/includes/toast-snackbar-setup.md @@ -13,11 +13,14 @@ No setup is required. ### [Windows](#tab/windows) -When using `Snackbar` it is essential to perform the following two steps: +> [!IMPORTANT] +> `Snackbar` and `Toast` on Windows require a **packaged (MSIX) app**. The underlying Windows App SDK `AppNotificationManager` API only works within a packaged app identity. If your app is not packaged, `Snackbar` and `Toast` are not supported on Windows. + +When using `Snackbar` or `Toast` on Windows, perform the following steps: -#### 1. Enable the snackbar usage with the MauiAppBuilder +#### 1. Enable snackbar/toast usage with the MauiAppBuilder -When using the `UseMauiCommunityToolkit` make use of the `options` parameter to enable the snackbar usage on Windows as follows: +When using `UseMauiCommunityToolkit`, enable snackbar and toast support on Windows as follows: ```csharp var builder = MauiApp.CreateBuilder() @@ -27,7 +30,7 @@ var builder = MauiApp.CreateBuilder() }) ``` -The above will automatically register the required handlers by configuring lifecycle events (`OnLaunched` and `OnClosed`). +In a **packaged (MSIX)** app, this registers the required handlers by configuring lifecycle events (`OnLaunched` and `OnClosed`). In an **unpackaged** app, registration is silently skipped and a diagnostic message is emitted via `Trace.WriteLine`. #### 2. Include ToastNotification registrations in your Package.appxmanifest file