Aracılığıyla paylaş

Hızlı Başlangıç: Windows Uygulama SDK'sında uygulama bildirimleri

Görev çubuğunun üzerinde uygulama bildirimini gösteren ekran görüntüsü. Bildirim, bir olay için anımsatıcıdır. Uygulama adı, olay adı, olay zamanı ve olay konumu gösterilir. Seçim girişi seçili durumdaki

Bu hızlı başlangıçta, Windows Uygulama SDK'sınıkullanarak bildirim bildirimleri olarak da bilinen yerel uygulama bildirimleri gönderen ve alan bir masaüstü Windows uygulaması oluşturacaksınız.

Önemli

Yükseltilmiş (yönetici) bir uygulama için bildirimler şu anda desteklenmemektedir.

Önkoşullar

Örnek uygulama

Bu hızlı başlangıçta, GitHubüzerinde bulunan bildirim örnek uygulamalarından alınan kodlar yer alır.

Örnek Uygulama Kodu

API referansı

Uygulama bildirimlerine yönelik API başvuru belgeleri için bkz. Microsoft.Windows.AppNotifications Ad Alanı.

1. Adım: Ad alanı bildirimleri ekleme

Windows Uygulama SDK uygulama bildirimleri için ad alanını Microsoft.Windows.AppNotificationsekleyin.

using Microsoft.Windows.AppNotifications;

2. Adım: Uygulamanızın bildirimini güncelleştirme

Uygulamanız paketten çıkarılmışsa (yani, çalışma zamanında paket kimliği eksikse) 3. Adım:bir uygulama bildirimi işlemek için kaydetme bölümüne atlayın.

Uygulamanız paketlenmiş durumda ise (harici konumla paketlenme dahil):

  1. Package.appxmanifestdosyasını açın.
  2. xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"'ye xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" ve <Package> ad alanlarını ekle
  3. COM etkinleştiricinizi tanımlamak için <desktop:Extension>'e windows.toastNotificationActivation ekleyin, CLSID. Visual Studio'da Araçları altında GUID Oluşturma'ne giderek bir CLSID elde edebilirsiniz.
  4. Aynı CLSID kullanarak COM etkinleştiricisi için <com:Extension> ekleyin.
    1. Executable özniteliğinde .exe dosyanızı belirtin. .exe dosyası, uygulamanızı bildirimlere kaydederken Register() çağıran işlemle aynı olmalıdır. Bu işlem, Adım 3'nde daha fazla açıklanmıştır. Aşağıdaki örnekte Executable="SampleApp\SampleApp.exe"kullanıyoruz.
    2. Windows Uygulama SDK'sı'nın bildiriminizin yükünü appNotification türü olarak işleyebilmesini sağlamak için Arguments="----AppNotificationActivated:" belirtin.
    3. DisplayNamebelirtin.

Önemli

Uyarı: ile appx bildiriminizde <uap:Protocol> uygulama genişletilebilirlik türü tanımlarsanız, uygulamanız zaten çalışıyor olsa bile bildirimlere tıklandığında aynı uygulamanın yeni işlemleri başlatılır.

<!--Packaged apps only-->
<!--package.appxmanifest-->

<Package
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

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

        <!--Register COM CLSID-->    
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="SampleApp\SampleApp.exe" DisplayName="SampleApp" Arguments="----AppNotificationActivated:">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" />
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>
    
      </Extensions>
    </Application>
  </Applications>
 </Package>

3. Adım: Uygulama bildirimini işlemek için kaydolma

Bildirimleri işlemek için uygulamanızı kaydedin, ardından uygulamanız sonlandırıldığında kaydını kaldırın.

App.xaml dosyanızda AppNotificationManager::Default().NotificationInvokediçin kaydolun, ardından AppNotificationManager::Default().Registerçağırın. Bu aramaların sırası önemlidir.

Önemli

AppNotificationManager::Default().Register çağırmalısınız, ardından AppInstance.GetCurrent.GetActivatedEventArgsçağırmadan önce.

Uygulamanız sonlandırılırken AppNotificationManager::D efault() çağrısında bulun. Unregister() COM sunucusunu boşaltmak ve sonraki çağrıların yeni bir işlem başlatmasına izin vermektir.

// App.xaml.cs
namespace CsUnpackagedAppNotifications
{

    public partial class App : Application
    {
        private Window mainWindow;
        private NotificationManager notificationManager;
        
        public App()
        {
            this.InitializeComponent();
            notificationManager = new NotificationManager();
            AppDomain.CurrentDomain.ProcessExit += new EventHandler(OnProcessExit);
        }

