Getting started with Notification Hubs for Windows Universal Platform Apps

Overview

This tutorial shows you how to use Azure Notification Hubs to send push notifications to a Universal Windows Platform (UWP) app.

In this tutorial, you create a blank Windows Store app that receives push notifications by using the Windows Push Notification Service (WNS). When you're finished, you'll be able to use your notification hub to broadcast push notifications to all the devices running your app.

Before you begin

The goal of this topic is to help you get started using Notification Hubs quickly as possible. This topic presents a very simple broadcast scenario example in order to concentrate on the basic concepts for Notification Hubs.

If you are already familiar with Notification Hubs, you may want to select another topic from the left-navigation or see the relevant links in Next steps.

We do take your feedback seriously. If you have any difficulties completing this topic, or recommendations for improving this content, we would appreciate your feedback at the bottom of the page.

The completed code for this tutorial can be found on GitHub here.

Prerequisites

This tutorial requires the following:

Completing this tutorial is a prerequisite for all other Notification Hubs tutorials for Windows Universal Platform apps.

Register your app for the Windows Store

To send push notifications to UWP apps, you must associate your app to the Windows Store. You must then configure your notification hub to integrate with WNS.

  1. If you have not already registered your app, navigate to the Windows Dev Center, sign in with your Microsoft account, and then click Create a new app.
  2. Type a name for your app and click Reserve app name.

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hubs-win8-app-name.png)
    
    This creates a new Windows Store registration for your app.
    
  3. In Visual Studio, create a new Visual C# Store Apps project by using the Blank App template and click OK.

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hub-create-windows-universal-app.png)
    
  4. Accept the defaults for the target and minimum platform versions.
  5. In Solution Explorer, right-click the Windows Store app project, click Store, and then click Associate App with the Store....

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hub-associate-win8-app.png)
    
    The **Associate Your App with the Windows Store** wizard appears.
    
  6. In the wizard, click Sign in and then sign in with your Microsoft account.

  7. Click the app that you registered in step 2, click Next, and then click Associate.

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hub-associate-app-name.png)
    
    This adds the required Windows Store registration information to the application manifest.
    
  8. Back on the Windows Dev Center page for your new app, click Services, click Push notifications, and then click Live Services site under Windows Push Notification Services (WNS) and Microsoft Azure Mobile Apps.

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hubs-uwp-app-live-services.png)
    
  9. On the registration page for your app, make a note of the Application Secret password and the Package security identifier (SID) located in the Windows Store platform settings.

    ![](./media/notification-hubs-windows-store-dotnet-get-started/notification-hubs-uwp-app-push-auth.png)
    

    [AZURE.WARNING] The application secret and package SID are important security credentials. Do not share these values with anyone or distribute them with your app.

Configure your notification hub

  1. Log on to the Azure Portal, and then click +NEW at the top left of the screen.
  2. Click on New, then Web + Mobile. Scroll down if necessary and click Notification Hub.

    Azure Portal - Create Notification Hubs

  3. Make sure you specify a unique name in the Notification Hub field. Select your desired Region, Subscription and Resource Group (if you have one already).

    If you already have a service bus namespace that you want to create the hub in, select it through the Select Existing option in the Namespace field. Otherwise, you can use the default name which will be created based on the hub name as long as the namespace name is available.

    Once ready, click Create.

    Azure Portal - Set notification hub properties

  4. Once the namespace and notification hub are created, you will be taken to the respective portal page.

    Azure Portal - Notification hub portal page

  5. Click on Settings and then Access Policies - take note of the two connection strings that are made available to you, as you will need them to handle push notifications later.

    Azure Portal - Notification hub connection strings

  1. Select the Notification Services option and the Windows (WNS) option. Then enter the Application secret password in the Security Key field. Enter your Package SID value that you obtained from WNS in the previous section, and then click Save.

  

Your notification hub is now configured to work with WNS, and you have the connection strings to register your app and send notifications.

