Pushbenachrichtigungen für ASP.NET Core Blazor Progressive Web Applications (PWAs)

Blazor PWAs können Pushbenachrichtigungen (Datennachrichten ) von einem Back-End-Server empfangen und anzeigen, auch wenn der Benutzer die App nicht aktiv verwendet. Beispielsweise können Pushbenachrichtigungen gesendet werden, wenn ein anderer Benutzer eine Aktion in seiner installierten PWA ausführt oder wenn die App oder benutzer, die direkt mit der Back-End-Server-App interagieren, eine Aktion ausführen.

Verwenden von Pushbenachrichtigungen für:

• Benachrichtigen Sie Benutzer, dass etwas Wichtiges passiert ist, und fordern Sie sie auf, zur App zurückzukehren.
• Aktualisieren Sie daten, die in der App gespeichert sind, z. B. einen Newsfeed, sodass der Benutzer neue Daten auf der nächsten Rückkehr zur App hat, auch wenn er offline ist, wenn die Pushbenachrichtigung ausgegeben wird.

Die Mechanismen zum Senden, Empfangen und Anzeigen einer Pushbenachrichtigung sind unabhängig von Blazor WebAssembly. Das Senden einer Pushbenachrichtigung wird vom Back-End-Server implementiert, der jede Technologie verwenden kann. Das Empfangen und Anzeigen einer Pushbenachrichtigung auf dem Client wird in der JavaScript-Datei des Service Workers (JS) implementiert.

Im Beispiel in diesem Artikel werden Pushbenachrichtigungen verwendet, um den Kunden eines Pizzarestaurants, basierend auf der PWA-Demonstrations-App Blazing Pizza Workshop, Bestellstatusaktualisierungen bereitzustellen. Sie müssen nicht am Online-Workshop teilnehmen, um diesen Artikel zu verwenden, aber der Workshop ist eine hilfreiche Einführung in Blazor die PWA-Entwicklung.

Einrichten von öffentlichen und privaten Schlüsseln

Generieren Sie die kryptografischen öffentlichen und privaten Schlüssel zum Sichern von Pushbenachrichtigungen entweder lokal, z. B. mit PowerShell oder IIS, oder verwenden Sie ein Onlinetool.

Platzhalter, die im Beispielcode dieses Artikels verwendet werden:

• {PUBLIC KEY}: Der öffentliche Schlüssel.
• {PRIVATE KEY}: Der private Schlüssel.

Aktualisieren Sie für die C#-Beispiele in diesem Artikel die someone@example.com E-Mail-Adresse so, dass sie mit der Adresse übereinstimmt, die beim Erstellen des benutzerdefinierten Schlüsselpaars verwendet wird.

Stellen Sie beim Implementieren von Pushbenachrichtigungen sicher sicher, dass kryptografische Schlüssel verwaltet werden:

• Schlüsselgenerierung: Verwenden Sie eine vertrauenswürdige Bibliothek oder ein vertrauenswürdiges Tool, um die öffentlichen und privaten Schlüssel zu generieren. Vermeiden Sie schwache oder veraltete Algorithmen.
• Schlüsselspeicher: Sicheres Speichern privater Schlüssel auf dem Server mithilfe eines sicheren Speichermechanismus wie einem Hardwaresicherheitsmodul (Hardware Security Module, HSM) oder verschlüsseltem Speicher. Machen Sie niemals private Schlüssel für den Client verfügbar.
• Schlüsselverwendung: Verwenden Sie den privaten Schlüssel nur zum Signieren von Pushbenachrichtigungsnutzlasten. Stellen Sie sicher, dass der öffentliche Schlüssel sicher an Clients verteilt wird.

Weitere Informationen zu bewährten Methoden für Kryptografie finden Sie unter Kryptografiedienste.

Erstellen eines Abonnements

Vor dem Senden von Pushbenachrichtigungen an einen Benutzer muss die App den Benutzer um Erlaubnis bitten. Wenn sie die Berechtigung zum Empfangen von Benachrichtigungen erteilen, generiert ihr Browser ein Abonnement, das eine Reihe von Token enthält, die die App zum Weiterleiten von Benachrichtigungen an den Benutzer verwenden kann.

Die Berechtigung kann jederzeit von der App abgerufen werden, es wird jedoch nur empfohlen, Benutzer um Erlaubnis zu bitten, wenn klar ist, warum sie Benachrichtigungen von der App abonnieren möchten. Im folgenden Beispiel werden Benutzer gefragt, wann sie auf der Checkout-Seite (Checkout Komponente) ankommen, da an diesem Punkt klar ist, dass der Benutzer ernsthaft eine Bestellung aufgeben muss.

