Condividi tramite

Guida introduttiva: Usare le notifiche delle app con il SDK per app di Windows

Cattura dello schermo che mostra una notifica dell'applicazione sopra la barra delle applicazioni. La notifica è un promemoria per un evento. Vengono visualizzati il nome dell'applicazione, il nome dell'evento, l'ora dell'evento e il luogo dell'evento. Un input di selezione visualizza il valore attualmente selezionato,

In questa guida introduttiva si creerà un'app WinUI che invia e risponde alle notifiche delle app locali usando il SDK per app di Windows.

Per le app di esempio complete che implementano le notifiche delle app, vedi il repository SDK per app di Windows Samples in GitHub.

Important

Le notifiche delle app non sono supportate per le app con privilegi elevati (amministratore).

Prerequisites

  • Installare Visual Studio 2022 (v17.6+)
  • Includere il workload C++ per lo sviluppo C++, o i workload .NET per lo sviluppo C#.
  • Assicurarsi che MSIX Packaging Tools sia selezionato per lo sviluppo desktop .NET.
  • Assicurarsi che sia selezionato Windows Sviluppo di applicazioni.
  • Assicurarsi che sia selezionato lo sviluppo di applicazioni dell'interfaccia utente di Windows.

Per ulteriori informazioni sulla gestione dei carichi di lavoro in Visual Studio, vedere Modificare i carichi di lavoro, i componenti e i pacchetti linguistici di Visual Studio. Per altre informazioni su come iniziare a usare WinUI, vedere Introduzione a WinUI. Per aggiungere il SDK per app di Windows a un progetto esistente, vedere Usare il SDK per app di Windows in un progetto esistente.

Creare un nuovo progetto di app WinUI in Visual Studio

  1. In Visual Studio creare un nuovo progetto.
  2. Nella finestra di dialogo Crea un nuovo progetto impostare il filtro del linguaggio su "C#" o "C++" e il filtro della piattaforma su "WinUI", quindi selezionare il modello di progetto "App vuota, In pacchetto (WinUI 3 in Desktop)".
  3. Denominare il nuovo progetto "AppNotificationsExample".

Inviare una notifica dell'app locale

In questa sezione si aggiungerà un pulsante all'app che invia una notifica locale dell'app quando si clicca su. La notifica includerà il contenuto di testo e un'immagine del logo dell'app. Si aggiungeranno anche due caselle di testo di sola lettura che visualizzeranno gli argomenti di attivazione quando l'utente fa clic sulla notifica.

Aggiungere prima di tutto un controllo Button e due controlli TextBox al controllo MainWindow.xaml:

<!-- MainWindow.xaml -->
<Button x:Name="SendNotificationButton" Content="Send App Notification" Click="SendNotificationButton_Click"/>

<TextBlock Text="Activation arguments:" FontWeight="SemiBold" Margin="0,12,0,0"/>
<TextBox x:Name="ActionTextBox" Header="action" IsReadOnly="True" PlaceholderText="(none)"/>
<TextBox x:Name="ExampleEventIdTextBox" Header="exampleEventId" IsReadOnly="True" PlaceholderText="(none)"/>

Le API di notifica dell'app si trovano nei namespace Microsoft.Windows.AppNotifications e Microsoft.Windows.AppNotifications.Builder. Aggiungere i riferimenti seguenti al progetto:

// MainWindow.xaml.cs
using Microsoft.Windows.AppNotifications;
using Microsoft.Windows.AppNotifications.Builder;

Ora, aggiungi il codice seguente al gestore del clic del pulsante. Questo esempio usa AppNotificationBuilder per costruire contenuto di notifica, inclusi gli argomenti che verranno passati all'app quando l'utente fa clic sulla notifica, un'immagine del logo dell'app e un testo. La notifica include anche un pulsante che illustra l'esecuzione di un'azione senza avviare l'interfaccia utente dell'app. Il metodo BuildNotification crea l'oggetto AppNotification e AppNotificationManager.Show lo visualizza all'utente.

