C# アプリからローカルのトースト通知を送信する

トースト通知は、アプリが現在アプリ内にないときに、ユーザーに対して作成および配信できるメッセージです。

Screenshot of a toast notification

このクイックスタートでは、リッチコンテンツと対話型アクションを使用して Windows 10 トースト通知を作成、配信、および表示する手順について説明します。 このクイックスタートでは、実装するための最も簡単な通知であるローカル通知を使用します。 すべての種類のアプリ (WPF、UWP、WinForms、コンソール) は、通知を送信できます。

重要

C++ アプリを作成している場合は、 C++ UWP または c++ wrl のドキュメントを参照してください。

手順 1: NuGet パッケージをインストールする

Visual Studio ソリューション内で、プロジェクトを右クリックし 、[NuGet パッケージの管理...] をクリックして、NuGet パッケージ バージョン Microsoft.Toolkit.Uwp.Notifications 7.0 以上を検索してインストールします。

重要

.NET Frameworkを使用しているデスクトップ アプリpackages.config PackageReference に移行する必要があります。そうしないと、Windows 10 SDK が正しく参照されません。 プロジェクトで [参照] を右クリックし、[Migrate packages.config to PackageReference]をクリックします。

.NET Core 3.0 WPF アプリは .NET Core 3.1 に更新する必要があります。そうしないと、API は存在しません。

.NET 5アプリでは、TMS の 1 つWindows 10使用する必要があります。そうしないと、 のようなトースト送信 API と管理 API Show() が見つからない可能性があります。 TFM を 以上 net5.0-windows10.0.17763.0 に設定します。

このサンプルコードでは、このパッケージを使用します。 このパッケージを使用すると、XML を使用せずにトースト通知を作成できます。また、デスクトップアプリでも、toasts を送信できます。

手順 2: トーストを送信する

Windows 10 では、トースト通知のコンテンツは、通知の外観にすばらしい柔軟性を持たせることができるアダプティブ言語を使って表されます。 詳細については、 トーストコンテンツのドキュメントを参照してください。

単純なテキストベースの通知から始めます。 通知ライブラリを使用して通知コンテンツを作成し、通知を表示します。 名前空間がであることに注意 Microsoft.Toolkit.Uwp.Notifications してください。

Simple text notification
// 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 5, your TFM must be net5.0-windows10.0.17763.0 or greater

このコードを実行すると、通知が表示されます。

手順 3: アクティブ化の処理

通知を表示した後、ユーザーが通知をクリックした場合、ユーザーがクリックしたときに特定のコンテンツを表示したり、アプリを一般に開いたり、ユーザーが通知をクリックしたときにアクションを実行したりすることが必要になる場合があります。

UWP、デスクトップ (MSIX)、およびデスクトップ (パッケージ化されていない) アプリでは、アクティベーションを処理する手順は異なります。

ユーザーが通知 (またはフォアグラウンドアクティベーション付きの通知のボタン) をクリックすると、アプリの app.xamlonactivated が呼び出され、追加した引数が返されます。

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

重要

OnLaunched コードと同様に、フレームを初期化してウィンドウをアクティブ化する必要があります。 OnLaunched は、ユーザーがトーストをクリックしても呼び出されません。アプリが閉じられてから初めて起動している場合も同様です。 通常は、OnLaunchedOnActivated を組み合わせて独自の OnLaunchedOrActivated メソッドにまとめることをお勧めします。これは、両方で同じ初期化を実行する必要があるためです。

手順 4: アンインストールの処理

何もする必要はありません。 UWP アプリがアンインストールされると、すべての通知とその他の関連リソースが自動的にクリーンアップされます。

イメージの追加

豊富なコンテンツを通知に追加できます。 インラインイメージとプロファイル (アプリロゴのオーバーライド) イメージを追加します。

注意

画像は、アプリのパッケージ、アプリのローカル ストレージ、または Web から使用できます。 Fall Creators Update の時点で、Web 画像の上限は通常の接続で 3 MB、従量制課金接続で 1 MB です。 まだ Fall Creators Update を実行していないデバイスでは、Web イメージは 200 KB を上限とします。

重要

