Code generated by the push notification wizard
By using a wizard in Visual Studio, you can generate push notifications from a mobile service that was created with Azure Mobile Services. The Visual Studio wizard generates code to help you get started. This topic explains how the wizard modifies your project, what the generated code does, how to use this code, and what you can do next to get the most out of push notifications. See Windows Push Notification Services (WNS) overview.
How the wizard modifies your project
The push notification wizard modifies your project in the following ways:
- Adds a reference to Mobile Services Managed Client (MobileServicesManagedClient.dll). Not applicable to JavaScript projects.
- Adds a file in a subfolder under services, and names the file push.register.cs, push.register.vb, push.register.cpp, or push.register.js.
- Creates a channels table on the database server for the mobile service. The table contains information that's required to send push notifications to app instances.
- Creates scripts for four functions: delete, insert, read and update.
- Creates a script with a custom API, notifyallusers.js, which sends a push notification to all clients.
- Adds a declaration to your App.xaml.cs, App.xaml.vb, or App.xaml.cpp file, or adds a declaration to a new file, service.js, for JavaScript projects. The declaration declares a MobileServiceClient object, which contains the information that's required to connect to the mobile service. You can access this MobileServiceClient object, which is named MyServiceNameClient, from any page in your app by using the name App.MyServiceNameClient.
The services.js file contains the following code:
var <mobile-service-name>Client = new Microsoft.WindowsAzure.MobileServices.MobileServiceClient(
"https://<mobile-service-name>.azure-mobile.net/",
"<your client secret>");
Registration for push notifications
In push.register.*, the UploadChannel method registers the device to receive push notifications. The Windows Store tracks installed instances of your app and provides the push notification channel. See PushNotificationChannelManager.
The client code is similar for both the JavaScript backend and the .NET backend. By default, when you add push notifications for a JavaScript backend service, a sample call to notifyAllUsers custom API is inserted into the UploadChannel method.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Microsoft.WindowsAzure.MobileServices;
using Newtonsoft.Json.Linq;
namespace App2
{
internal class mymobileservice1234Push
{
public async static void UploadChannel()
{
var channel = await Windows.Networking.PushNotifications.PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
try
{
await App.mymobileservice1234Client.GetPush().RegisterNativeAsync(channel.Uri);
await App.mymobileservice1234Client.InvokeApiAsync("notifyAllUsers");
}
catch (Exception exception)
{
HandleRegisterException(exception);
}
}
private static void HandleRegisterException(Exception exception)
{
}
}
}
Imports Microsoft.WindowsAzure.MobileServices
Imports Newtonsoft.Json.Linq
Friend Class mymobileservice1234Push
Public Shared Async Sub UploadChannel()
Dim channel = Await Windows.Networking.PushNotifications.PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync()
Try
Await App.mymobileservice1234Client.GetPush().RegisterNativeAsync(channel.Uri)
Await App.mymobileservice1234Client.GetPush().RegisterNativeAsync(channel.Uri, New String() {"tag1", "tag2"})
Await App.mymobileservice1234Client.InvokeApiAsync("notifyAllUsers")
Catch exception As Exception
HandleRegisterException(exception)
End Try
End Sub
Private Shared Sub HandleRegisterException(exception As Exception)
End Sub
End Class
#include "pch.h"
#include "services\mobile services\mymobileservice1234\mymobileservice1234Push.h"
using namespace AzureMobileHelper;
using namespace web;
using namespace concurrency;
using namespace Windows::Networking::PushNotifications;
void mymobileservice1234Push::UploadChannel()
{
create_task(PushNotificationChannelManager::CreatePushNotificationChannelForApplicationAsync()).
then([] (PushNotificationChannel^ newChannel)
{
return mymobileservice1234MobileService::GetClient().get_push().register_native(newChannel->Uri->Data());
}).then([]()
{
return mymobileservice1234MobileService::GetClient().invoke_api(L"notifyAllUsers");
}).then([](task<json::value> result)
{
try
{
result.wait();
}
catch(...)
{
HandleExceptionsComingFromTheServer();
}
});
}
void mymobileservice1234Push::HandleExceptionsComingFromTheServer()
{
}
(function () {
"use strict";
var app = WinJS.Application;
var activation = Windows.ApplicationModel.Activation;
app.addEventListener("activated", function (args) {
if (args.detail.kind == activation.ActivationKind.launch) {
Windows.Networking.PushNotifications.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync()
.then(function (channel) {
mymobileserviceclient1234Client.push.registerNative(channel.Uri, new Array("tag1", "tag2"))
return mymobileservice1234Client.push.registerNative(channel.uri);
})
.done(function (registration) {
return mymobileservice1234Client.invokeApi("notifyAllUsers");
}, function (error) {
// Error
});
}
});
})();
Push notification tags provide a way to restrict notifications to a subset of clients. You can use the for the registerNative method (or RegisterNativeAsync) method to either register for all push notifications without specifying tags, or you can register with tags by providing the second argument, an array of tags. If you register with one or more tags, you only receive notifications that match those tags.
Server-side scripts (JavaScript backend only)
For mobile services that use the JavaScript backend, the server-side scripts run when delete, insert, read, or update operations occur. The scripts don't implement these operations, but they run when a call from the client to the Windows Mobile REST API triggers these events. The scripts then pass control onto the operations themselves by calling request.execute or request.respond to issue a response to the calling context. See Azure Mobile Services REST API Reference.
A variety of functions are available in the server-side script. See Register table operations in Azure Mobile Services. For a reference to all available functions, see Mobile Services server script reference.
The following custom API code in Notifyallusers.js is also created:
exports.post = function(request, response) {
response.send(statusCodes.OK,{ message : 'Hello World!' })
// The following call is for illustration purpose only
// The call and function body should be moved to a script in your app
// where you want to send a notification
sendNotifications(request);
};
// The following code should be moved to appropriate script in your app where notification is sent
function sendNotifications(request) {
var payload = '<?xml version="1.0" encoding="utf-8"?><toast><visual><binding template="ToastText01">' +
'<text id="1">Sample Toast</text></binding></visual></toast>';
var push = request.service.push;
push.wns.send(null,
payload,
'wns/toast', {
success: function (pushResponse) {
console.log("Sent push:", pushResponse);
}
});
}
The sendNotifications function sends a single notification as a toast notification. You can also use other types of push notifications.
Tip For information about how to get help while editing scripts, see Enabling IntelliSense for server-side JavaScript.
Push notification types
Windows supports notifications that aren't push notifications. For general information about notifications, see Delivering scheduled, periodic, and push notifications.
Toast notifications are easy to use, and you can review an example in the Insert.js code on the channel's table that's generated for you. If you plan to use tile or badge notifications, you must create an XML template for the tile and badge, and you must specify the encoding of packaged information in the template. See Working with tiles, badges, and toast notifications.
Because Windows responds to push notifications, it can handle most of these notifications when the app isn't running. For example, a push notification could let a user know when a new mail message is available even when the local mail app isn't running. Windows handles a toast notification by displaying a message, such as the first line of a text message. Windows handles a tile or badge notification by updating an app's live tile to reflect the number of new mail messages. In this way, you can prompt users of your app to check it for new information. Your app can receive raw notifications when it's running, and you can use them to send data to your app. If your app isn't running, you can set up a background task to monitor push notifications.
You should use push notifications according to the guidelines for Windows Store apps, because those notifications use up a user's resources and can be distracting if overused. See Guidelines and checklist for push notifications.
If you're updating live tiles with push notifications, you should also follow the guidelines in Guidelines and checklist for tiles and badges.
Next steps
Using the WNS
You can call WNS directly if Mobile Services doesn't provide enough flexibility, if you want to write your server code in C# or Visual Basic, or if you already have a cloud service and you want to send push notifications from it. By calling WNS directly, you can send push notifications from your own cloud service, such as a worker role that monitors data from a database or another web service. Your cloud service must authenticate with WNS to send push notifications to your apps. See How to authenticate with the Windows Push Notification Service (JavaScript) or (C#/C++/VB).
You can also send push notifications by running a scheduled task in your mobile service. See Schedule recurring jobs in Mobile Services.
Warning Once you've run the push notification wizard once, don't run the wizard a second time to add registration code for another mobile service. Running the wizard more than once per project generates code that results in overlapping calls to the CreatePushNotificationChannelForApplicationAsync method, which leads to a runtime exception. If you want to register for push notifications for more than one mobile service, run the wizard once and then rewrite the registration code to ensure that calls to CreatePushNotificationChannelForApplicationAsync do not run at the same time. For example, you can accomplish this by moving the wizard-generated code in push.register.* (including the call to CreatePushNotificationChannelForApplicationAsync) outside of the OnLaunched event, but the specifics of this will depend on your app's architecture.
Related topics
Connecting to Windows Azure Mobile Services (JavaScript)
Connecting to Windows Azure Mobile Services (C#/C++/VB)
Quickstart: Adding push notifications for a mobile service (JavaScript)