Odeslání oznámení místní aplikace z aplikace v jazyce C#

Oznámení aplikace je zpráva, že vaše aplikace může sestavit a doručit uživateli, i když nejsou aktuálně uvnitř vaší aplikace.

Tento rychlý start vás provede postupem vytvoření, doručování a zobrazení oznámení aplikace pro Windows 10 nebo Windows 11 pomocí bohatého obsahu a interaktivních akcí. V tomto rychlém startu se používají místní oznámení, což je nejjednodušší oznámení k implementaci. Můžou odesílat oznámení všechny typy aplikací (WPF, UPW, WinForms, konzola).

Note

Termín "notifikace typu toast" se nahrazuje "notifikací aplikace". Oba tyto termíny odkazují na stejnou funkci Windows, ale v průběhu času postupně přestaneme používat termín "toast notification" v dokumentaci.

Important

Pokud píšete aplikaci C++, projděte si dokumentaci k C++ UWP nebo C++ WRL.

Krok 1: Instalace balíčku NuGet

V rámci řešení sady Visual Studio klikněte pravým tlačítkem na projekt, klikněte na Spravovat balíčky NuGet a vyhledejte a nainstalujte balíček NuGet Microsoft.Toolkit.Uwp.Notifications verze 7.0 nebo vyšší.

Important

Desktopové aplikace rozhraní .NET Framework, které stále používají packages.config musí migrovat na PackageReference, jinak se na sady SDK pro Windows nebudou odkazovat správně. V projektu klikněte pravým tlačítkem na Odkazy a klikněte na Migrovat packages.config do PackageReference.

Aplikace WPF .NET Core 3.0 se musí aktualizovat na .NET Core 3.1, jinak budou rozhraní API chybět.

Aplikace .NET musí používat jeden z Windows TFMs, jinak budou chybět rozhraní API pro odesílání a správu oznámení aplikace, jako je Show(). Nastavte TFM na net6.0-windows10.0.17763.0 nebo novější.

Tento balíček použijeme v ukázce kódu. Tento balíček umožňuje vytvářet oznámení aplikací bez použití XML a také umožňuje desktopovým aplikacím odesílat oznámení aplikací.

Krok 2: Odeslání oznámení aplikace

Ve Windows 10 a Windows 11 se obsah oznámení vaší aplikace popisuje pomocí adaptivního jazyka, který umožňuje velkou flexibilitu s tím, jak oznámení vypadá. Další informace najdete v dokumentaci k obsahu oznámení aplikace .

Začneme jednoduchým textovým oznámením. Vytvořte obsah oznámení (pomocí knihovny oznámení) a zobrazte oznámení. Všimněte si, že obor názvů je Microsoft.Toolkit.Uwp.Notifications.

// 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

Zkuste tento kód spustit a měli byste vidět oznámení.

Krok 3: Řešení aktivace

Po zobrazení oznámení budete pravděpodobně muset zpracovat situaci, kdy uživatel klikne na oznámení (ať už to znamená otevřít konkrétní obsah po kliknutí, obecně otevřít aplikaci, nebo provést nějakou akci po kliknutí na oznámení).

Postup pro zpracování aktivace se liší pro UPW a pro zabalené a rozbalené desktopové aplikace.

Desktop (MSIX)

Nejprve v Package.appxmanifestpřidejte:

1. Deklarace pro xmlns:com
2. Deklarace pro xmlns:desktop
3. V atributu IgnorableNamespaces jsou com a desktop
4. desktop:Extension pro windows.toastNotificationActivation deklarovat CLSID aktivátoru oznámení (pomocí nového identifikátoru GUID podle vašeho výběru).
5. Pouze MSIX: com:Extension pro aktivátor COM s použitím identifikátoru GUID z kroku 4. Nezapomeňte zahrnout Arguments="-ToastActivated", abyste věděli, že vaše spuštění bylo z notifikace.

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>

Pak ve spouštěcím kódu aplikace (App.xaml.cs OnStartup pro WPF), přihlaste se k odběru události 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);
    });
};

Když uživatel klikne na některou z vašich oznámení (nebo na tlačítko oznámení), stane se toto...

Pokud vaše aplikace aktuálně běží...

1. Událost ToastNotificationManagerCompat.OnActivated se vyvolá ve vlákně na pozadí.

Pokud je vaše aplikace aktuálně zavřená...