        protected override void OnLaunched(LaunchActivatedEventArgs args)
        {
            mainWindow = new MainWindow();

            notificationManager.Init();
            
            // Complete in Step 5
            
            mainWindow.Activate();
        }

        void OnProcessExit(object sender, EventArgs e)
        {
            notificationManager.Unregister();
        }
    }
}


// NotificationManager.cs
namespace CsUnpackagedAppNotifications
{
    internal class NotificationManager
    {
        private bool m_isRegistered;

        private Dictionary<int, Action<AppNotificationActivatedEventArgs>> c_map;

        public NotificationManager()
        {
            m_isRegistered = false;

            // When adding new a scenario, be sure to add its notification handler here.
            c_map = new Dictionary<int, Action<AppNotificationActivatedEventArgs>>();
            c_map.Add(ToastWithAvatar.ScenarioId, ToastWithAvatar.NotificationReceived);
            c_map.Add(ToastWithTextBox.ScenarioId, ToastWithTextBox.NotificationReceived);
        }

        ~NotificationManager()
        {
            Unregister();
        }

        public void Init()
        {
            // To ensure all Notification handling happens in this process instance, register for
            // NotificationInvoked before calling Register(). Without this a new process will
            // be launched to handle the notification.
            AppNotificationManager notificationManager = AppNotificationManager.Default;

            notificationManager.NotificationInvoked += OnNotificationInvoked;

            notificationManager.Register();
            m_isRegistered = true;
        }

        public void Unregister()
        {
            if (m_isRegistered)
            {
                AppNotificationManager.Default.Unregister();
                m_isRegistered = false;
            }
        }

        public void ProcessLaunchActivationArgs(AppNotificationActivatedEventArgs notificationActivatedEventArgs)
        {
            // Complete in Step 5
        }

    }
}

4. Adım: Uygulama bildirimi görüntüleme

DüğmeApp notification with buttonApp notification with buttonile uygulama bildirimi

Devam etmeden önce 3. Adım: Kayıt uygulama bildirimi işlemek için tamamlamanız GEREKIR.

Şimdi appLogoOverride görüntü ve düğme içeren basit bir uygulama bildirimi görüntüleyeceksiniz.

AppNotificationBuilder sınıfını kullanarak uygulama bildiriminizi oluşturun ve ardından Showçağrısı yapın. XML kullanarak uygulama bildiriminizi oluşturma hakkında daha fazla bilgi için lütfen Toast içerik ve Notifications XML şemasımakalelerindeki örneklere bakın.

Not

Uygulamanız paketlenmişse (harici bir konumda paketlenmiş dahil), uygulamanızın bildirim bölümünün sol üst köşesindeki simgesi package.manifestkaynaklıdır. Uygulamanız paketten çıkarılmışsa, simgenin kaynağı önce kısayoldan, ardından uygulama işlemindeki kaynak dosyasından alınır. Tüm denemeler başarısız olursa Windows varsayılan uygulama simgesi kullanılır. Desteklenen simge dosya türleri .jpg, .png, .bmpve .ico.

// ToastWithAvatar.cs
class ToastWithAvatar
{
    public const int ScenarioId = 1;
    public const string ScenarioName = "Local Toast with Avatar Image";

    public static bool SendToast()
    {
        var appNotification = new AppNotificationBuilder()
            .AddArgument("action", "ToastClick")
            .AddArgument(Common.scenarioTag, ScenarioId.ToString())
            .SetAppLogoOverride(new System.Uri("file://" + App.GetFullPathToAsset("Square150x150Logo.png")), AppNotificationImageCrop.Circle)
            .AddText(ScenarioName)
            .AddText("This is an example message using XML")
            .AddButton(new AppNotificationButton("Open App")
                .AddArgument("action", "OpenApp")
                .AddArgument(Common.scenarioTag, ScenarioId.ToString()))
            .BuildNotification();

        AppNotificationManager.Default.Show(appNotification);

        return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }

    public static void NotificationReceived(AppNotificationActivatedEventArgs notificationActivatedEventArgs)
    {
        // Complete in Step 5   
    }
}

// Call SendToast() to send a notification.

5. Adım: Bildirim seçen bir kullanıcıyı işleme

Kullanıcılar bildiriminizin gövdesini veya düğmesini seçebilir. Uygulamanızın bildiriminizle etkileşim kuran bir kullanıcıya yanıt olarak çağrıyı işlemesi gerekir.

Bunu işlemenin 2 yaygın yolu vardır:

  1. Uygulamanızın belirli bir kullanıcı arabirimi bağlamında başlatılmasını veya
  2. Uygulamanızın herhangi bir kullanıcı arabirimi işlemeden eyleme özgü bir davranışı (bildirim gövdesindeki bir düğmeye basma gibi) değerlendirmesini seçebilirsiniz. Arka plan eylemi olarak da bilinir.

