Integrieren Sie Ihre Windows UWP-App mit dem clientseitigen SDK für Benutzerbenachrichtigungen (veraltet)
Wichtig
Die Microsoft Graph-Benachrichtigungs-API ist veraltet und gibt seit Januar 2022 keine Daten mehr zurück. Eine alternative Benachrichtigungsoberfläche finden Sie unter Microsoft Azure-Benachrichtigungshubs. Weitere Informationen finden Sie im Blogbeitrag Außerbetriebnahme der Microsoft Graph Benachrichtigungs-API (Beta).
Nachdem Sie Ihre App im Microsoft Entra Admin Center registriert und ihre geräteübergreifenden Erfahrungen im Partner Dev Center integriert haben, besteht der nächste Schritt darin, Ihre Client-App in das clientseitige SDK für Windows UWP-Apps zu integrieren.
Mit dem clientseitigen SDK kann Ihre App die nötigen Registrierungsschritte ausführen, um Benachrichtigungen von Ihrem App-Server zu empfangen, die an den Benutzer gerichtet sind, der aktuell angemeldet ist. Das SDK verwaltet die Benachrichtigungen clientseitig, einschließlich des Empfangs neuer Benachrichtigungen und der Verwaltung des Status von Benachrichtigungen, um Szenarien wie geräteübergreifendes Schließen und den Abruf des vollständigen Benachrichtigungsverlaufes zu realisieren.
Fluss neuer eingehender Benachrichtigungen
Für den Empfang neuer eingehender Benachrichtigungen wird der Datenfluss im folgenden Diagramm gezeigt.
Der Prozess umfasst einige Komponenten:
- App-Server – das Back-End Ihrer Anwendung
- App-Client – das Frontend Ihrer Anwendung (eine UWP-App, eine Android-App oder eine App für iOS)
- Microsoft Graph-Benachrichtigungen – Diejenige Dienstkomponente, die es ermöglicht, Benutzerbenachrichtigungen zu veröffentlichen, zu speichern und zwischen verschiedenen Instanzen der App auf mehreren Geräten und Plattformen zu synchronisieren.
- WNS – der Windows-Pushbenachrichtigungsdienst, der von Microsoft Graph-Benachrichtigungen zum Signalisieren der Clients verwendet wird.
Das Diagramm zeigt die folgenden Schritte:
- Anwendungslogik. Dieser Schritt erfasst, was den Versand der Benachrichtigung an den Benutzer auslösen soll. Dies ist App-spezifische Logik, die auch eine Ereignis- oder Datenaktualisierung zu etwas anderem in Microsoft Graph sein kann, beispielsweise ein neuer Kalendereintrag oder die Zuweisung einer Aufgabe, oder etwas anderes, worüber Ihr App-Dienst den Benutzer informieren möchte.
- Der App-Server sendet mittels der Microsoft Graph Benachrichtigungs-API eine Benachrichtigung an den entsprechenden Benutzer. Weitere Informationen hierzu finden Sie unter Serverseitige Integration.
- Bei Empfang der Webanforderung, welche die neue Benachrichtigung enthält, speichert Microsoft Graph Benachrichtigungen den Inhalt der Benachrichtigung für diese App und diesen Benutzer sicher in der Cloud.
- Für jede Instanz der Client-App, die für den Empfang von Benachrichtigungen für diesen Benutzer angemeldet ist, sendet Microsoft Graph Benachrichtigungen mittels des jeweils systemeigenen Push-Dienstes ein Signal aus, um den App-Client zu benachrichtigen. In diesem Fall handelt es sich bei der Anwendung um eine Windows-UWP-App, und diese verwendet eine unformatierte WNS-Pushbenachrichtigung, um das Signal zu versenden.
- Nachdem die Anwendung das Signal mittels eingehender Pushbenachrichtigung empfangen hat, fordert sie das SDK dazu auf, die Änderungen im Benachrichtigungsspeicher des Benutzers abzurufen.
- Das SDK baut eine sichere und konforme Verbindung mit dem Benachrichtigungsspeicher des Benutzers in Microsoft Graph auf.
- Das SDK empfängt die Datenänderungen – in diesem Fall handelt es sich um die neuen Benachrichtigungsinhalte.
- Das SDK sendet Ereignisrückrufe, um die App zu benachrichtigen, nachdem die Änderungen erfolgreich abgerufen wurden.
- Anwendungslogik. Dieser Schritt umfasst, was die App innerhalb des Ereignisrückrufes entscheidet, zu tun. In der Regel führt dies zur Änderung lokaler Anwendungsdaten und zu lokalen Benutzeroberflächen-Updates. In diesem Fall erstellt die App in der Regel ein Popupbenachrichtigungs-Popup, um den Benutzer über den Benachrichtigungsinhalt zu benachrichtigen.
Benachrichtigungs-Updatefluss
Einer der Hauptvorteile bei der Verwendung von Microsoft Graph Benachrichtigungen ist, dass Benachrichtigungen sicher in der Cloud gespeichert und in einen zustandsbehafteten Ressourcentyp gewandelt werden. Daher kann es Ihrer Anwendung dabei helfen, in einem plattformübergreifenden Szenario den korrekten Benachrichtigungsstatus über verschiedene Geräte hinweg für denselben angemeldeten Benutzer zu verwalten und zu synchronisieren. Wenn eine Benachrichtigung als geschlossen oder auf einem Gerät als gelesen markiert wird, können die anderen Geräte darüber in Echtzeit benachrichtigt werden. „Einmal behandelt, überall geschlossen“ kann für Ihre benachrichtigten Nutzer zu einem echten Versprechen werden.
Das folgende Diagramm zeigt den Datenfluss für die Änderung des Status einer Benachrichtigung oder für das Löschen der Benachrichtigung auf einem Gerät und den Erhalt/die Verarbeitung der Statusänderung oder der Löschung auf einem anderen Gerät.
Beachten Sie, dass der zweite Teil des Flussdiagramms ähnlich dem Ablauf für die Verarbeitung eingehender neuer Benachrichtigungen ist. Dies ist beabsichtigt: Das Programmiermuster des SDK ist so konzipiert, dass der Anwendungsclient alle Arten von Änderungen an Benutzerbenachrichtigungsdaten (neue eingehende Benachrichtigungen, Änderungen des Benachrichtigungszustands, gelöschte Benachrichtigungen) auf ähnliche Weise verarbeiten kann.
Das Diagramm zeigt die folgenden Schritte:
- Anwendungslogik. Etwas löst die Änderung oder Löschung der Benachrichtigung aus. Im Allgemeinen kann jedes Ereignis eine Änderung der Benachrichtigung auslösen.
- Die App kontaktiert das Client-SDK, um eine Benachrichtigung zu aktualisieren oder zu löschen. Derzeit bieten wir zwei Eigenschaften bezüglich Statusänderungen: userActionState und readState. Ihre Anwendung kann diese Status definieren und auch festlegen, wann diese aktualisiert werden müssen. Wenn ein Benutzer das Benachrichtigungs-Popup beispielsweise schließt, können Sie die Eigenschaft userActionState auf geschlossen setzen. Wenn ein Benutzer auf das Benachrichtigungs-Popup klickt und die App öffnet, um den entsprechenden App-Inhalt zu konsumieren, können Sie userActionState auf aktiviert und readState auf gelesen setzen.
- Nachdem die entsprechende API aufgerufen wird, um eine Benachrichtigung zu aktualisieren oder zu löschen, kontaktiert das SDK den Benachrichtigungsspeicher des Benutzers in der Cloud, um diese Änderung an die restlichen App-Client-Instanzen aufzufächern, in denen derselbe Benutzer angemeldet ist.
- Nach Erhalt der Aktualisierungs-/Löschanfrage von einem Client aktualisiert Microsoft Graph Benachrichtigungen den Benachrichtigungsspeicher und identifiziert die anderen App-Client-Instanzen, die sich für diese Änderung angemeldet haben.
- Für jede Client-App-Anmeldung sendet Microsoft Graph Benachrichtigungen mittels des jeweils systemeigenen Push-Dienstes ein Signal aus, um den App-Client zu benachrichtigen. In diesem Fall handelt es sich um eine Windows-UWP-App, und diese verwendet eine unformatierte WNS-Pushbenachrichtigung, um das Signal zu versenden.
- Nachdem die Anwendung das Signal mittels eingehender Pushbenachrichtigung empfangen hat, fordert sie das SDK dazu auf, die Änderungen im Benachrichtigungsspeicher des Benutzers abzurufen.
- Das SDK baut eine sichere und konforme Verbindung mit dem Benachrichtigungsspeicher des Benutzers in Microsoft Graph auf.
- Das SDK empfängt die Datenänderungen – in diesem Fall handelt es sich um Benachrichtigungs-Statusaktualisierungen oder Benachrichtigungs-Löschungen.
- Das SDK sendet Ereignisrückrufe, um die App zu benachrichtigen, nachdem die Änderungen erfolgreich abgerufen wurden.
- Anwendungslogik. Dieser Schritt umfasst, was die App innerhalb des Ereignisrückrufes entscheidet, zu tun. In der Regel führt dies zur Änderung lokaler Anwendungsdaten und zu lokalen Benutzeroberflächen-Updates. Da Benachrichtigungsaktualisierungen vorliegen, sollte die App in diesem Fall die Benutzeroberfläche lokal aktualisieren, um die Zustandsänderung darzustellen. Wenn eine Benachrichtigung z.B. als aktiviert markiert wird, können Sie die zugehörige Popupbenachrichtigung aus dem Windows-Info-Center entfernen, um nach dem Prinzip „einmal behandelt, überall geschlossen“ zu arbeiten.
Weitere Informationen zu Microsoft Graph Benachrichtigungen finden Sie unter Microsoft Graph Benachrichtigungen Überblick. Für zusätzliche Informationen über die Schritte, die erforderlich sind, um Microsoft Graph-Benachrichtigungen von Ende zu Ende zu integrieren, lesen Sie die Microsoft Graph-Benachrichtigungsübersicht.
Hinzufügen des SDKs zu Ihrem Projekt
Unter Windows ist das clientseitige SDK ein NuGet-Paket, das außerhalb des Windows-Betriebssystems ausgeliefert wird. Diese API ist in C#, C++und WinJS verfügbar.
Laden Sie das NuGet-Paket für das SDK für die Microsoft Graph-Benachrichtigungen für Windows-Apps in nuget herunter, oder führen Sie die folgenden Schritte aus, um es aus Ihrer APP-Lösung in Visual Studio herunterzuladen:
Klicken Sie in Visual Studio mit der rechten Maustaste auf das Projekt, um das Kontextmenü zu öffnen, und klicken Sie dann auf NuGet-Pakete verwalten….
Wechseln Sie zur Registerkarte Durchsuchen, und suchen Sie nach „Microsoft.ConnectedDevices.UserNotifications“.
Das clientseitige SDK von Microsoft Graph-Benachrichtigungen wird in den Suchergebnissen angezeigt. Klicken Sie auf die Schaltfläche Installieren, um es zu installieren.
Nach Abschluss der Installation wird das Paket im Projektmappen-Explorer unter Verweise angezeigt.
Weitere Details zum Einschließen und Verwenden von NuGet-Paketen aus ihrer UWP-App finden Sie unter:
- Verwenden von Paketen von nuget.org
- Schnellstart: Installieren und Verwenden eines Pakets in Visual Studio
Initialisieren der Plattform für verbundene Geräte
Das clientseitige SDK basiert auf einer Infrastruktur namens „Plattform für verbundene Geräte“. Bevor eine der Funktionen verwendet werden kann, muss die Plattform innerhalb Ihrer App initialisiert werden. Die Initialisierungsschritte sollten in der Hauptklasse OnLaunched- oder onActivated-Methode erfolgen, da sie benötigt werden, bevor die Benachrichtigungsszenarien erfolgen können.
Sie müssen die Plattform konstruieren und initialisieren, indem Sie die Klasse ConnectedDevicesPlatform instanziieren. Vorher müssen Sie sicherstellen, dass Ereignishandler (wie gezeigt) verknüpft sind, denn die Ereignisse können eintreten, sobald die Plattform gestartet wird.
var platform = new ConnectedDevicesPlatform();
platform.AccountManager.AccessTokenRequested += AccountManager_AccessTokenRequestedAsync;
platform.AccountManager.AccessTokenInvalidated += AccountManager_AccessTokenInvalidated;
platform.NotificationRegistrationManager.NotificationRegistrationStateChanged += NotificationRegistrationManager_NotificationRegistrationStateChanged;
platform.Start();
Handhabung von Konto-Zugriffstoken
Alle Webaufrufe, die das SDK durchführt, einschließlich des Abrufens des Inhalts einer neuen eingehenden Benachrichtigung, das Aktualisierung von Benachrichtigungsstatus usw., lesen aus oder schreiben in die Benutzerdaten und benötigen daher stets ein gültiges Zugriffstoken. Das SDK erfordert, dass Sie die folgenden Ereignisse verarbeiten. Diese treten ein, sobald ein Zugriffstoken angefordert oder ungültig gemacht wird, um sicherzustellen, dass Ihr Zugriffstoken nach der Initialisierung der Plattform korrekt verarbeitet wird.
AccountManager_AccessTokenRequestedAsync
Eine vollständige Implementierung finden Sie im Windows-App-Beispiel.
private async void AccountManager_AccessTokenRequestedAsync(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenRequestedEventArgs args)
{
private List<Account> accounts = new List<Account>();
var account = accounts.Find((x) => x.EqualsTo(args.Request.Account));
if (account != null)
{
try
{
var accessToken = await account.GetAccessTokenAsync(args.Request.Scopes);
args.Request.CompleteWithAccessToken(accessToken);
}
catch (Exception ex)
{
args.Request.CompleteWithErrorMessage(ex.Message);
}
}
}
AccountManager_AccessTokenInvalidated
Eine vollständige Implementierung finden Sie im Windows-App-Beispiel.
private void AccountManager_AccessTokenInvalidated(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenInvalidatedEventArgs args)
{
Logger.Instance.LogMessage($"Token Invalidated. AccountId: {args.Account.Id}, AccountType: {args.Account.Id}, scopes: {string.Join(" ", args.Scopes)}");
}
Verarbeitung des Ablaufs von Pushregistrierungen
Microsoft Graph-Benachrichtigungen verwenden WNS, die systemeigene Push-Plattform unter Windows, um der Clientanwendung Änderungen der Benachrichtigungsdaten des Benutzers zu signalisieren. Dies geschieht, wenn neue eingehende Benachrichtigungen von Ihrem App-Server veröffentlicht werden oder wenn der Status einer Benachrichtigung auf einem anderen Gerät aktualisiert wird, falls es sich um denselben Nutzer in einem geräteübergreifenden Szenario handelt.
Aus diesem Grund wird ein gültiger WNS-Kanal benötigt, der ermöglicht, dass die unformatierten Pushbenachrichtigungen erfolgreich durchgelassen werden. Der folgende Ereignisrückruf verarbeitet die Ablaufzeiten des WNS-Pushkanals.
NotificationRegistrationManager_NotificationRegistrationStateChanged
Eine vollständige Implementierung finden Sie im Windows-App-Beispiel.
private async void NotificationRegistrationManager_NotificationRegistrationStateChanged(ConnectedDevicesNotificationRegistrationManager sender, ConnectedDevicesNotificationRegistrationStateChangedEventArgs args)
{
if ((args.State == ConnectedDevicesNotificationRegistrationState.Expired) || (args.State == ConnectedDevicesNotificationRegistrationState.Expiring))
{
var account = m_accounts.Find((x) => x.EqualsTo(args.Account));
if (account != null)
{
await account.RegisterAccountWithSdkAsync();
}
}
}
Anmelden des Benutzers
Microsoft Graph-Benachrichtigungen sind, wie viele andere Ressourcentypen in Microsoft Graph, um einen zentralen Benutzer herum konstruiert. Um Ihre App für Benachrichtigungen für den angemeldeten Benutzer anzumelden und diese zu empfangen, müssen Sie zuerst ein gültiges OAuth-Token beschaffen, das im Registrierungsprozess verwendet wird. Sie können Ihre bevorzugte Methode zum Generieren und Verwalten der OAuth-Token verwenden. Die Beispiel-App verwendet ADAL.
Wenn Sie ein Microsoft-Konto verwenden, müssen Sie die folgenden Berechtigungen in Ihre Anmeldeanfrage inkludieren: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry und https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.
Wenn Sie ein Microsoft Entra-Konto verwenden, müssen Sie die folgende Zielgruppe anfordern: https://cdpcs.access.microsoft.com.
Der Plattform das Benutzerkonto hinzufügen
Sie müssen das angemeldete Benutzerkonto beim SDK registrieren. Dazu ist es nötig, das Konto hinzuzufügen, und einen Push-Kanal zu registrieren, um die anfänglichen Pushbenachrichtigungen durch WNS zu erhalten.
var account = new ConnectedDevicesAccount(accountId, accountType);
var addResult = await platform.AccountManager.AddAccountAsync(account);
if (addResult.Status != ConnectedDevicesAccountAddedStatus.Success)
{
throw new Exception("Add account failed with " + addResult.Status + "!");
}
var pushChannel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
ConnectedDevicesNotificationRegistration registration = new ConnectedDevicesNotificationRegistration();
registration.Type = ConnectedDevicesNotificationType.WNS;
registration.Token = pushChannel.Uri;
var registerResult = await platform.NotificationRegistrationManager.RegisterAsync(account, registration);
if (registerResult.Status != ConnectedDevicesNotificationRegistrationStatus.Success)
{
throw new Exception("Register push channel failed with " + registerResult.Status + "!");
}
Empfang von Benutzerbenachrichtigungen anmelden
Sie müssen ein UserDataFeed-Objekt für Ihre Anwendung für den angemeldeten Benutzer instanziieren. Ihre Anwendung wird durch die plattformübergreifende App-ID identifiziert, die Sie während des geräteübergreifenden Onboardings vergeben haben.
UserDataFeed feed = UserDataFeed.GetForAccount(account, platform, "YOUR_HOST_HERE");
var scopes = new List<UserDataFeedSyncScope> { UserNotificationChannel.SyncScope };
var subscribeResult = await feed.SubscribeToSyncScopesAsync(scopes);
if (!subscribeResult)
{
throw new Exception("Subsribe failed!");
}
var channel = new UserNotificationChannel(feed);
var reader = channel.CreateReader();
reader.DataChanged += Reader_DataChanged;
Empfangen und Verwalten von Benutzerbenachrichtigungen
Das Flussdiagramm weiter oben in diesem Artikel zeigt, dass die Programmierungsmuster zur Verarbeitung neu ankommender Benachrichtigungen von einem App-Server und ein Benachrichtigungs-Update oder eine -Löschung, die von einer anderen Client-Instanz initiiert werden, ähnlich sind. Die folgenden Schritte beschreiben die Verarbeitung dieser Datenänderungen.
Verarbeitung eingehender Pushbenachrichtigungs-Signale
Alle Typen von Datenänderungen an Benutzerbenachrichtigungen generieren ein Signal, welches als Pushbenachrichtigung zu den App-Clients gesendet wird. Bei Windows UWP-Apps wird das Signal als unformatierte WNS-Pushbenachrichtigung bereitgestellt. Sobald das unformatierte Pushsignal empfangen wird, sollte die App TryParse aufrufen, um das SDK zu veranlassen, die tatsächlichen Datenänderungen vom Microsoft Graph-Benachrichtigungsdienst abzurufen.
public async Task ReceiveNotificationAsync(string content)
{
ConnectedDevicesNotification notification = ConnectedDevicesNotification.TryParse(content);
if (notification != null)
{
await platform.ProcessNotificationAsync(notification);
}
}
Verarbeitung von Änderungen an Benutzer-Benachrichtigungsdaten
Nachdem das SDK erfolgreich die Datenänderungen abgerufen hat, wird ein Ereignisrückruf ausgelöst, und vom App-Client wird erwartet, dass er die Erstellung, Löschung oder Änderung einer Benachrichtigung übernimmt.
private async void Reader_DataChanged(UserNotificationReader reader, object args)
{
var notifications = await reader.ReadBatchAsync(UInt32.MaxValue);
foreach (var notification in notifications)
{
// Handle notification changes based on change type;
}
}
Aktualisierung des Zustands einer Benachrichtigung
Wenn diese App-Client-Instanz eine Statusänderung für eine Benachrichtigung initiiert (beispielsweise, wenn die Popupbenachrichtigung auf diesem Gerät vom Benutzer aktiviert wird), so muss die App das SDK aufrufen, um den Benachrichtigungsstatus zu aktualisieren, damit dieser Status geräteübergreifend für diesen Nutzer auf all seinen Geräten synchronisiert wird.
notification.UserActionState = UserNotificationUserActionState.Activated;
await notification.SaveAsync();
Zeitliches Steuern einer Benachrichtigung
Wenn von dieser App-Client-Instanz aus die Löschung einer Benachrichtigung initiiert wird (z.B. falls der Task, der dieser Benachrichtigung zugehörig ist, als abgeschlossen gekennzeichnet wird und aus der Datenbank Ihrer App entfernt wird), so muss die App das SDK aufrufen, um die Benachrichtigung zu löschen, damit dieser Löschvorgang über alle Geräte dieses Benutzers hinweg synchronisiert wird.
Eine Benachrichtigung wird erst dann aus dem Benachrichtigungsspeicher eines Nutzers entfernt, wenn sie abgelaufen ist oder ausdrücklich gelöscht wurde. Eine Benutzerbenachrichtigung wird nicht gelöscht, wenn Sie den UserActionState auf geschlossen setzen, denn die semantische Definition von UserActionState wird durch die Anwendung selbst definiert.
await channel.DeleteUserNotificationAsync(notification.Id);
Verwandte Inhalte
- API-Referenz für alle APIs, die mit Benachrichtigungsfunktionen im SDK zusammenhängen.
- Clientseitiges Beispiel für Windows-UWP-Apps.
- App-Server-Beispiel für die Veröffentlichung von Benachrichtigungen.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für