// MainWindow.xaml.cs
private void SendNotificationButton_Click(object sender, RoutedEventArgs e)
{
    var appNotification = new AppNotificationBuilder()
        .AddArgument("action", "NotificationClick")
        .AddArgument("exampleEventId", "1234")
        .SetAppLogoOverride(new System.Uri("ms-appx:///Assets/Square150x150Logo.png"), AppNotificationImageCrop.Circle)
        .AddText("This is text content for an app notification.")
        .AddButton(new AppNotificationButton("Perform action without launching app")
            .AddArgument("action", "BackgroundAction"))
        .BuildNotification();

    AppNotificationManager.Default.Show(appNotification);
}

A questo punto, è possibile compilare ed eseguire l'app. Fare clic sul pulsante Send App Notification (Invia notifica app ) per visualizzare la notifica. Si noti che facendo clic sulla notifica non si eseguirà ancora alcuna azione, nella sezione successiva si apprenderà come gestire l'attivazione dell'app in modo che l'app possa rispondere quando un utente fa clic sulla notifica.

Note

Le notifiche delle app non sono supportate quando l'app è in esecuzione con privilegi di amministratore (con privilegi elevati). Show avrà esito negativo in modo invisibile all'utente e non verrà visualizzata alcuna notifica. Assicurati di eseguire l'app senza privilegi elevati durante il test delle notifiche.

Aggiornare il file manifesto del pacchetto dell'app

Il Package.appmanifest file fornisce i dettagli del pacchetto MSIX per un'app. Per abilitare l'avvio dell'app quando un utente interagisce con una notifica dell'app, devi aggiornare il file manifesto del pacchetto dell'app in modo che l'app sia registrata nel sistema come destinazione per l'attivazione delle notifiche dell'app. Per altre informazioni sui manifesti del pacchetto dell'app, vedi Manifesto del pacchetto dell'app.

  1. Modificare il file Package.appxmanifest facendo clic con il pulsante destro del mouse sul file in Esplora soluzioni e selezionando View Code.
  2. Aggiungere gli spazi dei nomi xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" e xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" a <Package>.
  3. Aggiungere un <desktop:Extension> elemento in <Extensions>. Impostare l'attributo Category su "windows.toastNotificationActivation" per dichiarare che l'app può essere attivata dalle notifiche dell'app.
    • Aggiungere un <desktop:ToastNotificationActivation> elemento figlio e impostare il ToastActivatorCLSID su un GUID che identificherà in modo univoco l'applicazione.
    • È possibile generare un GUID in Visual Studio passando a Tools > Crea GUID.
  4. Aggiungere un <com:Extension> elemento in <Extensions> e impostare l'attributo Category su "windows.comServer". Il file manifesto di esempio illustrato di seguito mostra la sintassi per questo elemento.
    • Aggiornare l'attributo Executable dell'elemento <com:ExeServer> con il nome eseguibile. Per questo esempio, il nome sarà "AppNotificationsExample.exe".
    • Specificare Arguments="----AppNotificationActivated:" per assicurarsi che SDK per app di Windows possa elaborare il payload della notifica come tipo AppNotification.
    • Impostare l'attributo Id dell'elemento <com:Class> sullo stesso GUID usato per l'attributo ToastActivatorCLSID .
<!--package.appxmanifest-->

<Package
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

        <!--Specify which CLSID to activate when notification is clicked-->   
        <desktop:Extension Category="windows.toastNotificationActivation">
          <desktop:ToastNotificationActivation ToastActivatorCLSID="replaced-with-your-guid-C173E6ADF0C3" />
        </desktop:Extension>

        <!--Register COM CLSID-->    
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="SampleApp.exe" DisplayName="SampleApp" Arguments="----AppNotificationActivated:">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" />
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>
    
      </Extensions>
    </Application>
  </Applications>
 </Package>

Gestire l'attivazione da una notifica dell'app