Wenn der Benutzer dem Empfangen von Benachrichtigungen zustimmt, sendet das folgende Beispiel die Pushbenachrichtigungsabonnementdaten an den Server, auf dem Pushbenachrichtigungstoken zur späteren Verwendung in der Datenbank gespeichert werden.

Fügen Sie eine Pushbenachrichtigungsdatei JS hinzu, um ein Abonnement anzufordern:

• Rufen Sie navigator.serviceWorker.getRegistration auf, um die Registrierung des Servicemitarbeiters zu erhalten.
• Rufen Sie auf worker.pushManager.getSubscription , um festzustellen, ob ein Abonnement vorhanden ist.
• Wenn kein Abonnement vorhanden ist, erstellen Sie ein neues Abonnement mithilfe der PushManager.subscribe Funktion, und geben Sie die URL und Token des neuen Abonnements zurück.

In der Blazing Pizza-App wird die JS Datei benannt pushNotifications.js und befindet sich im öffentlichen Ordner für statische Objekte (wwwroot) des Klassenbibliotheksprojekts Razor der Lösung (BlazingPizza.ComponentsLibrary). Die blazorPushNotifications.requestSubscription Funktion fordert ein Abonnement an.

BlazingPizza.ComponentsLibrary/wwwroot/pushNotifications.js:

(function () {
    const applicationServerPublicKey = '{PUBLIC KEY}';

    window.blazorPushNotifications = {
        requestSubscription: async () => {
            const worker = await navigator.serviceWorker.getRegistration();
            const existingSubscription = await worker.pushManager.getSubscription();
            if (!existingSubscription) {
                const newSubscription = await subscribe(worker);
                if (newSubscription) {
                    return {
                        url: newSubscription.endpoint,
                        p256dh: arrayBufferToBase64(newSubscription.getKey('p256dh')),
                        auth: arrayBufferToBase64(newSubscription.getKey('auth'))
                    };
                }
            }
        }
    };

    async function subscribe(worker) {
        try {
            return await worker.pushManager.subscribe({
                userVisibleOnly: true,
                applicationServerKey: applicationServerPublicKey
            });
        } catch (error) {
            if (error.name === 'NotAllowedError') {
                return null;
            }
            throw error;
        }
    }

    function arrayBufferToBase64(buffer) {
        var binary = '';
        var bytes = new Uint8Array(buffer);
        var len = bytes.byteLength;
        for (var i = 0; i < len; i++) {
            binary += String.fromCharCode(bytes[i]);
        }
        return window.btoa(binary);
    }
})();

Auf dem Server wird ein Abonnementobjekt und ein Benachrichtigungsabonnementendpunkt erstellt. Der Endpunkt empfängt Clientweb-API-Aufrufe mit Pushbenachrichtigungsabonnementdaten, einschließlich kryptografischer Token. Die Daten werden in der Datenbank für jeden App-Benutzer gespeichert.

In der Blazing Pizza-App ist das Abonnementobjekt die NotificationSubscription Klasse. Die P256dh Und Auth Eigenschaften sind die kryptografischen Token des Benutzers.

BlazingPizza.Shared/NotificationSubscription.cs:

public class NotificationSubscription
{
    public int? NotificationSubscriptionId { get; set; }

    public string? UserId { get; set; }

    public string? Url { get; set; }

    public string? P256dh { get; set; }

    public string? Auth { get; set; }
}

Der notifications/subscribe Endpunkt wird in der Erweiterungsmethode der App MapPizzaApi definiert, die in der Datei der App Program aufgerufen wird, um Web-API-Endpunkte für die App einzurichten. Das Benachrichtigungsabonnement des Benutzers (NotificationSubscription), das seine Pushbenachrichtigungstoken enthält, wird in der Datenbank gespeichert. Es wird nur ein Abonnement pro Benutzer gespeichert. Alternativ können Sie zulassen, dass der Benutzer mehrere Abonnements aus verschiedenen Browsern oder Geräten registriert.

app.MapPut("/notifications/subscribe", 
    [Authorize] async (
    HttpContext context,
    PizzaStoreContext db,
    NotificationSubscription subscription) => 
    {
        var userId = GetUserId(context);

        if (userId is null)
        {
            return Results.Unauthorized();
        }

        // Remove old subscriptions for this user
        var oldSubscriptions = db.NotificationSubscriptions.Where(
            e => e.UserId == userId);
        db.NotificationSubscriptions.RemoveRange(oldSubscriptions);

        // Store the new subscription
        subscription.UserId = userId;
        db.NotificationSubscriptions.Add(subscription);

        await db.SaveChangesAsync();

        return Results.Ok(subscription);
    });

In BlazingPizza.Client/HttpRepository.cs, gibt die SubscribeToNotifications Methode einen HTTP PUT an den Abonnementsendpunkt auf dem Server aus:

public class HttpRepository : IRepository
{

	private readonly HttpClient _httpClient;

