Inviare una notifica di tipo avviso popup locale da app C#Send a local toast notification from C# apps

Una notifica di tipo avviso popup è un messaggio che consente all'app di creare e consegnare all'utente mentre non si trovano attualmente all'interno dell'app.A toast notification is a message that your app can construct and deliver to your user while they are not currently inside your app.

Screenshot of a toast notification

Questa Guida introduttiva illustra la procedura per creare, distribuire e visualizzare una notifica di tipo avviso popup di Windows 10 usando contenuti avanzati e azioni interattive.This quickstart walks you through the steps to create, deliver, and display a Windows 10 toast notification using rich content and interactive actions. Questa Guida introduttiva usa le notifiche locali, che rappresentano la notifica più semplice da implementare.This quickstart uses local notifications, which are the simplest notification to implement. Tutti i tipi di app (WPF, UWP, WinForms, console) possono inviare notifiche.All types of apps (WPF, UWP, WinForms, console) can send notifications!

Importante

Se si sta scrivendo un'app C++, vedere la documentazione di c++ UWP o c++ WRL .If you're writing a C++ app, please see the C++ UWP or C++ WRL documentation.

Passaggio 1: installare il pacchetto NuGetStep 1: Install NuGet package

All'interno della soluzione di Visual Studio fare clic con il pulsante destro del mouse sul progetto, scegliere "Gestisci pacchetti NuGet" e cercare e installare il Microsoft.Toolkit.Uwp.Notifications pacchetto NuGet versione 7,0 o successiva.Within your Visual Studio solution, right click your project, click "Manage NuGet Packages..." and search for and install the Microsoft.Toolkit.Uwp.Notifications NuGet package version 7.0 or greater.

Importante

.NET Framework le app desktop che usano ancora packages.config devono eseguire la migrazione a PackageReference. in caso contrario, non verrà fatto riferimento agli SDK di Windows 10..NET Framework desktop apps that still use packages.config must migrate to PackageReference, otherwise the Windows 10 SDKs won't be referenced correctly. Nel progetto fare clic con il pulsante destro del mouse su "References" e scegliere "migrate packages.config to PackageReference".In your project, right-click on "References", and click "Migrate packages.config to PackageReference".

Le app WPF di .NET Core 3,0 devono eseguire l'aggiornamento a .NET Core 3,1, in caso contrario le API saranno assenti..NET Core 3.0 WPF apps must update to .NET Core 3.1, otherwise the APIs will be absent.

L'esempio di codice utilizzerà il pacchetto.Our code sample will use this package. Questo pacchetto consente di creare notifiche di tipo avviso popup senza usare XML e consente inoltre alle app desktop di inviare i popup.This package allows you to create toast notifications without using XML, and also allows desktop apps to send toasts.

Passaggio 2: inviare un avviso popupStep 2: Send a toast

In Windows 10, il contenuto della notifica di tipo avviso popup viene descritto utilizzando un linguaggio adattivo che consente una grande flessibilità con la modalità di aspetto della notifica.In Windows 10, your toast notification content is described using an adaptive language that allows great flexibility with how your notification looks. Per ulteriori informazioni, vedere la documentazione del contenuto di tipo avviso popup.For more information, see the toast content documentation.

Si inizierà con una semplice notifica basata su testo.We'll start with a simple text-based notification. Costruire il contenuto della notifica (usando la libreria di notifiche) e visualizzare la notifica.Construct the notification content (using the Notifications library), and show the notification! Si noti che lo spazio dei nomi è Microsoft.Toolkit.Uwp.Notifications .Note that the namespace is Microsoft.Toolkit.Uwp.Notifications.

Simple text notification
// Requires Microsoft.Toolkit.Uwp.Notifications NuGet package
new ToastContentBuilder()
    .AddArgument("action", "viewConversation")
    .AddArgument("conversationId", 9813)
    .AddText("Andrew sent you a picture")
    .AddText("Check this out, The Enchantments in Washington!")
    .Show();

Provare a eseguire questo codice. viene visualizzata la notifica.Try running this code and you should see the notification appear!

