Udostępnij przez

Wysyłanie powiadomienia aplikacji lokalnej z aplikacji w języku C#

Powiadomienie o aplikacji to komunikat, który aplikacja może skonstruować i dostarczyć użytkownikowi, gdy nie znajdują się one obecnie w aplikacji.

Zrzut ekranu przedstawiający powiadomienie aplikacji

Przewodnik Szybki start przeprowadzi Cię przez proces tworzenia, dostarczania i wyświetlania powiadomienia aplikacji w systemie Windows 10 lub Windows 11 z użyciem bogatej zawartości i akcji interaktywnych. W tym przewodniku szybkiego startu używane są powiadomienia lokalne, które najłatwiej zaimplementować. Wszystkie typy aplikacji (WPF, UWP, WinForms, konsola) mogą wysyłać powiadomienia!

Note

Określenie "powiadomienie typu toast" jest zastępowane terminem "powiadomienie aplikacji". Te dwa terminy odnoszą się do tej samej funkcji systemu Windows, ale z czasem wyeliminujemy użycie "toast notification" w dokumentacji.

Important

Jeśli piszesz aplikację języka C++, zapoznaj się z dokumentacją C ++ UWP lub C++ WRL .

Krok 1. Instalowanie pakietu NuGet

W rozwiązaniu programu Visual Studio kliknij prawym przyciskiem myszy projekt, kliknij pozycję "Zarządzaj pakietami NuGet..." i wyszukaj i zainstaluj Microsoft.Toolkit.Uwp.Notifications w wersji 7.0 lub nowszej.

Important

Aplikacje klasyczne platformy .NET Framework, które nadal używają packages.config, muszą zostać zmigrowane do mechanizmu PakietReference, w przeciwnym razie pakiety SDK systemu Windows nie będą poprawnie referowane. W projekcie kliknij prawym przyciskiem myszy pozycję "Odwołania", a następnie kliknij pozycję "Migruj packages.config do opcji PackageReference".

Aplikacje platformy .NET Core 3.0 WPF muszą zostać zaktualizowane do platformy .NET Core 3.1. W przeciwnym razie interfejsy API będą nieobecne.

Aplikacje platformy .NET muszą używać jednego z serwerów TFM systemu Windows. W przeciwnym razie brakuje interfejsów API wysyłania powiadomień aplikacji i zarządzania, takich jak Show() . Ustaw program TFM na net6.0-windows10.0.17763.0 lub nowszy.

Nasz przykładowy kod będzie używać tego pakietu. Ten pakiet umożliwia tworzenie powiadomień aplikacji bez używania kodu XML, a także umożliwia aplikacjom klasycznym wysyłanie powiadomień aplikacji.

Krok 2. Wysyłanie powiadomienia aplikacji

W systemach Windows 10 i Windows 11 zawartość powiadomień aplikacji jest opisana przy użyciu języka adaptacyjnego, który zapewnia dużą elastyczność w sposobie wyglądu powiadomienia. Aby uzyskać więcej informacji, zobacz dokumentację zawartości powiadomienia aplikacji .

Zaczniemy od prostego powiadomienia tekstowego. Skonstruuj zawartość powiadomienia (przy użyciu biblioteki powiadomień) i wyświetl powiadomienie! Należy pamiętać, że przestrzeń nazw to Microsoft.Toolkit.Uwp.Notifications.

proste powiadomienie tekstowe 
// Requires Microsoft.Toolkit.Uwp.Notifications NuGet package version 7.0 or greater
new ToastContentBuilder()
    .AddArgument("action", "viewConversation")
    .AddArgument("conversationId", 9813)
    .AddText("Andrew sent you a picture")
    .AddText("Check this out, The Enchantments in Washington!")
    .Show(); // Not seeing the Show() method? Make sure you have version 7.0, and if you're using .NET 6 (or later), then your TFM must be net6.0-windows10.0.17763.0 or greater

Spróbuj uruchomić ten kod i powinno zostać wyświetlone powiadomienie.

Krok 3. Obsługa aktywacji

Po wyświetleniu powiadomienia prawdopodobnie trzeba obsłużyć użytkownika klikając powiadomienie (czy oznacza to wyświetlenie określonej zawartości po kliknięciu jej przez użytkownika, otwarcie aplikacji w ogóle lub wykonanie akcji po kliknięciu powiadomienia przez użytkownika).

