Udostępnij za pośrednictwem

Wysyłanie lokalnego powiadomienia wyskakującego z aplikacji napisanej w C#

Powiadomienie typu toast to wiadomość, którą aplikacja może skonstruować i dostarczyć użytkownikowi, kiedy użytkownik nie jest obecnie w aplikacji.

zrzut ekranu powiadomienia typu

Ten przewodnik szybkiego startu przeprowadzi Cię przez kroki tworzenia, dostarczania i wyświetlania powiadomienia toast dla systemu Windows 10 lub Windows 11, przy użyciu rozbudowanej 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!

Ważne

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.

Ważne

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żyć jednej z docelowych platform systemu Windows, w przeciwnym razie interfejsy API do wysyłania i zarządzania powiadomieniami toast, takie jak Show(), będą niedostępne. 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ń toast bez użycia kodu XML, a także pozwala aplikacjom klasycznym na wysyłanie powiadomień toast.

Krok 2: Wyślij komunikat

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

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.

Gdy użytkownik kliknie powiadomienie (lub przycisk w powiadomieniu z aktywacją pierwszego planu), zostanie wywołana funkcja App.xaml.csOnActivated, a dodane argumenty zostaną zwrócone.

App.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
    }
}

Ważne

Musisz zainicjować ramkę i aktywować okno tak jak w kodzie OnLaunched. OnLaunched nie jest wywoływana, jeśli użytkownik kliknie wyskakujące, nawet jeśli aplikacja została zamknięta i jest uruchamiana po raz pierwszy. Często zalecamy połączenie OnLaunched i OnActivated we własną metodę OnLaunchedOrActivated, ponieważ w obu tych przypadkach musi wystąpić ta sama inicjalizacja.

Krok 4. Obsługa odinstalowywania

Nie musisz nic robić! Po odinstalowaniu aplikacji UWP wszystkie powiadomienia oraz inne powiązane zasoby są automatycznie usuwane.

Dodawanie obrazów

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

Uwaga / Notatka

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.

Ważne

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 typu toast 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();

Aktywacja przycisków pierwszego planu jest obsługiwana w taki sam sposób, jak główne powiadomienie (zostanie wywołana metoda OnActivated w App.xaml.cs).

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

Obsługa aktywacji w tle

Po określeniu aktywacji w tle dla powiadomienia typu toast (lub dla przycisku wewnątrz tego powiadomienia), zadanie w tle zostanie wykonane zamiast uruchamiania aplikacji pierwszego planu.

Aby uzyskać więcej informacji na temat zadań w tle, zobacz Obsługa aplikacji z zadaniami w tle.

Jeśli celujesz w wersję 14393 lub nowszą, możesz użyć zadań w tle w obrębie procesu, które znacznie upraszczają pracę. Należy pamiętać, że zadania w tle w procesie nie będą działać w starszych wersjach systemu Windows. W tym przykładzie kodu użyjemy zadania w tle w ramach procesu.

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();

Następnie w App.xaml.cs przesłoń metodę OnBackgroundActivated. Następnie możesz pobrać wstępnie zdefiniowane argumenty i dane wejściowe użytkownika, podobnie jak w przypadku aktywacji na pierwszym planie.

App.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();
}

Ustawianie czasu wygaśnięcia

W systemie Windows 10 wszystkie wyskakujące powiadomienia idą w Centrum akcji po ich odrzuceniu lub zignorowaniu przez użytkownika, aby użytkownicy mogli przyjrzeć się powiadomieniu po zakończeniu wyskakującego okienka.

Jeśli jednak komunikat w powiadomieniu jest istotny tylko przez pewien czas, należy ustawić czas wygaśnięcia dla powiadomienia typu toast, aby użytkownicy nie widzieli nieaktualnych informacji z Twojej 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.

Uwaga / Notatka

Domyślny i maksymalny czas wygaśnięcia dla lokalnych powiadomień toast wynosi 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 komunikatu

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 uzyskać więcej informacji na temat zastępowania/usuwania już dostarczonych powiadomień toast, zobacz Krótki przewodnik: 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 liczne powiadomienia o nowych wiadomościach w konwersacji.
  2. Użytkownik dotknie jednego z tych powiadomień, aby otworzyć konwersację.
  3. Aplikacja otwiera konwersację, a następnie usuwa wszystkie powiadomienia dla tej konwersacji (używając 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();

Zasoby