Passaggio 3: gestione dell'attivazioneStep 3: Handling activation

Dopo aver visualizzato una notifica, è probabile che sia necessario gestire l'utente facendo clic sulla notifica, ovvero attivando il contenuto specifico dopo che l'utente lo fa clic, aprendo l'app in generale o eseguendo un'azione quando l'utente fa clic sulla notifica.After showing a notification, you likely need to handle the user clicking the notification (whether that means bringing up specific content after the user clicks it, opening your app in general, or performing an action when the user clicks the notification).

I passaggi per la gestione dell'attivazione sono diversi per le app UWP, desktop (MSIX) e desktop (non in pacchetto).The steps for handling activation differ for UWP, Desktop (MSIX), and Desktop (unpackaged) apps.

Quando l'utente fa clic sulla notifica o su un pulsante della notifica con attivazione in primo piano, viene richiamata l' app. XAML. cs OnActivated e gli argomenti aggiunti verranno restituiti.When the user clicks your notification (or a button on the notification with foreground activation), your app's App.xaml.cs OnActivated will be invoked, and the arguments you added will be returned.

App.xaml.csApp.xaml.cs

protected override void OnActivated(IActivatedEventArgs e)
{
    // Handle notification activation
    if (e is ToastNotificationActivatedEventArgs toastActivationArgs)
    {
        // Obtain the arguments from the notification
        ToastArguments args = ToastArguments.Parse(toastActivationArgs.Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        ValueSet userInput = toastActivationArgs.UserInput;
 
        // TODO: Show the corresponding content
    }
}

Importante

È necessario inizializzare il frame e attivare la finestra proprio come il codice OnLaunched .You must initialize your frame and activate your window just like your OnLaunched code. OnLaunched non viene chiamato se l'utente fa clic sul popup, anche se l'app è stata chiusa e viene avviata per la prima volta.OnLaunched is NOT called if the user clicks on your toast, even if your app was closed and is launching for the first time. Si consiglia spesso di combinare OnLaunched e OnActivated nel metodo personalizzato, OnLaunchedOrActivated perché la stessa inizializzazione deve essere eseguita in entrambi.We often recommend combining OnLaunched and OnActivated into your own OnLaunchedOrActivated method since the same initialization needs to occur in both.

Passaggio 4: gestione della disinstallazioneStep 4: Handling uninstallation

Non è necessario eseguire alcuna operazione.You don't need to do anything! Quando le app UWP vengono disinstallate, tutte le notifiche e tutte le altre risorse correlate vengono pulite automaticamente.When UWP apps are uninstalled, all notifications and any other related resources are automatically cleaned up.

Aggiunta di immaginiAdding images

È possibile aggiungere contenuti avanzati alle notifiche.You can add rich content to notifications. Verranno aggiunte un'immagine inline e un profilo (override del logo dell'app).We'll add an inline image and a profile (app logo override) image.

Nota

Le immagini possono essere usate dal pacchetto dell'app, dall'archiviazione locale dell'app o dal Web.Images can be used from the app's package, the app's local storage, or from the web. A partire dall'aggiornamento Fall Creators, le immagini Web possono avere fino a 3 MB di connessioni normali e 1 MB per le connessioni a consumo.As of the Fall Creators Update, web images can be up to 3 MB on normal connections and 1 MB on metered connections. Nei dispositivi che non hanno ancora eseguito l'aggiornamento Fall Creators, le immagini Web non devono essere superiori a 200 KB.On devices not yet running the Fall Creators Update, web images must be no larger than 200 KB.

Importante

Le immagini http sono supportate solo nelle app UWP/MSIX/sparse con la funzionalità Internet nel manifesto.Http images are only supported in UWP/MSIX/sparse apps that have the internet capability in their manifest. le app desktop non MSIX/sparse non supportano le immagini http; è necessario scaricare l'immagine nei dati dell'app locale e farvi riferimento localmente.desktop non-MSIX/sparse apps do not support http images; you must download the image to your local app data and reference it locally.