Kroki obsługi aktywacji różnią się w przypadku platformy UWP oraz dla spakowanych i rozpakowanych aplikacji klasycznych.

Najpierw w Package.appxmanifestdodaj:

  1. Deklaracja dla xmlns:com
  2. Deklaracja xmlns:desktop
  3. W atrybucie IgnorableNamespaces, com i desktop
  4. desktop:Extension for windows.toastNotificationActivation w celu zadeklarowania CLSID aktywatora powiadomień toast (przy użyciu nowego wybranego identyfikatora GUID).
  5. MSIX tylko: com:Extension dla aktywatora COM przy użyciu identyfikatora GUID z kroku #4. Pamiętaj, aby dodać Arguments="-ToastActivated", aby się upewnić, że uruchomienie pochodzi z powiadomienia.

Package.appxmanifest

<!--Add these namespaces-->
<Package
  ...
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  IgnorableNamespaces="... com desktop">
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

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

        <!--Register COM CLSID LocalServer32 registry key-->
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="YourProject\YourProject.exe" Arguments="-ToastActivated" DisplayName="Toast activator">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" DisplayName="Toast activator"/>
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>

      </Extensions>
    </Application>
  </Applications>
 </Package>

Następnie w kodzie uruchamiania aplikacji (App.xaml.cs OnStartup for WPF), zasubskrybuj zdarzenie OnActivated.

// Listen to notification activation
ToastNotificationManagerCompat.OnActivated += toastArgs =>
{
    // Obtain the arguments from the notification
    ToastArguments args = ToastArguments.Parse(toastArgs.Argument);

    // Obtain any user input (text boxes, menu selections) from the notification
    ValueSet userInput = toastArgs.UserInput;

    // Need to dispatch to UI thread if performing UI operations
    Application.Current.Dispatcher.Invoke(delegate
    {
        // TODO: Show the corresponding content
        MessageBox.Show("Toast activated. Args: " + toastArgs.Argument);
    });
};

Gdy użytkownik kliknie dowolne powiadomienie (lub przycisk na powiadomieniu), stanie się co następuje...

Jeśli aplikacja aktualnie działa...

  1. Zdarzenie ToastNotificationManagerCompat.OnActivated zostanie wywołane w wątku w tle.

Jeśli aplikacja jest obecnie zamknięta...

  1. Plik EXE twojej aplikacji zostanie uruchomiony i ToastNotificationManagerCompat.WasCurrentProcessToastActivated() zwróci wartość true, aby wskazać, że proces został uruchomiony z powodu nowoczesnej aktywacji i że procedura obsługi zdarzeń zostanie wkrótce wywołana.
  2. Następnie zdarzenie ToastNotificationManagerCompat.OnActivated zostanie wywołane w wątku w tle.

Krok 4. Obsługa odinstalowywania

Nie musisz nic robić! Po odinstalowaniu aplikacji MSIX wszystkie powiadomienia i wszystkie inne powiązane zasoby są automatycznie czyszczone.

Dodawanie obrazów

Możesz dodać bogatą zawartość do powiadomień. Dodamy obraz umieszczony w treści i obraz profilu zastępujący logo aplikacji.

Note

Obrazy mogą być używane z pakietu aplikacji, z lokalnej pamięci aplikacji lub z Internetu. W ramach aktualizacji Fall Creators Update obrazy internetowe mogą mieć do 3 MB na zwykłych połączeniach i 1 MB w przypadku połączeń taryfowych. Na urządzeniach, na których nie uruchomiono jeszcze aktualizacji Fall Creators Update, obrazy internetowe nie mogą być większe niż 200 KB.

Important

Obrazy HTTP są obsługiwane tylko w spakowanych aplikacjach, które w swoim manifeście mają uprawnienia do internetu. Aplikacje rozpakowane nie obsługują obrazów http; Musisz pobrać obraz do danych aplikacji lokalnej i odwoływać się do niego lokalnie.

Komunikat z obrazami 
// 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();

Dodawanie przycisków i danych wejściowych

Możesz dodawać przyciski i dane wejściowe, aby otrzymywać powiadomienia interakcyjne. Przyciski mogą uruchamiać aplikację pierwszego planu, protokół lub zadanie w tle. Dodamy pole tekstowe odpowiedzi, przycisk "Lubię to" i przycisk "Wyświetl", który otwiera obraz.

Zrzut ekranu przedstawiający powiadomienie aplikacji z danymi wejściowymi i przyciskami 
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();