Connect your app to the notification hub

  1. In Visual Studio, right-click the solution, and then click Manage NuGet Packages.

    This displays the Manage NuGet Packages dialog box.

  2. Search for WindowsAzure.Messaging.Managed and click Install, and accept the terms of use.

    This downloads, installs, and adds a reference to the Azure Messaging library for Windows by using the WindowsAzure.Messaging.Managed NuGet package.

  3. Open the App.xaml.cs project file and add the following using statements.

     using Windows.Networking.PushNotifications;
     using Microsoft.WindowsAzure.Messaging;
     using Windows.UI.Popups;
    
  4. Also in App.xaml.cs, add the following InitNotificationsAsync method definition to the App class:

     private async void InitNotificationsAsync()
     {
         var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
    
         var hub = new NotificationHub("< your hub name>", "<Your DefaultListenSharedAccessSignature connection string>");
         var result = await hub.RegisterNativeAsync(channel.Uri);
    
         // Displays the registration ID so you know it was successful
         if (result.RegistrationId != null)
         {
             var dialog = new MessageDialog("Registration successful: " + result.RegistrationId);
             dialog.Commands.Add(new UICommand("OK"));
             await dialog.ShowAsync();
         }
    
     }
    

    This code retrieves the channel URI for the app from WNS, and then registers that channel URI with your notification hub.

    Note

    Make sure to replace the "your hub name" placeholder with the name of the notification hub that appears in the Azure Portal. Also replace the connection string placeholder with the DefaultListenSharedAccessSignature connection string that you obtained from the Access Polices page of your Notification Hub in a previous section.

  5. At the top of the OnLaunched event handler in App.xaml.cs, add the following call to the new InitNotificationsAsync method:

     InitNotificationsAsync();
    

    This guarantees that the channel URI is registered in your notification hub each time the application is launched.

  6. Press the F5 key to run the app. A pop-up dialog that contains the registration key is displayed.

    ![][19]
    

Your app is now ready to receive toast notifications.

Send notifications

You can quickly test receiving notifications in your app by sending notifications in the Azure Portal using the Test Send button on the notification hub, as shown in the screen below.

Push notifications are normally sent in a back-end service like Mobile Services or ASP.NET using a compatible library. You can also use the REST API directly to send notification messages if a library is not available for your back-end.

In this tutorial, we will keep it simple and just demonstrate testing your client app by sending notifications using the .NET SDK for notification hubs in a console application instead of a backend service. We recommend the Use Notification Hubs to push notifications to users tutorial as the next step for sending notifications from an ASP.NET backend. However, the following approaches can be used for sending notifications:

(Optional) Send notifications from a console app

To send notifications by using a .NET console application follow these steps.

  1. Right-click the solution, select Add and New Project..., and then under Visual C#, click Windows and Console Application, and click OK.

    ![][13]
    

    This adds a new Visual C# console application to the solution. You can also do this in a separate solution.

  2. In Visual Studio, click Tools, click NuGet Package Manager, and then click Package Manager Console.

    This displays the Package Manager Console in Visual Studio.

  3. In the Package Manager Console window, set the Default project to your new console application project, and then in the console window, execute the following command:

     Install-Package Microsoft.Azure.NotificationHubs
    

    This adds a reference to the Azure Notification Hubs SDK using the Microsoft.Azure.Notification Hubs NuGet package.

  4. Open the Program.cs file and add the following using statement:

     using Microsoft.Azure.NotificationHubs;
    
  5. In the Program class, add the following method:

     private static async void SendNotificationAsync()
     {
         NotificationHubClient hub = NotificationHubClient
             .CreateClientFromConnectionString("<connection string with full access>", "<hub name>");
         var toast = @"<toast><visual><binding template=""ToastText01""><text id=""1"">Hello from a .NET App!</text></binding></visual></toast>";
         await hub.SendWindowsNativeNotificationAsync(toast);
     }
    
    Make sure to replace the "hub name" placeholder with the name of the notification hub that as it appears in the Azure Portal. Also, replace the connection string placeholder with the **DefaultFullSharedAccessSignature** connection string that you obtained from the **Access Policies** page of your Notification Hub in the section called "Configure your notification hub."
    
    Note

    Make sure that you use the connection string that has Full access, not Listen access. The listen-access string does not have permissions to send notifications.

  6. Add the following lines in the Main method:

      SendNotificationAsync();
      Console.ReadLine();
    
  7. Right-click the console application project in Visual Studio, and click Set as StartUp Project to set it as the startup project. Then press the F5 key to run the application.

    ![][14]
    

    You will receive a toast notification on all registered devices. Clicking or tapping the toast banner loads the app.

You can find all the supported payloads in the toast catalog, tile catalog, and badge overview topics on MSDN.

Next steps

In this simple example, you sent broadcast notifications to all your Windows devices using the portal or a console app. We recommend the Use Notification Hubs to push notifications to users tutorial as the next step. It will show you how to send notifications from an ASP.NET backend using tags to target specific users.

If you want to segment your users by interest groups, see Use Notification Hubs to send breaking news.

To learn more general information about Notification Hubs, see Notification Hubs Guidance.