Toast with images
// Construct the content and show the toast!
new ToastContentBuilder()
    ...

    // Inline image
    .AddInlineImage(new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    .AddAppLogoOverride(new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop.Circle)
    
    .Show();

Aggiunta di pulsanti e inputAdding buttons and inputs

È possibile aggiungere pulsanti e input per rendere le notifiche interattive.You can add buttons and inputs to make your notifications interactive. I pulsanti possono avviare l'app in primo piano, un protocollo o l'attività in background.Buttons can launch your foreground app, a protocol, or your background task. Si aggiungerà una casella di testo di risposta, un pulsante "like" e un pulsante "View" per aprire l'immagine.We'll add a reply text box, a "Like" button, and a "View" button that opens the image.

Screenshot of a toast notification with inputs and buttons
int conversationId = 384928;

// Construct the content
new ToastContentBuilder()
    .AddArgument("conversationId", conversationId)
    ...

    // Text box for replying
    .AddInputTextBox("tbReply", placeHolderContent: "Type a response")

    // Buttons
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("Like")
        .AddArgument("action", "like")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("View")
        .AddArgument("action", "viewImage")
        .AddArgument("imageUrl", image.ToString()))
    
    .Show();

L'attivazione dei pulsanti in primo piano viene gestita in modo analogo al corpo del popup principale (verrà chiamato l'app. XAML. cs OnActivated).The activation of foreground buttons are handled in the same way as the main toast body (your App.xaml.cs OnActivated will be called).

Si noti che gli argomenti aggiunti all'avviso popup di primo livello, ad esempio l'ID di conversazione, verranno restituiti anche quando si fa clic sui pulsanti, purché i pulsanti usino l'API metodi AddArgument come illustrato in precedenza (se si assegnano argomenti personalizzati in un pulsante, gli argomenti di primo livello non verranno inclusi).Note that arguments added to the top-level toast (like conversation ID) will also be returned when the buttons are clicked, as long as buttons use the AddArgument API as seen above (if you custom assign arguments on a button, the top-level arguments won't be included).

Gestione dell'attivazione in backgroundHandling background activation

Quando si specifica l'attivazione in background sul proprio avviso popup (o su un pulsante all'interno del popup), l'attività in background verrà eseguita anziché attivare l'app in primo piano.When you specify background activation on your toast (or on a button inside the toast), your background task will be executed instead of activating your foreground app.

Per altre informazioni sulle attività in background, vedere supportare l'app con attività in background.For more information on background tasks, please see Support your app with background tasks.

Se la destinazione è Build 14393 o versione successiva, è possibile usare attività in background in-process, che semplificano notevolmente le operazioni.If you are targeting build 14393 or higher, you can use in-process background tasks, which greatly simplify things. Si noti che le attività in background in-process non verranno eseguite in versioni precedenti di Windows.Note that in-process background tasks will fail to run on older versions of Windows. In questo esempio di codice verrà utilizzata un'attività in background in-process.We'll use an in-process background task in this code sample.

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

Quindi, nel file app. XAML. cs, eseguire l'override del metodo OnBackgroundActivated.Then in your App.xaml.cs, override the OnBackgroundActivated method. È quindi possibile recuperare gli argomenti predefiniti e l'input dell'utente, in modo analogo all'attivazione in primo piano.You can then retrieve the pre-defined arguments and user input, similar to the foreground activation.

App.xaml.csApp.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();
 
    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                ToastArguments arguments = ToastArguments.Parse(details.Argument);
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }
 
    deferral.Complete();
}

Impostare una data di scadenzaSet an expiration time

In Windows 10, tutte le notifiche di tipo avviso popup vengono inserite nel centro operativo dopo che sono state ignorate o ignorate dall'utente, in modo che gli utenti possano esaminare la notifica dopo che il popup è andato.In Windows 10, all toast notifications go in Action Center after they are dismissed or ignored by the user, so users can look at your notification after the popup is gone.