Quando un utente fa clic su una notifica dell'app o su un pulsante all'interno di una notifica, l'app deve rispondere in modo appropriato. Esistono due scenari di attivazione comuni:

  1. Avvia con l'interfaccia utente : l'utente fa clic sul corpo della notifica e l'app deve avviare o venire in primo piano, visualizzando il contenuto pertinente.
  2. Azione in background : l'utente fa clic su un pulsante nella notifica che attiva un'azione (ad esempio l'invio di una risposta) senza mostrare alcuna interfaccia utente dell'app.

Per supportare entrambi gli scenari, il flusso di attivazione dell'app deve creare la finestra principale in OnLaunched ma non attivarla immediatamente. Registrare invece l'evento AppNotificationManager.NotificationInvoked , chiamare AppNotificationManager.Register e quindi selezionare AppInstance.GetActivatedEventArgs per determinare se l'app è stata avviata da una notifica o da un avvio normale. Se l'avvio è stato attivato da una notifica, il codice può esaminare gli argomenti di notifica e decidere se visualizzare la finestra o gestire l'azione in modo invisibile all'utente e uscire.

L'evento NotificationInvoked gestisce i clic che si verificano mentre l'app è già in esecuzione. Quando l'app non è in esecuzione, Windows avvia l'app tramite l'attivazione COM e il tipo di attivazione viene segnalato come Launch, non AppNotification. Gli argomenti di notifica vengono quindi recapitati tramite l'evento NotificationInvoked .

Important

È necessario chiamare AppNotificationManager.Register prima di chiamare AppInstance.GetActivatedEventArgs.

Important

L'impostazione activationType="background" nel payload XML di notifica viene ignorata per le applicazioni desktop. È necessario elaborare gli argomenti di attivazione nel codice e decidere se visualizzare o meno una finestra.

// App.xaml.cs
using Microsoft.UI.Xaml;
using Microsoft.Windows.AppLifecycle;
using Microsoft.Windows.AppNotifications;

namespace AppNotificationsExample;

public partial class App : Application
{
    private Window? _window;

    public App()
    {
        InitializeComponent();
    }

    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        _window = new MainWindow();

        AppNotificationManager.Default.NotificationInvoked += OnNotificationInvoked;
        AppNotificationManager.Default.Register();

        var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();

        if (activatedArgs.Kind == ExtendedActivationKind.AppNotification)
        {
            // App was launched by clicking a notification
            var notificationArgs = (AppNotificationActivatedEventArgs)activatedArgs.Data;
            HandleNotification(notificationArgs);
        }
        else
        {
            // Normal launch
            _window.Activate();
        }
    }

    private void OnNotificationInvoked(AppNotificationManager sender, AppNotificationActivatedEventArgs args)
    {
        // Notification clicked while app is already running
        HandleNotification(args);
    }

    private void HandleNotification(AppNotificationActivatedEventArgs args)
    {
        var action = args.Arguments.ContainsKey("action") ? args.Arguments["action"] : "(none)";
        var exampleEventId = args.Arguments.ContainsKey("exampleEventId") ? args.Arguments["exampleEventId"] : "(none)";

        _window!.DispatcherQueue.TryEnqueue(() =>
        {
            switch (action)
            {
                case "BackgroundAction":
                    // Handle the action without showing the app window.
                    // If the window was never shown, exit the app.
                    if (!_window.Visible)
                    {
                        Application.Current.Exit();
                    }
                    break;

                default:
                    // Bring the app to the foreground and display the notification arguments.
                    _window.Activate();
                    ((MainWindow)_window).UpdateNotificationUI(action, exampleEventId);
                    break;
            }
        });
    }
}

Aggiungere un UpdateNotificationUI metodo a MainWindow per visualizzare gli argomenti di notifica nelle caselle di testo aggiunte in precedenza.

// MainWindow.xaml.cs
public void UpdateNotificationUI(string action, string exampleEventId)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        ActionTextBox.Text = action;
        ExampleEventIdTextBox.Text = exampleEventId;
    });
}

Passaggi successivi

Vedere anche

  • Last updated on