Aktywowanie przycisków widocznych na pierwszym planie jest realizowane w taki sam sposób jak główna treść powiadomienia (zostanie wywołana App.xaml.cs OnActivated).

Należy pamiętać, że argumenty dodane do powiadomienia aplikacji najwyższego poziomu (na przykład identyfikator konwersacji) również zostaną zwrócone po kliknięciu przycisków, o ile przyciski używają API AddArgument, jak pokazano powyżej (jeśli przypiszesz niestandardowe argumenty do przycisku, argumenty najwyższego poziomu nie zostaną uwzględnione).

Obsługa aktywacji w tle

W przypadku aplikacji klasycznych aktywacje w tle są obsługiwane tak samo jak w przypadku aktywacji na pierwszym planie (zostanie wyzwolona program obsługi zdarzeń OnActivated). Możesz zrezygnować z wyświetlania żadnego interfejsu użytkownika i zamknąć aplikację po zakończeniu obsługi aktywacji.

Ustawianie czasu wygaśnięcia

W systemie Windows 10 wszystkie powiadomienia aplikacji są wyświetlane w Centrum akcji po ich odrzuceniu lub zignorowaniu przez użytkownika, dzięki czemu użytkownicy mogą przeglądać powiadomienia po zakończeniu wyskakującego okienka.

Jeśli jednak komunikat w powiadomieniu jest odpowiedni tylko przez pewien czas, należy ustawić czas wygaśnięcia powiadomienia aplikacji, aby użytkownicy nie widzieli nieaktualnych informacji z aplikacji. Jeśli na przykład promocja jest ważna tylko przez 12 godzin, ustaw czas wygaśnięcia na 12 godzin. W poniższym kodzie ustawiliśmy czas wygaśnięcia na 2 dni.

Note

Domyślny i maksymalny czas wygaśnięcia dla powiadomień aplikacji lokalnych to 3 dni.

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

Podaj klucz podstawowy dla powiadomienia

Jeśli chcesz programowo usunąć lub zamienić wysyłane powiadomienie, musisz użyć właściwości Tag (i opcjonalnie właściwości Grupa), aby podać klucz podstawowy powiadomienia. Następnie możesz użyć tego klucza podstawowego w przyszłości, aby usunąć lub zamienić powiadomienie.

Aby wyświetlić więcej szczegółów dotyczących zastępowania/usuwania już dostarczonych powiadomień aplikacji, zobacz Szybki start: Zarządzanie powiadomieniami toast w centrum akcji (XAML).

Tag i grupa łączone działają jako złożony klucz podstawowy. Grupa to bardziej ogólny identyfikator, w którym można przypisywać grupy, takie jak "wallPosts", "messages", "friendRequests" itp. Następnie tag powinien jednoznacznie zidentyfikować samo powiadomienie z grupy. Korzystając z grupy ogólnej, można usunąć wszystkie powiadomienia z tej grupy przy użyciu interfejsu API RemoveGroup.

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

Wyczyść powiadomienia

Aplikacje są odpowiedzialne za usuwanie i czyszczenie własnych powiadomień. Po uruchomieniu aplikacji nie usuwamy automatycznie powiadomień.

System Windows automatycznie usunie powiadomienie tylko wtedy, gdy użytkownik jawnie kliknie powiadomienie.

Oto przykład tego, co powinna zrobić aplikacja do obsługi komunikatów...

  1. Użytkownik otrzymuje wiele powiadomień aplikacji o nowych wiadomościach w konwersacji.
  2. Użytkownik kliknie jedno z tych powiadomień, aby otworzyć konwersację.
  3. Aplikacja otwiera konwersację, a następnie czyści wszystkie powiadomienia dotyczące tej konwersacji (przy użyciu polecenia RemoveGroup w grupie dostarczonej przez aplikację dla tej konwersacji).
  4. Centrum akcji użytkownika teraz prawidłowo odzwierciedla stan powiadomienia, ponieważ w Centrum akcji nie ma już nieaktualnych powiadomień dla tej konwersacji.

Aby dowiedzieć się więcej o wyczyszczeniu wszystkich powiadomień lub usunięciu konkretnych powiadomień, zobacz Szybki start: Zarządzanie powiadomieniami toast w centrum akcji (XAML).

ToastNotificationManagerCompat.History.Clear();

Resources

  • Last updated on