Tuttavia, se il messaggio nella notifica è pertinente solo per un periodo di tempo, è necessario impostare una data di scadenza per la notifica di tipo avviso popup in modo che gli utenti non visualizzino informazioni non aggiornate dall'app.However, if the message in your notification is only relevant for a period of time, you should set an expiration time on the toast notification so the users do not see stale information from your app. Se ad esempio una promozione è valida solo per 12 ore, impostare la scadenza su 12 ore.For example, if a promotion is only valid for 12 hours, set the expiration time to 12 hours. Nel codice riportato di seguito, l'ora di scadenza è impostata su 2 giorni.In the code below, we set the expiration time to be 2 days.

Nota

L'ora di scadenza predefinita e massima per le notifiche di tipo avviso popup locale è di 3 giorni.The default and maximum expiration time for local toast notifications is 3 days.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("Expires in 2 days...")
    .Show(toast =>
    {
        toast.ExpirationTime = DateTime.Now.AddDays(2);
    });

Fornire una chiave primaria per il avviso popupProvide a primary key for your toast

Se si vuole rimuovere o sostituire la notifica inviata a livello di codice, è necessario usare la proprietà Tag (e, facoltativamente, la proprietà Group) per fornire una chiave primaria per la notifica.If you want to programmatically remove or replace the notification you send, you need to use the Tag property (and optionally the Group property) to provide a primary key for your notification. Quindi, è possibile usare questa chiave primaria in futuro per rimuovere o sostituire la notifica.Then, you can use this primary key in the future to remove or replace the notification.

Per ulteriori dettagli sulla sostituzione o la rimozione di notifiche di tipo avviso popup già recapitate, vedere Guida introduttiva: gestione delle notifiche di tipo avviso popup nel centro operativo (XAML).To see more details on replacing/removing already delivered toast notifications, please see Quickstart: Managing toast notifications in action center (XAML).

Il tag e il gruppo combinati agiscono come chiave primaria composta.Tag and Group combined act as a composite primary key. Il gruppo è l'identificatore più generico, in cui è possibile assegnare gruppi come "wallPosts", "messages", "friendRequests" e così via. Quindi il tag deve identificare in modo univoco la notifica dal gruppo.Group is the more generic identifier, where you can assign groups like "wallPosts", "messages", "friendRequests", etc. And then Tag should uniquely identify the notification itself from within the group. Usando un gruppo generico, è quindi possibile rimuovere tutte le notifiche da tale gruppo usando l' API removegroup.By using a generic group, you can then remove all notifications from that group by using the RemoveGroup API.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("New post on your wall!")
    .Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Cancellare le notificheClear your notifications

Le app sono responsabili della rimozione e della cancellazione delle proprie notifiche.Apps are responsible for removing and clearing their own notifications. Quando l'app viene avviata, le notifiche non vengono cancellate automaticamente.When your app is launched, we do NOT automatically clear your notifications.

Windows eliminerà automaticamente una notifica solo se l'utente fa clic esplicitamente sulla notifica.Windows will only automatically remove a notification if the user explicitly clicks the notification.

Ecco un esempio di ciò che un'app di messaggistica deve eseguire...Here's an example of what a messaging app should do…

  1. L'utente riceve più popup sui nuovi messaggi in una conversazioneUser receives multiple toasts about new messages in a conversation
  2. L'utente tocca uno di questi toast per aprire la conversazioneUser taps one of those toasts to open the conversation
  3. L'app apre la conversazione e quindi Cancella tutti i toast per la conversazione (usando removegroup nel gruppo fornito dall'app per la conversazione)The app opens the conversation and then clears all toasts for that conversation (by using RemoveGroup on the app-supplied group for that conversation)
  4. Il centro operativo dell'utente ora riflette correttamente lo stato di notifica, perché non sono presenti notifiche non aggiornate per la conversazione rimanente nel centro operativo.User's Action Center now properly reflects the notification state, since there are no stale notifications for that conversation left in Action Center.

Per informazioni sulla cancellazione di tutte le notifiche o sulla rimozione di notifiche specifiche, vedere Guida introduttiva: gestione delle notifiche di tipo avviso popup nel centro operativo (XAML).To learn about clearing all notifications or removing specific notifications, see Quickstart: Managing toast notifications in action center (XAML).

ToastNotificationManagerCompat.History.Clear();

RisorseResources