1. Spustí se exe vaší aplikace a ToastNotificationManagerCompat.WasCurrentProcessToastActivated() vrátí hodnotu true, která indikuje, že proces byl spuštěn z důvodu moderní aktivace a že obslužná rutina události bude brzy vyvolána.
2. Potom se ToastNotificationManagerCompat.OnActivated událost vyvolá na pozadí vlákna.

Pracovní plocha (neinstalovaný)

Když uživatel klikne na některou z vašich oznámení (nebo na tlačítko oznámení), stane se toto...

Pokud vaše aplikace aktuálně běží...

1. Událost ToastNotificationManagerCompat.OnActivated se vyvolá ve vlákně na pozadí.

Pokud je vaše aplikace aktuálně zavřená...

1. Spustí se exe vaší aplikace a ToastNotificationManagerCompat.WasCurrentProcessToastActivated() vrátí hodnotu true, která indikuje, že proces byl spuštěn z důvodu moderní aktivace a že obslužná rutina události bude brzy vyvolána.
2. Potom se ToastNotificationManagerCompat.OnActivated událost vyvolá na pozadí vlákna.

Ve spouštěcím kódu aplikace (App.xaml.cs OnStartup pro WPF) se přihlaste k odběru události 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);
    });
};

UWP

Když uživatel klikne na vaše oznámení (nebo na tlačítko na oznámení s aktivací na popředí), bude vyvolána metoda App.xaml.csOnActivated vaší aplikace a budou vráceny argumenty, které jste přidali.

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

Important

Musíte inicializovat svůj rámeček a aktivovat své okno, stejně jako v kódu OnLaunched. OnLaunched není volána, pokud uživatel klikne na oznámení aplikace, i když byla vaše aplikace zavřená a spouští se poprvé. Často doporučujeme kombinovat OnLaunched a OnActivated do vlastní OnLaunchedOrActivated metody, protože stejná inicializace musí nastat v obou případech.

Krok 4: Zpracování odinstalace

Desktop (MSIX)

Nemusíte dělat nic! Když se odinstalují aplikace MSIX, všechna oznámení a všechny další související prostředky se automaticky vyčistí.

Desktop (nebalený)

Pokud má aplikace odinstalátor, měli byste v odinstalačním nástroji volat ToastNotificationManagerCompat.Uninstall();. Pokud je vaše aplikace "přenosná aplikace" bez instalačního programu, zvažte při ukončení aplikace volání této metody, pokud nemáte oznámení, která mají být zachována po zavření aplikace.

Metoda odinstalace vyčistí všechna naplánovaná a aktuální oznámení, odebere všechny přidružené hodnoty registru a odebere všechny přidružené dočasné soubory vytvořené knihovnou.

UWP

Nemusíte dělat nic! Když se odinstalují aplikace pro UPW, všechna oznámení a všechny další související prostředky se automaticky vyčistí.

Přidání obrázků

Do oznámení můžete přidat bohatý obsah. Přidáme obrázek v textu a obrázek profilu (nahrazení loga aplikace).

Note

Obrázky se dají použít z balíčku aplikace, místního úložiště aplikace nebo z webu. Od fall Creators Update můžou být webové obrázky až 3 MB na normálních připojeních a 1 MB u připojení účtovaných podle měr. Na zařízeních, na kterých ještě není spuštěná aktualizace Fall Creators Update, nesmí být webové obrázky větší než 200 kB.

Important

Image HTTP se podporují jenom v zabalených aplikacích, které mají v manifestu funkci internetu. Rozbalené aplikace nepodporují obrázky HTTP; musíte obrázek stáhnout do místních dat aplikace a místně na něj odkazovat.

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

Přidání tlačítek a vstupů

Můžete přidávat tlačítka a vstupní prvky, aby byla vaše oznámení interaktivní. Tlačítka můžou spustit aplikaci na popředí, protokol nebo úlohu na pozadí. Přidáme textové pole odpovědi, tlačítko To se mi líbí a tlačítko Zobrazit, které obrázek otevře.

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

Aktivace tlačítek panelu popředí se zpracovává stejným způsobem jako hlavní tělo oznámení (bude volán váš App.xaml.cs OnActivated).