Aşağıdaki örnek uygulamadan alınmayan kod örneği, kullanıcı tarafından oluşturulan bir eylemi işlemenin her iki yolunu da gösterir. Bildiriminizin XML yüküne bir launch değeri (bildirim gövdesine tıklayan kullanıcıya karşılık gelir), bir input öğesi (hızlı yanıt metin kutusu) ve arguments değerine sahip bir düğme (düğmeye tıklayan kullanıcıya karşılık gelir) ekleyin. Argümanların her birinde, ProcessLaunchActivationArgsbüyük/küçük harf duyarlılığı üzerinde durun.

Önemli

Bildirim XML yükündeki activationType="background" ayarı masaüstü uygulamaları için yoksayılır. Bunun yerine etkinleştirme bağımsız değişkenlerini işlemeli ve bu adımda belirtildiği gibi bir pencere görüntüleyip görüntülemeyeceğine karar vermelisiniz.

Yanıt ile Uygulama bildirimi

// Example of how to process a user either selecting the notification body or inputting a quick reply in the text box. 

// Notification XML payload
//<toast launch="action=openThread&amp;threadId=92187">
//  <visual>
//      <binding template="ToastGeneric">
//          <image placement="appLogoOverride" hint-crop="circle" src="C:\<fullpath>\Logo.png"/>
//          <text>Local Toast with Avatar and Text box</text>
//          <text>This is an example message using</text>
//      </binding>
//  </visual>
//  <actions>
//      <input id="replyBox" type="text" placeHolderContent="Reply" />
//      <action
//          content="Send"
//          hint-inputId="replyBox"
//          arguments="action=reply&amp;threadId=92187" />
//  </actions>
//</toast>

void ProcessLaunchActivationArgs(const winrt::AppNotificationActivatedEventArgs& notificationActivatedEventArgs)
{
    // If the user clicks on the notification body, your app needs to launch the chat thread window
    if (std::wstring(notificationActivatedEventArgs.Argument().c_str()).find(L"openThread") != std::wstring::npos)
    {
        GenerateChatThreadWindow();
    }
    else // If the user responds to a message by clicking a button in the notification, your app needs to reply back to the other user with no window launched
    if (std::wstring(notificationActivatedEventArgs.Argument().c_str()).find(L"reply") != std::wstring::npos)
    {
        auto input = notificationActivatedEventArgs.UserInput();
        auto replyBoxText = input.Lookup(L"replyBox");

        // Process the reply text
        SendReplyToUser(replyBoxText);
    }
}