Http イメージは、マニフェストにインターネット機能を持つ UWP/MSIX/スパースアプリでのみサポートされています。 デスクトップの非 MSIX/スパースアプリでは、http イメージはサポートされません。ローカルアプリデータにイメージをダウンロードし、ローカルで参照する必要があります。

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

ボタンと入力の追加

ボタンと入力を追加して、通知を対話形式にすることができます。 ボタンを使用すると、フォアグラウンドアプリ、プロトコル、またはバックグラウンドタスクを起動できます。 応答テキストボックス、"Like" ボタン、および [表示] ボタンを追加して、画像を開きます。

Screenshot of a toast notification with inputs and buttons
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();

前面のボタンのアクティブ化は、メインのトーストの本文と同じ方法で処理されます (app.xaml の OnActivated が呼び出されます)。

上に示したように、ボタンが AddArgument API を使用している限り、トップレベルのトースト (メッセージ交換 ID など) に追加された引数も返されます (ボタンで引数を代入する場合、最上位レベルの引数は含まれません)。

バックグラウンドのアクティブ化を処理する

トースト (またはトースト内のボタンで) でバックグラウンドのアクティブ化を指定すると、フォアグラウンド アプリがアクティブ化されるのではなく、バックグラウンド タスクが実行されます。

バックグラウンド タスクについて詳しくは、「バックグラウンド タスクによるアプリのサポート」をご覧ください。

ビルド 14393 以降をターゲットとしている場合、インプロセス バックグラウンド タスクを使用できるため、大幅に簡略化できます。 インプロセス バックグラウンド タスクは古いバージョンの Windows では実行できないことに注意してください。 次のコード サンプルでは、インプロセス バックグラウンド タスクを使います。

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

次に、app.xaml で OnBackgroundActivated 化されたメソッドをオーバーライドします。 その後、事前に定義された引数とユーザー入力を取得できます。これは、フォアグラウンドアクティベーションと同様です。

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

有効期限を設定する

Windows 10 では、ユーザーが閉じるか無視したすべてのトースト通知はアクション センター に送られるため、ユーザーはポップアップが消えた後も通知を表示できます。

ただし、通知に含まれているメッセージが一定期間だけ関係する場合は、トースト通知に有効期限を設定して、アプリからユーザーに古い情報が表示されないようにする必要があります。 たとえば、12 時間限りのキャンペーンの場合は、有効期限を 12 時間に設定します。 以下のコードでは、有効期限が 2 日間に設定されています。

注意

ローカル トースト通知の既定の最長有効期限は 3 日間です。

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

トーストの主キーを提供する

送信した通知をプログラムで削除するか差し替える必要がある場合、Tag プロパティ (および必要に応じて Group プロパティ) を使って通知の主キーを提供する必要があります。 そうすると、今後この主キーを使って、通知の削除や差し替えができるようになります。

既に配信されたトースト通知の差し替えと削除の方法について詳しくは、「クイック スタート: アクション センターでのトースト通知の管理 (XAML)」をご覧ください。

Tag と Group を組み合わせると、復号主キーとして機能します。 Group はより汎用的な ID で、"wallPosts"、"messages"、"friendRequests" などのグループを割り当てることができます。Tag はグループ内から通知自体を一意に識別する必要があります。 汎用グループを使うことで、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";
    });

通知を消去する

アプリは、独自の通知を削除してクリアする役割を担います。 アプリを起動したときに、通知が自動的に消去されることはありません。

Windows では、ユーザーが明示的に通知をクリックした場合のみ、通知を自動的に削除します。

メッセージング アプリの処理の例を以下に示します。

  1. ユーザーが会話の中で新しいメッセージに関する複数のトーストを受け取る
  2. ユーザーがそれらのトーストのいずれかをタップして会話を開く
  3. アプリが会話を開き、その会話のすべてのトーストを消去する (その会話用にアプリが提供するグループで RemoveGroup を使う)
  4. ユーザーのアクション センターが通知の状態を正しく反映して、その会話の古い通知がアクション センターに残らないように処理する

すべての通知を消去する方法または特定の通知を削除する方法については、「クイック スタート: アクション センターでのトースト通知の管理 (XAML)」をご覧ください。

ToastNotificationManagerCompat.History.Clear();

リソース