Všimněte si, že argumenty přidané do oznámení aplikace nejvyšší úrovně (například ID konverzace) se vrátí také po kliknutí na tlačítka, pokud tlačítka používají rozhraní API AddArgument, jak je vidět výše (pokud vlastníte přiřazovat argumenty na tlačítku, argumenty nejvyšší úrovně nebudou zahrnuty).

Zpracování aktivace na pozadí

Desktop

U desktopových aplikací se aktivace na pozadí zpracovávají stejným způsobem jako aktivace na popředí (spustí se vaše obslužná rutina události OnActivated). Po zpracování aktivace se můžete rozhodnout, že se nezobrazí žádné uživatelské rozhraní a aplikaci zavřete.

UWP

Když v oznámení aplikace zadáte aktivaci na pozadí (nebo na tlačítku uvnitř oznámení), spustí se úloha na pozadí místo aktivace aplikace na popředí.

Další informace o úlohách na pozadí najdete v tématu Podpora aplikace pomocí úloh na pozadí.

Pokud cílíte na build 14393 nebo novější, můžete použít úlohy na pozadí v procesu, které výrazně zjednodušují věci. Mějte na paměti, že úlohy na pozadí v procesu nebudou spuštěny ve starších verzích Windows. V této ukázce kódu použijeme úlohu na pozadí 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();

Poté ve vašem souboru App.xaml.cs přepište metodu OnBackgroundActivated. Pak můžete načíst předdefinované argumenty a vstup uživatele, podobně jako při aktivaci na popředí.

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

Nastavení času vypršení platnosti

Ve Windows 10 se všechna oznámení aplikací po tom, co je uživatel zavře nebo ignoruje, ukládají do Centra akcí, takže se na ně uživatelé mohou podívat i poté, co zmizí vyskakovací okno.

Pokud je ale zpráva v oznámení relevantní jenom po určitou dobu, měli byste pro oznámení aplikace nastavit dobu vypršení platnosti, aby se uživatelům nezobražely zastaralé informace z vaší aplikace. Pokud je například povýšení platné jenom 12 hodin, nastavte dobu vypršení platnosti na 12 hodin. V následujícím kódu nastavíme dobu vypršení platnosti na 2 dny.

Note

Výchozí a maximální doba vypršení platnosti oznámení místní aplikace je 3 dny.

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

Zadání primárního klíče pro oznámení

Pokud chcete oznámení, které odesíláte, odebrat nebo nahradit prostřednictvím kódu programu, musíte k zadání primárního klíče pro oznámení použít vlastnost Tag (a volitelně také vlastnost Skupina). Potom můžete tento primární klíč v budoucnu použít k odebrání nebo nahrazení oznámení.

Další podrobnosti o nahrazení nebo odebrání už doručených oznámení aplikací najdete v rychlém startu: Správa informačních oznámení v Centru akcí (XAML).

Kombinace značek a skupin funguje jako složený primární klíč. Skupina je obecnější identifikátor, kde můžete přiřadit skupiny jako "wallPosts", "messages", "friendRequests" atd. Značka by pak měla jednoznačně identifikovat samotné oznámení ze skupiny. Pomocí obecné skupiny pak můžete odebrat všechna oznámení z této skupiny pomocí rozhraní RemoveGroup API.

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

Vymazání oznámení

Aplikace zodpovídají za odebrání a vymazání vlastních oznámení. Po spuštění vaší aplikace automaticky nesmažíme vaše oznámení.

Systém Windows automaticky odebere oznámení pouze v případě, že uživatel explicitně klikne na oznámení.

Tady je příklad toho, co má aplikace pro zasílání zpráv dělat...

1. Uživatel obdrží více oznámení aplikace o nových zprávách v konverzaci.
2. Uživatel klepne na jedno z těchto oznámení a otevře konverzaci.
3. Aplikace otevře konverzaci a pak vymaže všechna oznámení pro danou konverzaci (pomocí removeGroup ve skupině zadané aplikací pro danou konverzaci).
4. Centrum akcí nyní správně odráží stav oznámení, protože v něm nezůstala žádná zastaralá oznámení týkající se této konverzace.

Další informace o odstranění všech oznámení nebo odebrání konkrétních oznámení najdete v tématu Rychlý průvodce: Správa notifikací v centru akcí (XAML).

ToastNotificationManagerCompat.History.Clear();

Resources

• ukázka úplného kódu na GitHubu
• Dokumentace k obsahu oznámení aplikace
• ToastNotification třída
• Třída ToastNotificationActivatedEventArgs