aşağıdaki yönergeleri izleyin:

  1. Kullanıcı tarafından bir bildirim seçilirse ve uygulamanız çalışmıyorsa, uygulamanızın başlatılması ve kullanıcının bildirimin bağlamında ön plan penceresini görebilmesi beklenir.
  2. Kullanıcı tarafından bir bildirim seçilirse ve uygulamanız simge durumuna küçültülmüşse, uygulamanızın ön plana getirilmesi ve bildirimin bağlamında yeni bir pencere oluşturulması beklenir.
  3. Kullanıcı tarafından bir bildirim arka planı eylemi çağrılırsa (örneğin, kullanıcı bildirim metin kutusuna yazarak ve yanıtla'ya basarak bir bildirime yanıt verirse), uygulamanız ön plan penceresi oluşturmadan yükü işler.

Daha ayrıntılı bir örnek için github bulunan örnek uygulama koduna bakın.

6. Adım: Bildirimleri kaldırma

Artık kullanıcıyla ilgili olmayan bildirimleri kaldırın.

Bu örnekte, kullanıcı uygulamanızda bir grup sohbetinden gelen tüm iletileri görmüştür, bu nedenle grup sohbetindeki tüm bildirimleri temizlersiniz. Ardından, kullanıcı bir arkadaşı sessize alır, böylece arkadaşınızdan gelen tüm bildirimleri temizlersiniz. Bildirimleri şimdi tanımlayabilmek için, önce Grup ve Etiket özelliklerini eklediniz.


void SendNotification(winrt::hstring const& payload, winrt::hstring const& friendId, winrt::hstring const& groupChatId)
{
    winrt::AppNotification notification(payload);

    // Setting Group Id here allows clearing notifications from a specific chat group later
    notification.Group(groupChatId);

    // Setting Tag Id here allows clearing notifications from a specific friend later
    notification.Tag(friendId);

    winrt::AppNotificationManager::Default().Show(notification);
}

winrt::Windows::Foundation::IAsyncAction RemoveAllNotificationsFromGroupChat(const std::wstring groupChatId)
{
    winrt::AppNotificationManager manager = winrt::AppNotificationManager::Default();
    co_await manager.RemoveByGroupAsync(groupChatId);    
}

winrt::Windows::Foundation::IAsyncAction RemoveAllNotificationsFromFriend(const std::wstring friendId)
{
    winrt::AppNotificationManager manager = winrt::AppNotificationManager::Default();
    co_await manager.RemoveByTagAsync(friendId);    
}

Ek özellikler

Bulut kaynaklı uygulama bildirimi gönderme

Buluttan uygulama bildirimi göndermek için, Hızlı Başlangıç: Windows Uygulama SDK'sında anında iletme bildirimleriadresinden Bulut kaynaklı uygulama bildirimi gönderme izleyin.

Süre sonu ayarlama

Bildiriminizdeki ileti yalnızca belirli bir süre için uygunsa Expiration özelliğini kullanarak uygulama bildiriminizde bir süre sonu ayarlayın. Örneğin, bir takvim olayı anımsatıcısı gönderirseniz, son kullanma süresini takvim olayının sonuna ayarlayın.

Not

Varsayılan ve en uzun süre sonu süresi 3 gündür.

class ToastWithAvatar
{
    public static bool SendToast()
    {

        var appNotification = new AppNotificationBuilder()
            .SetAppLogoOverride(new System.Uri("ms-appx:///images/logo.png"), AppNotificationImageCrop.Circle)
            .AddText("Example expiring notification")
            .AddText("This is an example message")
            .BuildNotification();


        appNotification.Expiration = DateTime.Now.AddDays(1);
        AppNotificationManager.Default.Show(appNotification);

        return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }
}

Yeniden başlatmada bildirimlerin süresinin dolduğundan emin olun

Yeniden başlatmada bildirimlerin silinmesini istiyorsanız ExpiresOnReboot özelliğini True olarak ayarlayın.

class ToastWithAvatar
{
    public static bool SendToast()
    {

        var appNotification = new AppNotificationBuilder()
            .SetAppLogoOverride(new System.Uri("ms-appx:///images/logo.png"), AppNotificationImageCrop.Circle)
            .AddText("Example ExpiresOnReboot notification")
            .AddText("This is an example message")
            .BuildNotification();


            appNotification.ExpiresOnReboot = true;
            AppNotificationManager.Default.Show(appNotification);

            return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }
}

İlerleme çubuğu bildirimi gönderme ve güncelleştirme

İlerleme çubuğuyla ilgili güncelleştirmeleri bir bildirimde görüntüleyebilirsiniz:

İlerleme çubuğu bildirimi

İlerleme çubuğu bildirimini güncelleştirmek için AppNotificationProgressData yapısını kullanın.

const winrt::hstring c_tag = L"weekly-playlist";
const winrt::hstring c_group = L"downloads";

// Send first Notification Progress Update
void SendUpdatableNotificationWithProgress()
{
    auto notification{ winrt::AppNotificationBuilder()
            .AddText(L"Downloading this week's new music...")
            .AddProgressBar(winrt::AppNotificationProgressBar()
                .BindTitle()
                .BindValue()
                .BindValueStringOverride()
                .BindStatus())
            .BuildNotification() }

    notification.Tag(c_tag);
    notification.Group(c_group);

    // Assign initial values for first notification progress UI
    winrt::AppNotificationProgressData data(1); // Sequence number
    data.Title(L"Weekly playlist"); // Binds to {progressTitle} in xml payload
    data.Value(0.6); // Binds to {progressValue} in xml payload
    data.ValueStringOverride(L"15/26 songs"); // Binds to {progressValueString} in xml payload
    data.Status(L"Downloading..."); // Binds to {progressStatus} in xml payload

    notification.Progress(data);
    winrt::AppNotificationManager::Default().Show(notification);
}

// Send subsequent progress updates
winrt::Windows::Foundation::IAsyncAction UpdateProgressAsync()
{
    // Assign new values
    winrt::AppNotificationProgressData data(2 /* Sequence number */ );
    data.Title(L"Weekly playlist"); // Binds to {progressTitle} in xml payload
    data.Value(0.7); // Binds to {progressValue} in xml payload
    data.ValueStringOverride(L"18/26 songs"); // Binds to {progressValueString} in xml payload
    data.Status(L"Downloading..."); // Binds to {progressStatus} in xml payload

    auto result = co_await winrt::AppNotificationManager::Default().UpdateAsync(data, c_tag, c_group);
    if (result == winrt::AppNotificationProgressResult::AppNotificationNotFound)
    {
        // Progress Update failed since the previous notification update was dismissed by the user! So account for this in your logic by stopping updates or starting a new Progress Update flow.
    }
}

Kaynaklar