	public HttpRepository(HttpClient httpClient)
	{
		_httpClient = httpClient;
	}

    ...

    public async Task SubscribeToNotifications(NotificationSubscription subscription)
	    {
		    var response = await _httpClient.PutAsJsonAsync("notifications/subscribe", 
                subscription);
		    response.EnsureSuccessStatusCode();
	}
}

Die Repositoryschnittstelle (BlazingPizza.Shared/IRepository.cs) enthält die Methodensignatur von SubscribeToNotifications:

public interface IRepository
{
    ...

	Task SubscribeToNotifications(NotificationSubscription subscription);
}

Definieren Sie eine Methode, um ein Abonnement anzufordern und Benachrichtigungen zu abonnieren, wenn das Abonnement eingerichtet ist. Speichern Sie das Abonnement in der Datenbank für die spätere Verwendung.

In der Checkout Komponente der Blazing Pizza-App führt die RequestNotificationSubscriptionAsync Methode die folgenden Aufgaben aus:

• Das Abonnement wird über JS Interop durch den Aufruf von blazorPushNotifications.requestSubscription erstellt. Die Komponente fügt den IJSRuntime Dienst ein, um die JS Funktion aufzurufen.
• Die SubscribeToNotifications Methode wird aufgerufen, um das Abonnement zu speichern.

In BlazingPizza.Client/Components/Pages/Checkout.razor:

async Task RequestNotificationSubscriptionAsync()
{
    var subscription = await JSRuntime.InvokeAsync<NotificationSubscription>(
        "blazorPushNotifications.requestSubscription");

    if (subscription is not null)
    {
        try
        {
            await Repository.SubscribeToNotifications(subscription);
        }
        catch (AccessTokenNotAvailableException ex)
        {
            ex.Redirect();
        }
    }
}

In der Checkout Komponente wird RequestNotificationSubscriptionAsync in der OnInitialized Lebenszyklusmethode aufgerufen und bei der Komponenteninitialisierung ausgeführt. Die Methode ist asynchron, kann aber im Hintergrund ausgeführt werden, und das zurückgegebene Task-Objekt kann verworfen werden. Daher wird die Methode nicht in der asynchronen Lebenszyklusmethode für die Komponenteninitialisierung (OnInitializedAsync) aufgerufen. Auf diese Weise wird die Komponente schneller gerendert.

protected override void OnInitialized()
{
    _ = RequestNotificationSubscriptionAsync();
}

Um zu veranschaulichen, wie der Code funktioniert, führen Sie die Blazing Pizza-App aus, und beginnen Sie mit der Bestellung. Wechseln Sie zum Auscheckbildschirm, um die Abonnementanfrage anzuzeigen:

Wählen Sie "Zulassen" aus, und überprüfen Sie die Konsole der Browserentwicklertools auf Fehler. Sie können einen Haltepunkt im PizzaApiExtensions-Code des MapPut("/notifications/subscribe"...) setzen und die Anwendung mit Debugging ausführen, um die vom Browser eingehenden Daten zu untersuchen. Die Daten enthalten eine Endpunkt-URL und kryptografische Token.

Nachdem der Benutzer Benachrichtigungen für eine bestimmte Website zugelassen oder blockiert hat, wird der Browser nicht mehr gefragt. Wenn Sie die Berechtigung für weitere Tests für Google Chrome oder Microsoft Edge zurücksetzen möchten, wählen Sie das Symbol "Informationen" (🛈) links neben der Adressleiste des Browsers aus, und ändern Sie Benachrichtigungen wieder in "Fragen" (Standardeinstellung), wie in der folgenden Abbildung dargestellt:

Senden einer Benachrichtigung

Das Senden einer Benachrichtigung umfasst das Ausführen komplexer kryptografischer Vorgänge auf dem Server, um die Daten während der Übertragung zu schützen. Der Großteil der Komplexität wird für die App von einem NuGet-Paket eines Drittanbieters behandelt, WebPushdas vom Serverprojekt (BlazingPizza.Server) in der Blazing Pizza-App verwendet wird.

Die SendNotificationAsync Methode verteilt Bestellbenachrichtigungen mithilfe des erfassten Abonnements. Der folgende Code verwendet WebPush APIs zum Verteilen der Benachrichtigung. Die Nutzlast der Benachrichtigung ist im JSON-Format serialisiert und enthält eine Nachricht und eine URL. Die Meldung wird dem Benutzer angezeigt, und über die URL kann der Nutzer die mit der Benachrichtigung verknüpfte Pizza-Bestellung aufrufen. Für andere Benachrichtigungsszenarien können zusätzliche Parameter serialisiert werden.

private static async Task SendNotificationAsync(Order order, 
    NotificationSubscription subscription, string message)
{
    var publicKey = "{PUBLIC KEY}";
    var privateKey = "{PRIVATE KEY}";

    var pushSubscription = new PushSubscription(subscription.Url, 
        subscription.P256dh, subscription.Auth);
    var vapidDetails = new VapidDetails("mailto:<someone@example.com>", publicKey, 
        privateKey);
    var webPushClient = new WebPushClient();

    try
    {
        var payload = JsonSerializer.Serialize(new
        {
            message,
            url = $"myorders/{order.OrderId}",
        });

        await webPushClient.SendNotificationAsync(pushSubscription, payload, 
            vapidDetails);
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"Error sending push notification: {ex.Message}");
    }
}

Im vorherigen Beispiel kann der Server Benachrichtigungen senden, der Browser reagiert jedoch nicht auf Benachrichtigungen ohne zusätzliche Logik. Die Anzeige von Benachrichtigungen wird im Abschnitt "Anzeigebenachrichtigungen" behandelt.

Die Entwicklertools-Konsole des Browsers zeigt die Ankunft von Benachrichtigungen zehn Sekunden nach der Bestellung in der Blazing Pizza-App an. Öffnen Sie auf der Registerkarte "Anwendung " den Abschnitt "Pushnachrichten" . Wählen Sie den Kreis aus, um die Aufzeichnung zu starten:

Anzeigen von Benachrichtigungen

Der PWA-Servicemitarbeiter (service-worker.js) muss Pushbenachrichtigungen verarbeiten, damit die App sie anzeigen kann.

Der folgende push-Ereignishandler in der Blazing Pizza App fragt showNotification an, um eine Benachrichtigung für den aktiven Service Worker zu erstellen.

In BlazingPizza/wwwroot/service-worker.js:

self.addEventListener('push', event => {
  const payload = event.data.json();
  event.waitUntil(
    self.registration.showNotification('Blazing Pizza', {
      body: payload.message,
      icon: 'img/icon-512.png',
      vibrate: [100, 50, 100],
      data: { url: payload.url }
    })
  );
});

Der vorhergehende Code wird erst nach dem Laden der nächsten Seite wirksam, wenn der Browser Installing service worker... protokolliert. Wenn Sie schwierigkeiten haben, den Service Worker zu aktualisieren, verwenden Sie die Registerkarte "Anwendung " in der Entwicklertools-Konsole des Browsers. Wählen Sie unter Service Worker die Option "Aktualisieren" aus, oder verwenden Sie " Registrierung aufheben ", um eine neue Registrierung beim nächsten Laden zu erzwingen.

Sobald der vorangehende Code implementiert ist und eine neue Bestellung von einem Benutzer aufgegeben wurde, wechselt die Bestellung entsprechend der integrierten Demonstrationslogik der App nach 10 Sekunden in den Unterwegs-zur-Auslieferung-Status. Der Browser empfängt eine Pushbenachrichtigung:

Wenn Sie die App in Google Chrome oder Microsoft Edge verwenden, wird die Benachrichtigung auch dann angezeigt, wenn der Benutzer die Blazing Pizza-App nicht aktiv verwendet. Allerdings muss der Browser ausgeführt werden, sonst erscheint die Benachrichtigung beim nächsten Öffnen des Browsers.

Wenn Sie die installierte PWA verwenden, sollte die Benachrichtigung auch dann zugestellt werden, wenn der Benutzer die App nicht ausführt.

Klicks auf Benachrichtigungen verarbeiten

Registrieren Sie einen notificationclick Ereignishandler , um einen Benutzer zu verarbeiten, der eine Pushbenachrichtigung auf dem Gerät auswählt (klickt):

• Schließen Sie die Benachrichtigung durch Aufrufen event.notification.close.
• Rufen Sie auf clients.openWindow , um einen neuen Browserkontext auf oberster Ebene zu erstellen und die an die Methode übergebene URL zu laden.

Das folgende Beispiel in der Blazing Pizza-App führt den Nutzer zur Bestellstatusseite für die Bestellung, die sich auf die Benachrichtigung bezieht. Die URL wird vom event.notification.data.url Parameter bereitgestellt, der vom Server in der Nutzlast der Benachrichtigung gesendet wird.

In der Service Worker-Datei (service-worker.js):

self.addEventListener('notificationclick', event => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});

Wenn die PWA auf dem Gerät installiert ist, wird die PWA auf dem Gerät angezeigt. Wenn die PWA nicht installiert ist, wird der Benutzer in seinem Browser zur Seite der App weitergeleitet.

Weitere Ressourcen

• Push-API (MDN-Dokumentation)
• Nachrichtenverschlüsselung für Web-Push (Draft-ietf-webpush-encryption-08)
• Push-API (W3C Working Draft 03 September 2024)
• Service Worker-API (MDN-Dokumentation)