Windows 8 app developer blog

Create location aware apps using geolocation and Bing Maps

Windows 8 Team — Wed, 22 May 2013 15:00:00 GMT

By tying together a user’s location to the business logic of your app, you can easily provide app users with weather, coupons, sporting events, or concert listings for their current location. You can use the geolocation capabilities of Windows 8, along with the Bing Maps SDK, to create great location aware Windows Store apps.

Let’s take a look at how your app can use the location service to provide users location-specific info with either an IP address, WiFi network, or GPS data. Once you have the location, you can use the Bing Maps SDK to show the user where they are.

Retrieving Location

The Windows.Devices.Geolocation namespace is used for retrieving your location. Whether you use GPS, a WiFi network, or an IP address to retrieve a user’s location depends on two primary factors:

The accuracy level requested. This is the ideal level of accuracy to meet your app’s needs.
The availability of location data. Meaning, not all devices have GPS built in. Or a network or Wi-Fi connection may not be available when the location is requested.

Desired accuracy

When requesting a location, your app should specify your desired accuracy so the location data can be returned as quickly as possible within the given range. Each of the location types have degrees of accuracy:

GPS – GPS provides the most accuracy, down to approximately 10 meters. However, if the GPS sensor needs to ‘wake up’ and acquire satellite data and then triangulate the data, it can take a minute or two to return the location details. But, once the GPS has acquired satellite connections, it can then acquire the next location point more quickly. Of course, the more the GPS is used, the more power it consumes. The Geolocator.DesiredAccuracy property must be set to High to enable to GPS to acquire data.
Wi-Fi – A Wi-Fi connection can provide accuracy between 300-500 meters. If the connection exists, the location data can be returned faster than a GPS can acquire satellite connections. Set the DesiredAccuracy property to Default in order to acquire the location with Wi-Fi.
IP – IP level resolution can bring accuracy down to about the 1 kilometer level. If the network connection exists, the location data can be returned faster than a GPS can acquire a satellite connection. You also set the DesiredAccuracy property to Default to acquire the location with IP. The location service returns the highest accuracy it can and lets you know how accurate it is in the Geocoordinate.Accuracy property.

Consider your desired accuracy value carefully. It can affect your app’s performance and power consumption. For example, if your app is providing a weather forecast, you rarely need the high accuracy of GPS. Also be sure to indicate the accuracy of your data by displaying an error radius based on the accuracy of the data returned. Here is the C# code to set your desired accuracy:

Geolocator geolocator = new Geolocator();
geolocator.DesiredAccuracy = Windows.Devices.Geolocation.PositionAccuracy.High;

No matter what accuracy you want, the call to get your location is:

Geoposition pos = await geolocator.GetGeopositionAsync().AsTask(token);

Here’s the JavaScript code that creates an instance of the Geolocator class, sets the desired accuracy, and then gets the current location. Note that the ‘promise’ variable below is a WinJS.Promise object – you’ll need to use the done method to access the data from the call to getGeopositionAsync.

JavaScript

var geolocator = Windows.Devices.Geolocation.Geolocator();
geolocator.desiredAccuracy =
Windows.Devices.Geolocation.PositionAccuracy.high;

// Get the geoposition, capturing the request in a 'promise' object.
var promise = geolocator.getGeopositionAsync();

Remember that if you set your desired accuracy to High, you can’t be assured that the user’s device will be able to return high accuracy. Their PC may not have a GPS or it may be turned off or they may not be connected to Wi-Fi, etc. Always be prepared to gracefully handle these instances of lower accuracy data. How you do this depends on the functionality of your app. Can you continue with lower accuracy? Can you require GPS level accuracy? See the Guidelines for location-aware apps for more info.

Bing Maps

The Bing Maps app is a good example of an app that adapts to the accuracy of the location data available to it. On a desktop PC, which typically doesn’t have GPS or Wi-Fi, it finds the location based on the IP address and zooms in to a region level when mapping the current location. On a laptop, which typically has a wireless card, it uses the Wi-Fi to get a more precise location and zoom in further when showing current location. If the user zooms in even further, the current location icon will show an error radius. On a device with GPS, Bing Maps gets the high accuracy location data from the GPS and displays a more accurate location.

Bing Weather

As mentioned above, an app like the Bing Weather app only needs region information. Because of this, it can specify that it only needs low accuracy allowing it to quickly get a location value back. This makes the app more responsive to the user. Other examples of apps that may need only region level information include radio station guides, shopping deals, or local news feeds.

Displaying location data with the Bing Maps SDK

After you have the location information from your call to GetGeopositionAsync, you’ll want to display it on a map.

First, convert the Geoposition into a Location that can be used with Bing Maps, use the following code:

Location location = new Location(pos.Coordinate.Latitude, pos.Coordinate.Longitude);

JavaScript:

promise.done(
  function (pos) {
    // Get the coordinates of the current location.
    var coord = pos.coordinate,
    location = new Microsoft.Maps.Location(coord.latitude, coord.longitude);
 
  },
  function (err) {
    // Handle the error.
  });

Next, display your location using Bing Maps. You can get the Bing Maps SDK here. You’ll also need to get a Bing Maps Key by registering on the Bing Maps Portal and following the instructions for Getting a Bing Maps Key. When you register make sure you look at the usage restrictions for each type of key and choose one that is appropriate for your app.
Add a Bing Maps control to your designer and insert your key into the credentials.

<Page
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SimpleMapping"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:Maps="using:Bing.Maps"
    x:Class="SimpleMapping.MainPage"
    mc:Ignorable="d">

    <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
        <Maps:Map x:Name="Map" Margin="0,120,0,0" Credentials="Insert Your Bing Maps Key Here"/>
    </Grid>
</Page>

Now you can use the following code to the page in your app where the map is displayed. This sets the zoom level of the map and shows the location. Learn more about zoom level in How to display your location on a Bing Map:

double zoomLevel = 13.0f;

Map.SetView(location, zoomLevel);

Adding a Bing Maps control to your app in JavaScript and HTML requires a little more work. Add the following <script> tag to the HTML of your app:

<script type="text/javascript" 
   src="ms-appx:///Bing.Maps.JavaScript//js/veapicore.js">
/script>

Then, you’ll need to create a <div> tag to contain the map, setting the id attribute so that you can access it.

<div id=’map-div’></div>

Last, you’ll need to initialize the map control in the HTML page. Here’s some JavaScript code that does so:

// Load the Microsoft.Maps.Map module and then call getMap when the 
// module has loaded.
function initMap() {
  Microsoft.Maps.loadModule('Microsoft.Maps.Map', 
    { 
      callback: getMap, 
      culture: "en", 
      homeRegion: "US" 
  });
}

// Get the div to contain the map from the interface of the app.
function getMap() {

  // Create a new instance of the Map class, passing in the app ID.
  var map = new Microsoft.Maps.Map(
    document.getElementById(mapDivId), 
    { credentials: “Insert your credentials here” });

  // Set the initial zoom level and type of map.
  map.setView({
    mapTypeId: Microsoft.Maps.MapTypeId.road,
    zoom: 3
  });
}

Finally, any app that uses location must respect the user’s permissions settings, which can change at any time. The Weather app uses location to get the weather for the current location. But at any time, the user may go into the Settings and turn the Locations permissions off. Your app always has to handle the possibility that the Location permission has been disabled. In this case, the Weather app displays a “Your location cannot be found. Change your Permissions to allow Weather to user your location.” message. See the User experience guidelines in Guidelines for location-aware apps for examples of handling location permissions.

For full details on using geolocation and the Bing Maps SDK, we have a new video, how-to topic , and code sample that leads you through the steps of asynchronously acquiring your location and then using the Bing Maps SDK to show where you are in a visual manner. The video, how-to topic, and sample guide you through enabling the location capability, getting the location asynchronously, setting the map to a given location, and setting the location icon based on the accuracy of the location data. You can also find more info in Bing Maps for Windows Store Apps.

Wrapping up

Location can be a powerful and time saving feature to add to your app. You can provide the user with more pertinent information based on where they are. Whether it’s a list of local radio stations, shopping deals, traffic information, or weather information, the control to tailor that information based on location can make your app more useful. And the ability to make that happen automatically, without user interaction, saves the user time and makes them more likely to use your app.

--Ross Heise, Senior Content Developer, Windows Developer Content

Special thanks to Jon Kay and Eric Schmidt for their help and contributions to this post.

Introducing a new Windows Dev Center experience

Windows 8 Team — Wed, 15 May 2013 20:15:00 GMT

Since launching the Windows Dev Center in October, 2011, we’ve worked closely with developers and designers around the world to understand how we can provide the best guidance, inspiration, and samples for app builders. With millions of visitors and your feedback, we’ve been evaluating what’s been working well and what experiences can be improved.

What’s new

The Windows team is focused on growing a vibrant and thriving app ecosystem. This is manifested in three ways: great apps, great economics, and great reach opportunity. The new Dev Center connects app builders, designers and businesses with the resources they need to succeed in developing great apps and building a business with Windows.

To support those goals, the Dev Center evolved in these areas:

The navigation model has changed so you can find the content relevant to where you are in the app development lifecycle
The site design highlights top tasks, scenarios, and new content

In addition to the content, samples, and downloads that developers want; we’ve made it easier to access resources for designers and businesses.

Depending on what you’re building, you can navigate to one of four areas: Windows Store apps, Internet Explorer, Windows desktop, and Hardware. Each of these presents a new experience that addresses the points mentioned above. In this post, we’ll take a closer look at the specific changes made for Windows Store apps.

The right content for your role

The most informative website isn’t useful if you can’t find what you’re looking for. With hundreds of thousands of topics in the Dev Center, organization and discoverability of content is critical. For Windows Store app development, that means a tighter focus based on role and scenario – from putting everything you need to get started in one place, to better support for designers and businesses. Here are some of the highlights.

Developers

We’ve streamlined the content you need to build great Windows Store apps. When you go to the Windows Store apps home page, you’ll see:

“Key tasks and content” prominently called out to help you jump into the content you need. Local events in your region are highlighted, as well as new resources just added to the site.
Downloads to help you dive right into coding, all the resources you need to get started, and our detailed guidance on getting your app into the Windows Store.
Important code samples are highlighted, and how-to guidance is more easily navigated with an eye toward the development lifecycle.
“One Dev Minute” videos throughout the site, which give you a quick look at how to add features to your app.

Designers

We’ve overhauled the Design section of the site to make it both easier to use and more comprehensive. You can find useful downloads and reusable design assets more easily, and design inspiration and case studies give you the tools you need to make a unique experience on Windows. Everything you need to build a beautiful app that stands out from the crowd is right at your fingertips, with a page design that’s touch-friendly and easy-to-use.

Businesses

The business opportunity of the Windows Store is significant, with a better economic model than competitive platforms and flexibility that enables you to build the business you want. The new Market section of the site provides great tips for marketing your apps, evaluating telemetry data, and passing app certification. We’ve learned a lot about how to make certification easier and have improved the content to help you breeze through the process.

Of course, many of you fill multiple roles, and we think the new site organization supports that as well. From hobbyists to creative agencies to the largest enterprise software developers, the new site organization will help you achieve your creative and business vision with Windows.

There’s more to come, and we want your input

With BUILD 2013 a little more than a month away, there’s plenty to talk about. We’re working hard to produce new content to expand on what will be shared at this year’s event. In addition to keeping up with this blog, other ways to stay connected include following @windevs on Twitter and subscribing to the Windows Store newsletter.

As we roll out more content to help you design, develop, and market your Windows Store apps, we want to keep improving your Dev Center experience! To make it easier for you to tell us what you think, we’ve provided two new feedback options at the bottom of every page. Please provide feedback– we’re listening and are always working to address your concerns.

Keith Boyd, Content Publishing Manager, Windows Developer Content

Sharing to your target app

Windows 8 Team — Wed, 08 May 2013 15:00:00 GMT

In Sharing from your app, we introduced the idea of sharing content from the example app Food with Friends to several target apps that let the user accomplish rich end-to-end scenarios. Apps in Windows 8 offer interesting content that your customers will want to share with friends or other apps. With a compelling and well-designed share target, your app can be at the heart of a social and connected experience for your customers.

In this post we look at how you can use the Share target contract for your apps, especially those like Food with Friends. Using this contract, your app can receive content from other apps and use that content to improve its quality. We want to help you make your app the best in its category!

A target app is built using the Share target contract and is designed for a quick and easy sharing experience. Not every app in Windows will be a share target, but if your app can publish, transform, store or somehow add value to content it receives from another app, there are benefits to creating a Share target.

Your app will always show up in the target app list. It’s instantly relevant and connected to other apps that can share data you want.
The share contract creates a bridge between your app and any source app without either app requiring one-to-one integration.
Because the Share charm is always present and available in the OS, it gives your target app a presence in the OS that extends beyond the boundaries of your app. This can potentially point more customers to your app!

Receiving shared content

Let’s take a look at few examples that show how you can deliver compelling experiences through a Share target app.

You might already be familiar with the Mail and People apps on Windows 8. Mail creates an easy and personal share target experience for receiving and sharing content with one or more friends. The People app lets you share content with broader audiences on your social networks. In addition to social sharing, you can go a step further with in app-to-app sharing. Productivity apps like SkyDrive can receive files from anywhere in Windows and store these on the cloud; note-taking apps can receive text, links and possibly data in a wide variety of other formats and archive it for reference later. There’s also plenty of room to get creative.

Look at how the two pictures below show the share flow when sharing a photo from the Photos app to PuzzleTouch, a game app that turns the picture into a visual puzzle.

Figure 1: Source app on the left; list of filtered target apps that can receive photos in the Share pane on the right.
PuzzleTouch is one of the Share targets that can receive a picture from the Photos app.

Figure 2: On the right, the target app preview lets the user select what type of puzzle they
want to build. The puzzle is ready when the user switches back to the app.

What is a share target app?

An end-to-end sharing experience in Windows has two components. You have a source app that makes its content available in different formats to Windows. You also have a share target app that registers to recognize certain formats and act as the destination for the content being shared. Using the Share contract, the source app and the share target app communicate with each other.

When you think about the share experience for your app, consider that the share target app is rendered in the hosted Share window. Make sure you design the experience so your user can quickly preview their content and confirm sharing in this view. This example shows the Mail share target app view that allows a user to quickly share a link from the browser with one of his or her mail contacts.

Figure 3: Sharing a link from the Photos app using the Mail target app

Scenarios for Food with Friends

Now, let’s consider how Food with Friends creates a compelling Share target app experience. If you’re familiar with the app, you’ll see two main actions that a user can take in Food with Friends – creating a plan and adding a restaurant to their Wishlist. Of course, there are other actions such as writing a review, posting a comment, viewing your friends’ wish lists, and so on, but those experiences make sense within the context of the main app. For the two core scenarios that stand out, let’s do a quick sanity-check to see if these can be effectively completed via the Food with Friends target app.

Create Tonight’s plan

While a core scenario of the main app, this isn’t the best scenario for a Share target experience. Here’s why: The Share target experience is meant to be quick and easy. Creating a plan is a much more involved task – a user would want to know what other restaurants her friends want to try out, compare a few restaurants from their Wishlist, review ratings and so on. Because planning involves leveraging details that are best presented in the main app view, condensing that functionality into the Share target app is not compelling.

Add to Wishlist

This scenario works really well as a short and directed task in the Share target. Some highlights in this app experience:

People come across restaurants in other apps, whether these are trip planning apps, local city apps with recommendations, food blogs, and so on. Food with Friends is a great destination for aggregating restaurants in the ‘My Wishlist’ section.
The target app view of an app is designed for a user to quickly take action while in the context of a different app. Thus, adding a restaurant to a Wishlist is an excellent option to surface in the Share target.
While it’s certainly possible for the user to switch apps, repeat the search to find the restaurant, and then add the restaurant to their Wishlist, it’s a much easier experience to quick tap on Share.

The Food with Friends Wishlist seems to be a great share target app experience that we want to design and build. Here’s the end-to-end scenario we have in mind:

While browsing an app that shows me local food trucks, I find a food truck recommendation that sounds interesting. I want to add the food truck from this app to My Wishlist in Food with Friends to help with planning later.

Figure 4: Browsing an app that shows local food trucks and recommends places of interest

This image shows the share target app view that we want to use:

Figure 5: The share target app view

By completing the share action in the target app view, users can curate restaurants in Food with Friends, without switching context from their current immersive app experience.

Implementing a share target

Now that you’ve seen some examples of when to implement a share target, let’s look at how you implement a share target. First, decide which data formats your app can receive.

Which data formats should you support?

With Share you can support either standard data formats such as text, URI, HTML, bitmaps, files or custom data formats such as the ones listed on http://schema.org . Windows filters target apps by the data formats they support to display the filtered target app list in the Share pane. Your app should support data formats that are important to the app experience. For example, if your app is about viewing photos, supporting text formats might not be helpful. If you declare support for multiple data formats, decide which one helps you represent the shared data best so you can pick that format from the data package first.

Since Food with Friends is implementing a share target experience that lets users share restaurants to the app, we’ll use the Restaurant data format listed on http://schema.org. Food with Friends can register with the Share target contract to receive this data format. Then, using the data in the received package, it can build a compelling experience in its target app view that allows the user to add that restaurant to their Wishlist.

While some source apps may specifically share out the Restaurant data format, other source apps may represent similar information using other data formats like Place, LocalBusiness and FoodEstablishment listed on schema.org. Thus, Food with Friends can support receiving multiple formats in the share contract to cater to a wider variety of source apps.

Food with Friends supports the following formats in the Share target declarations of the app manifest:

We’re focusing on the Restaurant data type for the sake of brevity, but the concepts apply to other data types as well.

Which data formats and scenarios should you scope out?

Food with Friends will only support adding the restaurant to the user’s Wishlist if the restaurant information received matches that of a restaurant that the app is already aware of. This is intentional to avoid multiple copies of restaurants in the app.

We’re not supporting standard data types because most text, files, photos, URI or HTML shared from source apps won’t be mapped to a restaurant or local business. For example, if Food with Friends supported receiving text, it would show up in the target app list for a notetaking source app. In this case, Food With Friends would need to provide an error message telling the user why this app doesn’t work with their source app. Bottom line, the data formats are what connect a source app that has something to offer a target app. If the data formats aren’t the same, there’s nothing worthwhile to share.

Make sure you consider all data formats that help identify what you care about, scope out the data formats that dilute your share experience.

Supporting the Share target contract

To support data formats, declare them in the Visual Studio manifest designer for your app. This is what happens when a user selects your app as the target of a share action:

A new instance of the app is launched in the share target window over the source app.
A share target activation event is fired and your app receives a ShareOperation object as a result.
Your app can retrieve the data that the user shared from this object.
You can use this data to render the target app view and complete the user’s share.

For more info about how to create this experience, see the Receiving shared content Quickstart guide.

Additionally, Visual Studio supports a template for share targets. Right-click your project, select Add Item, Add New Item, click Share Target Contract from the list and you get code added for supporting the contract. The Share target code sample shows how to receive shared content.

Designing a tailored target app view

When the user selects a target app from the list of apps in the Share pane, Windows launches the app in the app’s share target view. The target app view is a special view hosted in the Share pane and is different from the app’s main view. Activating Windows 8 contracts in your app gives more info about hosted views and handling activation for these views. The target app view is designed to help complete the share action initiated by the user. In this view, users should be able to preview their content at a glance, take simple actions, and confirm their intent to share.

Before we look at the target app design for Food with Friends, let’s consider a target app that you might already know. The images below show the target app view for the Mail app alongside the full view of the app in Windows 8.

Figure 6: Sharing from Photos to the Mail target app on the right

Figure 7: Composing a new mail in the main app view of Mail

Notice that Mail’s share target app view is simpler than its full app view. It provides a clean and minimal preview of the content the user is about to share in the form of a thumbnail and associated text and HTML. It provides a To line for adding recipients, an input area for composing a quick message and an easy to way to confirm sending the mail through the Send button.

Despite this simpler view, the app’s target app view is clearly identifiable as an avatar of the Mail app, which reinforces user confidence about the destination of the shared content.

Food with Friends as a share target app

Now that you have a general idea about design for the target app view, let’s discuss how Food with Friends can create a target app helps users add restaurants to the ‘My Wishlist.’

When Food with Friends receives the data package containing a Restaurant from the source app, it can use the details in the Restaurant data format to identify which restaurant from its existing database matches the received data package. The app can then show a preview of this restaurant in the target app view. This reinforces confidence in the integrity of the content being shared.

This image shows the target app view for Food with Friends –

Figure 8: The target app view for Food with Friends

As you can see this view of Food with Friends is simple and tailored for a share target app - It shows a preview of the restaurant that the user is about to share and a simple actionable button, Add to Wishlist that clarifies the destination of the shared content in the main app. When the user taps or clicks this button, it confirms the share operation. By requiring a tap or click here, we help prevent accidental sharing and build confidence in the overall Share experience.

If the app finds multiple restaurants that match the info of the data package content, Food with Friends uses the share target app view to show the options and let the user pick which ones to share.

Figure 9: Target app view shows options so users can pick which items to share

In case the app cannot accurately identify a restaurant or a valid set of options based on the received data package, use the target app view to communicate that message.

Creating a QuickLink

A QuickLink is a provision of the Share API that lets users share content to familiar destinations within your target app quickly. A QuickLink acts as a customized link to your target view, providing specific actions. When Windows filters the list of target apps available to the user, the list of QuickLinks is featured at the top of the Share pane as the list of available targets. These familiar destinations or user actions may include places or people that are shared with often through the target app. For example, the Mail app returns QuickLinks for previously mailed contacts. Similarly, you can add QuickLinks to folders, groups, notebooks, and playlists that you share often to your target app.

Figure 10: Share pane shows a QuickLink provided by the Mail target app for contacts
that have been previously mailed using the target app

The target app can provide a QuickLink by calling ShareOperation objects’ reportCompleted method. A QuickLink must have a title, an icon, and an ID. The title (like "Email Mom") and icon appear when the user taps the Share charm. The ID is what your app uses to access any custom information, such as an email address, a folder location and so on. See How to Create a QuickLink to learn more about this tool.

Note: QuickLinks are useful when the app supports multiple actions from the target app. Because Food with Friends only supports a single action in the Share target i.e. Add to Wishlist, the app doesn’t implement QuickLinks.

Extended share and error reporting

Sometimes source apps share large chunks of data like photos, videos, or files resulting in longer data transfer times. These types of share operations are known as extended shares where your target app might need more time to receive and process the data.

Because sharing is to be fast and fluid and the target app view is a lightweight, hosted view over the main app, users might tap away from the target app view to get back to their main app. Thus, target apps shouldn’t rely on or expect user interaction with the target app view after sharing has begun. Target apps can rely on using the ShareOperation object and its methods to let Windows know that the app is processing data.

reportStarted – call this method to let Windows know your app has started retrieving the data in the DataPackage object from the source app.
reportDataRetrieved – call this method to let Windows know your app has finished retrieving the data in the package.
reportCompleted – call this method to let Windows know your app has completed the Share operation.

When your app is processing data for an extended share, give the user a progress UI in the target app view. This informs the user that their request is underway and reinforces confidence when they return to your app and check on the progress of the share operation. Check out Quickstart: adding progress controls to learn more about progress controls in Windows 8.

Figure 11: Mail target app view shows a progress ring when completing an extended share such as sending over large attachments

If something goes wrong during the data transfer and your target app has to end the share operation, you can call reportError to send an error message to Windows. The user will see the message when they check status of the share in the Share pane. After you report the error, your app is shut down and the share is ended. The user will need to start again to share the content to your app.

In the Food with Friends share target example, if the app cannot identify a restaurant in its database that matches the restaurant that was shared from the source app via the Restaurant data format, the app should report an error.

Let’s review!

App-to-app sharing provides a great opportunity to share target apps. By enabling your app to receive shared content, your users get value from your app even when they are involved in another activity. We hope you have a better understanding of the design principles as well data types, classes and properties that you can use to create a great share target destination. We’re excited to discover how your apps will transform shared content and create broader and richer end-user experiences.

If you want to learn more about sharing, read Sharing and Exchanging Data and the Share content target app sample to get started!

Ishita Kapur

Program Manager

Windows User Experience

Develop a cutting edge app with NFC

Windows 8 Team — Thu, 18 Apr 2013 22:25:54 GMT

Near Field Communication (NFC) is an emerging, short range wireless technology. With a precise range of 2 cm, people can physically tap devices together to send/receive content. Tapping lets you select something (or someone) quickly. Not only is it quick, it’s also easy to understand. Once you see it, you get it; there’s no manual needed.

For example, imagine you are looking at some photos with a friend and she wants your pictures; with NFC, you can simply tap your device against her PC to send the photos. Over simplifying? Maybe, but the main idea is that it’s simple to share content between devices.

Figure 1: This image shows the Nokia 360 speaker sharing its Bluetooth
pairing information with a Windows Phone

Similar to Bluetooth or Wi-Fi, NFC is a standard wireless protocol defined by the NFC Forum. Your PC needs an NFC radio. There are lots of Windows 8 PCs that have NFC radios integrated directly into them. If NFC isn’t already part of your PC, you can buy NFC dongles to plug into your PC.

NFC offers some cool capabilities. People can tap and send photos, tap a menu and order a meal at a restaurant, or even tap to pair a Bluetooth device. These scenarios are pretty different from each other, but the thing they have in common is the 'tap' to initiate the experience. NFC is used in variety of devices, such as PCs, phones, speakers, headsets, wireless displays, etc..., to make connecting devices together a really intuitive experience. Also, NFC uses RFID tags; these are really cheap, lightweight passive antennas that can hold a sizable amount of data and can be stuck on virtually anything, most commonly posters. For example, buying a movie ticket could be as simple as tapping the movie poster! These are called NFC tags. We'll walk through a basic example of tapping an NFC tag to demonstrate some key concepts of the NFC API.

But first, let’s take a closer look at what it means to tap devices together.

Defining a ‘Tap’

Whether you’re tapping to pair a Bluetooth mouse or tapping to share photos, it’s important for users to tap devices together the same way. And while tapping is a well understood concept, tapping your PC against another device is new to most people. Here are some guidelines for tapping that let users know:

Where to tap devices together – by using a touchmark, also known as the ‘Tap and Do’ visual mark, indicating where the NFC antenna is located. Depending on the PC model, you tap different parts of the PC. For example, you may tap on the back on a tablet but on the front an all-in-one. Here’s what the mark looks like on any NFC enabled, Windows 8 PC:

Figure 2: Tap and Do visual mark
Devices are communicating with each other - During the tap, users should have confidence that something is going on; even if they can’t see the data being transferred. Therefore, Windows plays a sound when devices are in-range and communicating with each other.

Windows does these things automatically, so you won’t need to worry about them. For more info on these user experience elements, see the Windows 8 Near Field Proximity Implementation Specification. With that in mind, let's check out some of the cool scenarios you can experience with NFC.

When to use NFC

Use NFC when a user needs to select something, or someone, in your app. NFC gives you an intuitive way to select; and it’s often faster (and cooler!) than manually searching. The tap is a trigger to initiate an experience; and depending on your app, the experience can range from receiving a photo to starting a playlist. It’s really up to your app to decide what happens after the tap. So, to keep it simple, we classify this range of experiences as ‘Tap and Do’ experiences.

Below are a few examples of using NFC to select something in an app. You could Tap and…

Get information from a poster: NFC tags are light, cheap RFID tags; they cost between $0.15 - $1.00 (price varies on printing cost). These are comparable to QR codes, but are easier and faster to use. Tapping a tag feels more comfortable than taking a picture of the bar code (and hoping the camera got the right angle). Manufacturers are increasingly embedding tags into posters in high traffic areas like airports, metro stations, and bus stops. They can hold between 48 B – 4 KB of data. You can program a tag to launch your app to a specific page.

Exchange contact information: instead of spelling out your contact information to a friend, and hoping he didn’t misspell anything, tap devices together to exchange contact information. Similar to above, you can program your information to an NFC-business card/tag; or you could directly exchange information via an app.
Play your favorite music station: whether you’re about to go work out, hopping into your car or just lounging at home – use an NFC tag to start a radio station. You can even have different music stations programmed on different tags; for example, one tag for the gym, one for lounging, and one for sleep.
Order dinner at a busy restaurant: a popular restaurant at dinner time means you might be waiting a long time just to place an order. Instead, tap a tag at your table to order your food.
Play a multiplayer game with a friend: you can easily connect a multiplayer game like Battleship, Chess, or Scrabble with a friend by tapping devices together. After the tap, the connection persists over an out-of-band transport with a bigger range and higher throughput, such as Bluetooth or Wi-Fi Direct.

By now, we’ve got a pretty good idea of when to use NFC; now for fun stuff – building an app that uses our Windows 8 Proximity (NFC) APIs.

How to implement NFC

As you can see NFC makes lots of everyday tasks easier for end-users. Take setting an alarm for example. I’m sure just about everyone has had a few experiences where they mistakenly set their alarm for the wrong time in the morning. When its late and you just want to get to sleep, you’re not always thinking at your best. NFC makes this easier by letting you just tap a preset tag, confirm, and then go to sleep worry free. So to help users with this everyday task let’s imagine you wrote a basic alarm app that let users set an alarm using an NFC tag. This breaks into two scenarios

Setting an alarm on the tag: NFC tags can be reusable, so the app should have a way for users to program an alarm. For example, a user may want to program different alarms – one for the week, another for the weekend. This is known as publishing data to a tag.
Setting an alarm from the tag: After a user taps a tag, the app should launch to confirm setting an alarm. This means the app can be launched with context, or arguments.

The NFC API allows for several ways to achieve the same thing, but I’ll go over the simplest way to implement this scenario.

Let’s walk through a flow to set an alarm on an NFC tag:

Mario launches the alarm app and sets a time, say 7.00 AM. Normal alarm stuff, nothing with NFC yet.
Mario selects an option to ‘Set alarm on an NFC tag’. At this time, the app calls the NFC APIs to publish information to the NFC radio, specifically an app identifier string & 07:00. NFC tags use a standardized message format called NDEF, NFC Defined Exchange Format. Your app does not need to worry about formatting data into an NDEF message; Windows does this for you! Now, the user can tap the NFC tag.
Mario taps the tag against the PC and the app confirms programming the tag. After the tag is tapped, it’s important to let users know that your app successfully programmed the tag. As we discussed earlier – tapping your PC is a new concept for most people, so the confirmation gives users confidence that what they just did worked. The app knows a message was successfully transmitted by registering for a message transmitted handler.

The NFC APIs are located in the Windows.Networking.Proximity namespace. They come into play at step 2 – after the user selects the option to ‘Set alarm on NFC tag.’ First, the app initializes a proximity object. The proximity object is used to tell when a tag (or device) is in/out of range. Next, we’ll add the DeviceArrival event handler. The handler recognizes when the tag has been tapped, which means we can start writing information to the tag. It’s useful to let users know when you’re writing to a tag, so they don’t move it out of range. You can use the same event to recognize when any proximity device has been tapped.

The next code snippet shows how to initialize and add a DeviceArrival event handler.

JavaScript

var proximityDevice;

function initializeProximityDevice() {
    proximityDevice = Windows.Networking.Proximity.ProximityDevice.getDefault();

    if (proximityDevice) {
        proximityDevice.addEventListener("devicearrived", proximityDeviceArrived);
       
}
   else {
        // No NFC radio on the PC, display an error message
    }


function proximityDeviceArrived(device) {
        // Let the user know we’re ‘Writing to Tag’

}
}

private void InitializeProximityDevice()
{

Windows.Networking.Proximity.ProximityDevice proximityDevice;
    proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault();

    if (proximityDevice != null) {
        proximityDevice.DeviceArrived += ProximityDeviceArrived;
    
    }
    else
    {
        // No NFC radio on the PC, display an error message
    }
}

private void ProximityDeviceArrived(Windows.Networking.Proximity.ProximityDevice device)
{
            // Let the user know we’re ‘Writing to Tag’

}

Next, we publish information to the tag. The app publishes two things: an app identifier string, which consists of an app ID and app platform, and launch arguments. For Windows 8, the app Id is <package family name>!<app Id> and the app platform is ‘Windows.’ You must copy the app ID value from the ID attribute of the Application element in the package manifest for your app. The launch argument is ’07:00’ – the alarm set by the user. Let’s call this the message.

If the app works across platforms, Windows lets you publish alternate app ID(s) and app platform(s); which means you can tap the same tag on a different device which support NFC, like Windows Phone 8! You can find more information about Alternate IDs on MSDN.

The app publishes the data to the tag using a method called publishBinaryMessage. The method takes three parameters – messageType, message, and a messageTransmittedHandler function. We’ll set messageType to ‘LaunchApp:WriteTag’, which lets Windows know that your app wants to write information to an NFC tag. The message is just the message we defined earlier (app identified string and launch arguments); we’ll need to store the message as a binary message in a buffer. The messageTransmittedHandler function registers for callbacks. This lets your app know that the message has successfully been written to the tag. We’ll use this to tell the user two things: we’ve successfully written a message to the tag and the tag no longer needs to be in range.

Messages continue to be published until we call the StopPublishingMessage function or the ProximityDevice object is released. In this example, we’ll use the stop function. PublishBinaryMessage returns a publication ID; we’ll use this same publication ID to stop publishing the message onto the NFC Radio.

The next code snippet shows how to write data to an NFC tag:

JavaScript

var proximityDevice;

function getAlarmTime(){

    // Grab time set by the user, call this variable ‘Alarm’
    return Alarm;

}

function publishLaunchApp() {
    proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault();

if (proximityDevice) {
        // The format of the app launch string is: "<args>\tWindows\t<AppName>".
        // The string is tab or null delimited.

        // The <args> string can be an empty string ("").
        var launchArgs = getAlarmTime();

        // The format of the AppName is: PackageFamilyName!PRAID.
        var praid = "AlarmApp"; // The Application Id value from your package.appxmanifest.

        var appName = Windows.ApplicationModel.Package.current.id.familyName + "!" + praid;

        var launchAppMessage = launchArgs + "\tWindows\t" + appName;

        var dataWriter = new Windows.Storage.Streams.DataWriter();
        dataWriter.unicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.utf16LE;
        dataWriter.writeString(launchAppMessage);
        var launchAppPubId =
             proximityDevice.publishBinaryMessage(
                 "LaunchApp:WriteTag", 
                 dataWriter.detachBuffer(), 
                 proximityWriteTagLaunchAppMessageTransmitCallback);
        
    if (launchAppPubId != -1) {
            // Stop publishing the message on NFC radio
        proximityDevice.stopPublishingMessage(launchAppPubId);
    }

     }
}

function proximityWriteTagLaunchAppMessageTransmitCallback() {
    // Inform the user that: the message has been successfully written to a tag & the tag no longer needs to be in range
}

Windows.Networking.Proximity.ProximityDevice proximityDevice;

private string GetAlarmTime(){

    // Grab time set by the user, call this variable ‘Alarm’
    return Alarm;
}

private void PublishLaunchApp()
{
    proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault();

if (proximityDevice != null)
    {
        // The format of the app launch string is: "<args>\tWindows\t<AppName>".
        // The string is tab or null delimited.

        // The <args> string can be an empty string ("").
        string launchArgs = getAlarmTime();

        // The format of the AppName is: PackageFamilyName!PRAID.
        string praid = "MyAppId"; // The Application Id value from your package.appxmanifest.

        string appName = Windows.ApplicationModel.Package.Current.Id.FamilyName + "!" + praid;

        string launchAppMessage = launchArgs + "\tWindows\t" + appName;

        var dataWriter = new Windows.Storage.Streams.DataWriter();
        dataWriter.UnicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.Utf16LE;
        dataWriter.WriteString(launchAppMessage);
        var launchAppPubId =
        proximityDevice.PublishBinaryMessage(
            "LaunchApp:WriteTag", dataWriter.DetachBuffer(), 
            proximityWriteTagLaunchAppMessageTransmitCallback);
    
    if (launchAppPubId!= -1)
    {
        proximityDevice.StopPublishingMessage(launchAppPubId);
    // Stop publishing the message on NFC radio
    }

    }
}

private void proximityWriteTagLaunchAppMessageTransmitCallback(
    Windows.Networking.Proximity.ProximityDevice sender,
    long messageId)
{
        // Inform the user that: the message has been successfully written to a tag & the tag no longer needs to be in range
}

That’s it! Now you know how to write to an NFC tag from a Windows Store app. Simple enough; so, let’s move onto the next scenario - setting an alarm from the tag. Let’s walk through a flow to read an alarm from an NFC tag:

Mario is reading his home screen/writing an email/playing a game/using Windows and he realizes he needs to set an alarm for Monday morning. He grabs his ‘Weekday alarm’ tag and taps it on his PC. He gets a toast inviting him to launch your Alarm app. Windows takes care of everything up until this point; your app doesn’t do a thing.
Mario accepts and your app launches to a ‘Confirm Alarm?’ screen with a time of 7:00 AM. After Mario accepts the toast, Windows passes the launch arguments (same as above) to your app during activation. This is called contextual launching, which is the same thing as launching your app to specific page.
Mario sets the alarm. Normal alarm stuff, no NFC.

It’s easy enough to get the launch arguments from the NFC tag. The app needs to handle contextual launching from an NFC tag. Contextual launching is the synonymous with launching your app to a specific page. Our launch arguments specify an alarm, 7.00 AM, which your app uses to display a proposed alarm. Also, in case your app isn’t installed on the PC, Windows invites Mario to install your app from the Windows store – automatically!

The following code snippet shows how to implement contextual launching.

JavaScript

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.arguments == "Windows.Networking.Proximity.PeerFinder:StreamSocket") {
            //do nothing here.
        }
        else {
    // Use args.detail.arguments to parse out ’07.00’ string, and display to the user
        }

        args.setPromise(WinJS.UI.processAll());
    }
}

async protected override void OnLaunched(LaunchActivatedEventArgs args)
        {
            if (args.Arguments == "Windows.Networking.Proximity.PeerFinder:StreamSocket")
            {
                _isLaunchedByTap = true;
            }
            else
            {
// Use args.Arguments to parse out ’07.00’ string, and display to the user

            }
            Window.Current.Activate();
        }

That’s all your app has to do to support reading and writing to an NFC tag; pretty simple for a cutting edge scenario. Before I wrap up, let’s go over some good hygiene stuff – error handling.

Error Handling

There are a few common errors your app may run into.

The tapped tag is not NDEF formatted. Windows 8 doesn’t support automatically reformatting a tag to NDEF, so you’ll need to download and install an NDEF formatter.
The tapped tag is read-only. Some NFC tags can be locked to read-only (similar to old school VHS tapes).
The tapped tag is too small and cannot hold all the data.
A users PC doesn’t have NFC. As I mentioned from the start, NFC is an emerging technology; widespread adoption is still growing. To check whether a PC supports proximity, use the ProximityDevice.getDefault() method; the method returns NULL if no NFC radios are installed.

It’s fun and intuitive!

NFC is finally here, ready for mainstream consumers – Windows has the ecosystem and a well-designed end-to-end UX. The technology has a lot of potential to make apps and device experiences incredibly interactive. It’s fun and intuitive.

NFC is a big area, so stay tuned for more blog posts on other cool Windows 8 NFC developer experiences.

For more info about NFC and proximity, check out the resources below.

Resources

Link	Types
Guidelines for using proximity experiences	Doc
Proximity APIs	Doc
Testing and troubleshooting proximity apps	Doc
Publishing and subscribing (in further detail)	Doc
Proximity app sample	Sample
Got a question on proximity? Ask it here	Forum

Thanks,

Priya Dandawate
Program Manager, Devices and Networking

Contributions by: Max Morris, Marzena Makuta, Mike Loholt, Jake Sabulsky, and Vishal Mhatre

Creating connected Windows Store apps

Windows 8 Team — Wed, 10 Apr 2013 16:00:00 GMT

People are continually surrounded by devices that are connected to a network. Even the latest refrigerators and washing machines can connect to the internet and home networks. So it’s no surprise that end-users expect their apps to be connected as well. These “connected apps” consume the latest content from the web—social media, digital media, blogs, and other types of content. Developing connected apps has become the norm, but it can still be a challenge to handle common issues like loss of network connectivity, metered network costs, or performance issues. Windows 8 makes it easier than ever before to write a connected app.

In this post, we’ll look at some useful tips to help you provide a fast and fluid, hassle-free, connected experience for users of your Windows Store apps:

Pick the right API for your scenarios
Choose the right network capabilities
Adapt app behavior for metered networks
React to network status changes
Cache content for fluidity

Let’s dive into the details of each tip.

Pick the right API

If you're going to build a house, you want the right tools. You want a hammer for hammering nails, a saw for cutting boards, and a screwdriver for fastening with screws. In the same way, you’ll want to use the right networking APIs when you develop a connected Windows Store app. Windows 8 provides a variety of networking APIs that your app can use to communicate with other computers and devices over either the Internet or private networks. So your first step is to figure out what networking features your app needs.

The most common networking scenario is to access a web site to retrieve or store information. A simple example would be a game that uses a website to store user information and game scores. A more complex example might be an app that connects to a REST-based web service and uses a library provided by the web service to access or store information. Windows 8 has several APIs that connect with web services and web sites. With these APIs your app can access web services that support REST or send basic HTTP protocol commands (like GET and POST) to a web server. For web access, the API you want depends on the language you use to develop the app:

XMLHTTPRequest and WinJS.xhr—Apps written in JavaScript and HTML.
HttpClient—Apps written in C# or Visual Basic .NET and XAML.
XML HTTP Request 2 (IXHR2)—Apps written in C++ and XAML.

The following code shows how to perform a basic request and response with a REST-based web service. In this case, the web service could execute an ASP.NET script on the web server.

JavaScript

function makeXHRCall() {
    WinJS.xhr({ uri: "http://www.microsoft.com/en-us/default.aspx” }).done(
        function onComplete(result) {
            print(result.responseText);
        },
        function onError(err) {
            print("Error: " + err.responseText);
        });
}

private async void MakeHttpCall()
{
    HttpClient httpClient = new HttpClient();
    try {
        string response = await httpClient.GetStringAsync("http://www.microsoft.com/en-us/default.aspx");
    }
    catch (Exception) {
        // Handle exception.
    }
}

For more info about WinJS.xhr, see Connecting to web services (Windows Store apps using JavaScript and HTML). For more information about HttpClient, see Quickstart: Connecting using HttpClient (Windows Store apps using C#/VB/C++ and XAML) and the HttpClient sample.

Another common networking scenario is downloading or uploading files where the file transfer may take some time. An example would be a camera or photo gallery app that needs to upload or download photos or photo albums from a web service. These transfers can take a lot of time, so it doesn't make sense to have the user wait for the transfer to finish. The Windows.Networking.BackgroundTransfer API provides the ability to download or upload files even when your app is no longer running. The app starts the transfer when it’s running in the foreground and has focus, and Windows 8 then continues the transfer in the background even if the app is no longer running.

Another more specialized scenario is accessing syndicated content. The Windows.Web.Syndication API can retrieve feeds in the RSS or Atom formats. In addition, the Windows.Web.AtomPub API allows an app to publish data in various AtomPub formats.

For scenarios for which a specific, higher-level networking protocol is not available through an API, the Windows Runtime also supports TCP and UDP sockets (along with multicast). The Windows.Networking.Sockets API provides a StreamSocket (TCP) and DatagramSocket (UDP) to let you to implement other, higher-layer protocols.

Note: Windows 8 introduces a new type of socket called a WebSocket. For more information about WebSockets and when to use them, see Connecting with WebSockets.

The following table provides a more complete list of supported networking features, with links to additional information.

APIs

Functionality

Examples

Windows.Web.Syndication

Windows.Web.AtomPub

Retrieving feeds in the RSS or Atom formats across multiple versions. These APIs make it easy to implement support for newer formats such as OData. The Windows Runtime also supports the Atom Publishing Protocol, enabling the publication of Atom collections.
For more information, see Accessing and managing syndicated content.

Syndication sample

AtomPub sample

RSS Readers

Windows.Networking.BackgroundTransfer

Uninterrupted, cost-aware, and resumeable downloading and uploading of content, even when the calling app is not in the foreground. This API supports content transfer using the HTTP, HTTPS, and FTP protocols.
For more information, see Transferring data in the background.

Background Transfer sample

SkyDrive

Xbox Video

XMLHTTPRequest (JavaScript)

WinJS.xhr (JavaScript)

HttpClient (C#)

XML HTTP Request 2 (IXHR2) (C++)

Interacting with REST-based web services and other HTTP-based protocols.
For more information, see Connecting to web services.

XHR, handling navigation errors, and URL schemes sample

HttpClient sample

Bing Maps

Windows.Networking.Proximity

Detecting close proximity between two devices, after which apps can trigger network communication between them using socket APIs.
For more information, see Supporting proximity and tapping.

Proximity sample

Games

Collaborative apps

Windows.Storage.Pickers

Communicating with remote file shares.
For more information, see Accessing data and files.

File picker sample

Xbox Music

Photos

Windows.Networking.Sockets

Connecting to a service that uses a protocol not supported by APIs already mentioned, like SMTP, MAPI, or telnet, or connecting to another device on the same local network. Also used for apps that require socket-like semantics (asynchronous, bidirectional) to connect through the web (including HTTP proxies) to a new service.
For more information, see Connecting with sockets.

StreamSocket sample

DatagramSocket sample

Connecting with WebSockets sample

ControlChannelTrigger samples

Lync, collaborative whiteboard, or stock pickers

Windows.Storage.ApplicationData

Windows 8 automatically transitions certain application data between user devices. Roaming application data benefits apps where the user utilizes more than one device, such as a PC at work and a tablet at home, and installs the app on multiple devices.
For more information, see Guidelines for roaming application data.

Application data sample

Choose the right network capabilities

Network isolation is part of the app security model used by Windows 8. Windows actively discovers network boundaries and enforces network access restrictions for network isolation. When you deploy them properly, these capabilities help protect your users and apps from malicious attacks.

Apps must declare network isolation capabilities in order to define the scope of network access. Without declaring these capabilities, your app will not have access to network resources. See How to set network capabilities to learn more about how Windows enforces network isolation for apps.

Note that you can’t use networking as an interprocess communication mechanism between a Windows Store app and a desktop app on the same device. So you can’t use IP loopback addresses in a Windows Store app. There are limited exceptions for development purposes that allow use of IP loopback addresses when operating under the Visual Studio debugger. For more information, see How to enable loopback and troubleshoot network isolation.

Network access requests come in two categories:

Outbound, client-initiated requests: Your app acts as the client and initiates network access by sending an initial network request to a remote computer, usually a server. The app sends one or more requests to the server and the server sends back a single response or several responses. For example, all traffic from a web client app to a web server would be in this category.
Inbound, unsolicited requests: Your app acts as a network server and listens for inbound network requests from a remote computer. The remote computer initiates network access by sending an initial request to your app, which acts as a server. The remote computer sends one or more requests to your app, which sends back one or more responses to the remote computer. For example, an app that functions as a media server would be in this category.

Follow the principle of least privilege and add only capabilities your app needs. Your app might need only outbound, client-initiated requests, or it may also need to receive inbound, unsolicited requests. Some apps may also need access to user credentials and certificates when authenticating over a network.

The following table details the network isolation capabilities and other related capabilities often needed for connected apps. The first three are the primary network-isolation capabilities that connected apps use. In fact, your connected app must enable at least one of those first three capabilities. The other entries in the table are additional capabilities often needed by some connected apps.

Network capability

Description

Example apps

Internet (Client)

Provides outbound access to the Internet and networks in public places like airports and coffee shops. Most apps that require Internet access should declare this capability.

RSS readers

Social networks

Games

Internet (Client & Server)

Provides both inbound and outbound access to the Internet and networks in public places like airports and coffee shops. Inbound access to critical ports are always blocked. This capability is a superset of the Internet (Client) capability; there is no need to declare both.

P2P apps

Multiplayer games that discover players by using multicast

Private Networks (Client & Server)

Provides inbound and outbound network access at private locations trusted by the user. These are usually home or work networks. Inbound access to critical ports are always blocked.

Apps that access network attached storage (NAS) content

Line-of-business apps

Multiplayer games that discover players by using multicast on a private (home or work) network

Proximity

Required for near-field proximity communication with devices. Allows apps to access the network to connect to a device in close proximity, with user consent to send or accept an invitation.

Multiplayer games with people in close proximity

Enterprise Authentication

Provides the capability to connect to enterprise intranet resources that require domain credentials.

Line-of-business apps

Shared User Certificates

Provides the capability to access software and hardware certificates, such as smart card certificates, for validating a user's identity. When related APIs are invoked at run time, the user must take action (such as inserting a card or selecting a certificate).

Virtual private network apps

Line-of-business apps

Use this checklist to make sure network isolation is configured in your app:

Determine the direction of network access that your app needs; outbound client-initiated requests, inbound unsolicited requests, or both.
Determine the type of network resources that your app will communicate with: trusted resources on a home or work network, resources on the Internet, or both.
Configure the minimum required network isolation capabilities in the app manifest. You can do this using the App Manifest Designer in Microsoft Visual Studio 2012, or add them manually.
Deploy and run your app to test it using the network isolation tools provided for troubleshooting. For more information, see How to enable loopback and troubleshoot network isolation.

The following screen shot shows how to enable network capabilities using the App Manifest Designer in Microsoft Visual Studio 2012.

Select network capabilities in your app’s package.appxmanifest in Visual Studio 2012

Adapt app behavior for metered networks

Think about the last time you were approaching your monthly data cap or perhaps travelled abroad. In these situations I typically ended up using my device and apps cautiously to prevent any unnecessary network charges.

Windows 8 addresses this user problem by allowing apps to monitor available network resources and behave accordingly when on metered networks. To promote user confidence in your apps, you can make it able to tell when a connection may incur costs and then adapt its behavior to avoid or reduce charges.

The Windows.Networking.Connectivity API provides info about the type and cost of a network connection. This allows your app to determine when it makes sense to use network resources normally, use them conservatively, or ask the user.

A ConnectionProfile represents a network connection. Your app can use the ConnectionCost of a ConnectionProfile to determine whether to adapt its behavior. The NetworkCostType property indicates the type of a network connection. There are four possible values:

Unrestricted—Use of this network connection is unlimited. It has no usage charges or capacity constraints.
Fixed—Use of this network connection is unrestricted up to a specific limit.
Variable—Use of this network connection is metered on a per-byte basis.
Unknown—Cost information is not available for this network connection.

Several other Boolean properties for the ConnectionCost provide still more info.

Roaming—The connection is to a network outside of the home provider.
ApproachingDataLimit—The connection is approaching the usage allowance specified by the data plan.
OverDataLimit—The connection has exceeded the usage allowance specified by the data plan.

Have your app respond to the conditions indicated by these properties. Whenever a connection is Roaming, the data costs associated with network usage could be high. When the NetworkCostType is Variable, the network is a metered network, where the user pays for the amount of data sent or received on the network. When the NetworkCostType is Fixed, there’s cause for concern if the user is already over the data limit or approaching it.

By using this information, an app can follow these guidelines to decide how best to use network resources.

Behavior

Connection cost

App guidelines

Examples

Normal

NetworkCostType is Unrestricted or Unknown and ConnectionCost is not Roaming

App does not implement restrictions. App treats the connection as Unlimited in cost, and unrestricted by usage charges and capacity constraints.

Media player app can play an entire HD movie.

App can download large file without any restrictions or prompts.

Conservative

NetworkCostType is Fixed or Variable and ConnectionCost is not Roaming or OverDataLimit

App implements restrictions for optimizing network usage to handle operations on metered networks.

Media player app can play movies in lower resolutions.

App can delay non-critical downloads.

Opt-In

ConnectionCost is Roaming or OverDataLimit

App handles exceptional cases where the network access cost is substantially higher than plan cost.

App prompts user to access the network.

App suspends all background data network activities.

This code example checks the connection cost and returns suggestions for appropriate app behavior.

JavaScript

var CostGuidance = { Normal: 0, Conservative: 1, OptIn: 2 };
// GetCostGuidance returns an object with a Cost (with value of CostGuidance), 
// CostName (a string) and Reason, which says why the cost is what it is.
function GetCostGuidance() 
{
    var connectionCost = Windows.Networking.Connectivity.NetworkInformation.getInternetConnectionProfile().getConnectionCost();
    var networkCostConstants = Windows.Networking.Connectivity.NetworkCostType;
    var Retval = new Object();
    if (connectionCost.roaming || connectionCost.overDataLimit)
    {
        Retval.Cost = CostGuidance.OptIn;
        Retval.CostName = "OptIn";
        Retval.Reason = connectionCost.roaming
            ? "Connection is roaming; using the connection may result in additional charge."
            : "Connection has exceeded the usage cap limit.";
    }
    else if (connectionCost.networkCostType == networkCostConstants.fixed
        || connectionCost.networkCostType == networkCostConstants.variable)
    {
        Retval.Cost = CostGuidance.conservative;
        Retval.CostName = "Conservative";
        Retval.Reason = connectionCost.networkCostType == NetworkCostType.fixed
            ? "Connection has limited allowed usage."
            : "Connection is charged based on usage. ";
    }
    else
    {
        Retval.Cost = CostGuidance.Normal;
        Retval.CostName = "Normal";
        Retval.Reason = connectionCost.networkCostType == networkCostConstants.unknown
            ? "Connection is unknown."
            : "Connection cost is unrestricted.";
    }

    return Retval;
}

public enum NetworkCost { Normal, Conservative, OptIn };
public class CostGuidance
{
    public CostGuidance()
    {
        var connectionCost = NetworkInformation.GetInternetConnectionProfile().GetConnectionCost();
        Init(connectionCost);
    }
    public NetworkCost Cost { get; private set; }
    public String Reason { get; private set; }


    public void Init(ConnectionCost connectionCost)
    {
        if (connectionCost == null) return;
        if (connectionCost.Roaming || connectionCost.OverDataLimit)
        {
            Cost = NetworkCost.OptIn;
            Reason = connectionCost.Roaming
                ? "Connection is roaming; using the connection may result in additional charge."
                : "Connection has exceeded the usage cap limit.";
        }
        else if (connectionCost.NetworkCostType == NetworkCostType.Fixed
            || connectionCost.NetworkCostType == NetworkCostType.Variable)
        {
            Cost = NetworkCost.Conservative;
            Reason = connectionCost.NetworkCostType == NetworkCostType.Fixed
                ? "Connection has limited allowed usage."
                : "Connection is charged based on usage. ";
        }
        else
        {
            Cost = NetworkCost.Normal;
            Reason = connectionCost.NetworkCostType == NetworkCostType.Unknown
                ? "Connection is unknown."
                : "Connection cost is unrestricted.";
        }
    }
}

Use the network information sample to learn more about adapting app behavior for metered networks.

Users can also run Task Manager to see the amount of network data that each app is consuming. This screen shot shows an example.

App History tab in Task Manager allows users to see CPU and network consumption by apps

React to network status changes

In any mobile device scenario, networks can come and go. A mobile 3G or 4G broadband network could go out of range within a user’s home or garage while Wi-Fi is still available. Similarly, Wi-Fi may go out of range when a user leaves home. There may also be times when no network is available. Given the proliferation of Wi-Fi and mobile broadband networks, such network changes occur frequently.

A NetworkStatusChanged event indicates that the available cost or connectivity options may have changed. To react to network status changes and provide a seamless customer experience when a change occurs, have your connected apps follow these scenario guidelines.

Connection loss due to error

In most cases, connections can be reestablished by simply retrying the network operation. If this fails, then wait for a NetworkStatusChanged event. We recommend that apps use an increasing backoff interval between retries, starting with a value of 50 milliseconds and increasing this backoff interval exponentially if connections continue to fail.

Loss of network

Inform the user that the connection has been lost, then register and wait for a NetworkStatusChanged event.

New network availability

There may be cases where the device is connected to multiple networks. For example, a user may be connected to mobile broadband and chatting with friends using the Windows 8 Messaging app before arriving at home and connecting to the unrestricted network there as well. The default policy in Windows 8 is to prefer an unrestricted network over a metered network, and a faster network over a slower network. However, existing connections established by an app do not automatically switch over to a new network. The app must get involved because only the app can make the best decision whether or not to switch to the new network.

For example, if a video stream is close to completion, it may not make sense to switch to the new network. However, if the current network is dropping packets, is too slow, or the stream will take additional time to complete, switching to the new network may be best.

If you determine that switching networks is plausible for your app scenario, follow these guidelines when you detect a new network:

Check the network costs of the existing and new network. If it makes sense to switch to the new network, try making a new network connection and retry the network operation based on the guidelines just mentioned. Windows automatically selects the unrestricted network over the metered network, and the faster network over the slower one if available.
If the new network connection succeeds, use the new network connection in your app and cancel the original network operation on the previous network if the connection already exists.

Change in network cost

A change in network cost can occur when the NetworkCostType is Fixed and usage is approaching the data limit or goes over the data limit. A change in network cost can also result if the NetworkCostType becomes Variable, or if Roaming changes to true. In these cases, adapt app behavior based on the guidelines in the preceding tip.

These code examples use the NetworkStatusChanged event to provide a seamless app experience for various network status changes. Both examples use a global Boolean variable called registeredNetworkStatusNotification, initially set to false.

JavaScript

// Register for NetworkStatusChanged notifications, and display new 
// Internet ConnectionProfile info upon network status change.
function registerForNetworkStatusChange() {
    try {

        // Register for network status change notifications.
        if (!registeredNetworkStatusNotification) {
            var networkInfo.addEventListener("networkstatuschanged", onNetworkStatusChange);
            registeredNetworkStatusNotification = true;
        }
    }
    catch (e) {
        print("An unexpected exception occurred: " + e.name + ": " + e.message);
    }
}

// Event handler for NetworkStatusChanged event
function onNetworkStatusChange(sender) {
    try {
        // Get the ConnectionProfile that is currently used to connect 
        // to the Internet.
        var internetProfile = networkInfo.getInternetConnectionProfile();
        if (internetProfile === null) {
            print("Not connected to Internet\n\r");
        }
        else {
            internetProfileInfo += getConnectionProfileInfo(internetProfile) + "\n\r";
            print(internetProfileInfo);
        }
        internetProfileInfo = "";
    }
    catch (e) {
        print("An unexpected exception occurred: " + e.name + ": " + e.message);
    }
}

// Register for NetworkStatusChanged notifications, and display new 
// Internet ConnectionProfile info upon network status change.
void NetworkStatusChange()
{
    // Register for network status change notifications.
    try
    {
        var networkStatusCallback = new NetworkStatusChangedEventHandler(OnNetworkStatusChange);
        if (!registeredNetworkStatusNotification)
        {
            NetworkInformation.NetworkStatusChanged += networkStatusCallback;
            registeredNetworkStatusNotification = true;
        }
    }
    catch (Exception ex)
    {
        rootPage.NotifyUser("Unexpected exception occurred: " + ex.ToString(), NotifyType.ErrorMessage);
    }
}

// Event handler for NetworkStatusChanged event
async void OnNetworkStatusChange(object sender)
{
    try
    {
        // Get the ConnectionProfile that is currently used to connect 
        // to the Internet                
        ConnectionProfile InternetConnectionProfile = NetworkInformation.GetInternetConnectionProfile();

        if (InternetConnectionProfile == null)
        {
            await _cd.RunAsync(CoreDispatcherPriority.Normal, () =>
            {
                rootPage.NotifyUser("Not connected to Internet\n", NotifyType.StatusMessage);
            });
        }
        else
        {
            connectionProfileInfo = GetConnectionProfile(InternetConnectionProfile);
            await _cd.RunAsync(CoreDispatcherPriority.Normal, () =>
            {
                rootPage.NotifyUser(connectionProfileInfo, NotifyType.StatusMessage);
            });
        }
        internetProfileInfo = "";
    }
    catch (Exception ex)
    {
        rootPage.NotifyUser("Unexpected exception occurred: " + ex.ToString(), NotifyType.ErrorMessage);
    }
}

To learn more about the NetworkStatusChanged event, see Quickstart: Managing connection events and changes in availability and the Network information sample.

Cache content for fluidity

Caching content to disk lets your app behave fast and fluidly. For example, an RSS feed reader app can immediately display feeds that were cached to disk from a previous session. As soon as the latest feeds are available, the app updates its content. Caching ensures that the user has content to read immediately upon launch while the app gets new content.

Windows 8 provides the ApplicationData class in the Windows.Storage namespace. This class provides access to the app data store. This data store consists of files and settings that are local to the device, roam across multiple devices, or are temporary.

Files are ideal for storing large data sets, databases, or data that is in a common file format. Files can exist in the Roaming, Local, or Temporary folders. Here’s what that means:

Roaming files are synchronized across multiple machines and devices where users have signed in with connected accounts. Roaming of files is not instant; the system weighs several factors to determine when to send the data. Keep the use of roaming data below the quota (available via the RoamingStorageQuota property); if the quota is exceeded, roaming of data will be suspended. Files cannot be roamed while an app is writing to them, so be sure to close your app’s file objects when they are no longer needed.
Local files are not synchronized across machines. They remain on the machine on which they were originally written.
Temporary files are subject to deletion when not in use. The system considers factors such as available disk capacity and the age of a file in determining when or whether to delete a temporary file.

These code examples cache content to disk. Caching the server response allows your app to immediately display content to the user after a termination and relaunch. For brevity, these examples don’t show how to write settings to the app data store or how to respond to roaming events. The Application data sample covers those details.

JavaScript

var roamingFolder = Windows.Storage.ApplicationData.current.roamingFolder;
var filename = "serverResponse.txt";

function cacheResponse(strResponse) {
    roamingFolder.createFileAsync(filename, Windows.Storage.CreationCollisionOption.replaceExisting)
        .done(function (file) {
            return Windows.Storage.FileIO.writeTextAsync(file, strResponse);
        });
}

function getCachedResponse() {
    roamingFolder.getFileAsync(filename)
        .then(function (file) {
            return Windows.Storage.FileIO.readTextAsync(file);
        }).done(function (response) {
            print(response);
        }, function () {
            // getFileAsync or readTextAsync failed. 
            // No cached response.
        });
}

MainPage rootPage = MainPage.Current;
StorageFolder roamingFolder = null;
const string filename = "serverResponse.txt";

async void cacheResponse(string strResponse)
{
    StorageFile file = await roamingFolder.CreateFileAsync(filename, CreationCollisionOption.ReplaceExisting);
    await FileIO.WriteTextAsync(file, strResponse);
}

async void getCachedResponse()
{
    try
    {
        StorageFile file = await roamingFolder.GetFileAsync(filename);
        string response = await FileIO.ReadTextAsync(file);
    }
    catch (Exception)
    {
        // getFileAsync or readTextAsync failed.
        // No cached response.
    }
}

For more info about the app data store, see the roaming your app data post and try out the Application data sample.

Wrapping it up

When planning your Windows Store apps, use the guidelines in this post to provide a great, hassle-free, connected experience. These tips can make your development process easier, while maintaining fluidity and boosting user confidence in your apps.

- Suhail Khalid, Program Manager II, Windows

Contributions by: Steven Baker and Peter Smith

Register now for //build/ 2013!

Windows 8 Team — Tue, 02 Apr 2013 15:23:03 GMT

Last week Steve Guggenheimer announced //build/ 2013. The conference is taking place June 26-28, 2013 at the Moscone Center in San Francisco. //build/ is a great opportunity to learn more about developing Windows Store apps. The conference will include great presentations, demos, info sessions, etc. for you. Many of us from the engineering team are traveling down to San Francisco to give these demos and answer your questions. There’s no better place to get the latest and greatest info on Windows Store app development.

Registration begins today, Tuesday April 2^nd. You can see all the details about the conference and register at www.buildwindows.com.

We hope to see you there!

Windows Store app support in jQuery version 2.0

Windows 8 Team — Mon, 01 Apr 2013 18:00:00 GMT

If you’ve already done some web development, it’s likely you’ve used the open source JavaScript framework jQuery. And if you’ve tried building Windows Store apps using jQuery, you might have run into errors related to JavaScript runtime or dynamic content. With the upcoming release of v2.0, the jQuery team has addressed these concerns. The jQuery v2 beta now supports development in HTML5/JS for Windows Store apps. As a web developer, you can use your existing skills and assets to build awesome apps for Windows 8. You can try it with the latest jQuery 2.0 beta build now.

“The jQuery team is excited about the new environments where jQuery 2.0 can be used. HTML and JavaScript developers want to take their jQuery knowledge with them to streamline the development process wherever they work. jQuery 2.0 gives them the ability to do that in environments such as Windows 8 Store applications.” - Dave Methvin, president, jQuery Foundation

Windows Store app: a different context for JavaScript code

You might be wondering why jQuery didn’t “just work” before. All Windows Store Apps, whether written in HTML/JS, C# or C++, have native access to the Windows Runtime, so a new security model was created to help your apps run securely on the new platform. Additionally, some of the APIs that are common to the web were modified to fit their new native environment in a more meaningful way. These differences can cause issues for code that was expecting to be running in a browser. Most issues are related to dynamic content – you may have gotten “HTML1701: Unable to add dynamic content…” or exceptions “0x800c001c - JavaScript runtime error: Unable to add dynamic content...”

For more info about this model check out the Delivering reliable and trustworthy apps post. You can learn about differences between the context of a Windows Store application and a Web browser on the Windows Dev Center.

Updating jQuery to support the new model

As many of you know, jQuery is a very popular JavaScript framework on the web because it makes things like HTML document traversal and manipulation, event handling, animation, and Ajax much simpler with an easy-to-use API that works across many browsers.

To enable all these features of jQuery in your Windows Store apps the jQuery experts at appendTo worked with the jQuery community to update jQuery to support the new Windows 8 app model. Our own engineers from Microsoft Open Technologies provided technical support for the effort to make sure all the changes took full advantage of the platform.

Adding support for Windows Store Apps in jQuery involved initial testing, porting of Unit Tests, and evaluating jQuery dependencies, such as the Sizzle selector engine, which is at the heart of jQuery. appendTo identified several areas in jQuery support logic, as well as sparse items throughout Sizzle, used to target elements in a document, that required re-authoring to work within the guidelines of the Windows Store app security model.

appendTo submitted code directly to the jQuery Core project, which integrated this support, so now you get all this for free as soon as you add jQuery into your app. Additionally, you’ll want to practice some alternative patterns when using jQuery in a Windows Store app. You can find more info on these patterns on the net.tuts+ site. Check out appendTo’s blog post for more details on the changes they made in their updates.

Let’s code!

If you’re an HTML5 and JavaScript developer, you can build Windows 8 apps using what you already know along with your existing JavaScript code and libraries. For your jQuery code, upgrade to jQuery 2.0 beta and follow the new patterns shared by appendTo. If you don’t use jQuery, you can apply these same patterns and techniques to your own code and libraries to make them fully compatible with Windows 8.

If you want to learn more new opportunities for using your web development skills with the Windows platforms, check out the MS Open Tech blog post.

--Olivier Bloch, Senior Technical Evangelist, MS Open Tech

Developing Windows Store games

Windows 8 Team — Fri, 22 Mar 2013 15:00:00 GMT

Windows 8 has changed the PC landscape with innovative form factors, new chip architectures, exciting commerce models and huge opportunities. PC games have long been a staple of the way computers are enjoyed. Now, more than ever, games exemplify the value of this new landscape of devices. Thanks to the Windows Store, games are easier to acquire, play, share with friends and update safely. It’s no wonder then that games account for such a large number of downloads, generate a lot of revenue, and drive the most user engagement on the new platform. With GDC around the corner, more game developers are eager to learn about the Windows 8 opportunity.

So, how do you create a great Windows Store game? What does Windows offer to make your game more creative, innovative, profitable and easier to develop? What tools, technologies and services can you use? What’s available out there in the ecosystem? What are other discoveries developers shared when developing for Windows 8? This post will answer questions about these topics and clarify how you too, can develop an awesome Windows Store game.

Windows 8 game design and development considerations

Windows 8 was designed and engineered specifically for the enjoyment of entertainment experiences. The Windows 8 User Experience (UX) guidelines promote full screen imagery, as well as fast and fluid interactions with no borders or extra window decorations. The design guidance recommends that apps focus on experiences that invite users to engage and provide interactions that guide them through an immersive experience. Main game controls should be easily accessible and secondary controls should be tucked away in an app bar or in a settings panel until they are needed. So, that’s great for general apps, but how do these principles affect games? After all, game developers have been providing fast and fluid, full screen, immersive experiences for a long time. Nevertheless, several basic questions arise almost right away:

How can game mechanics scale from powerful desktop PCs to notebooks and tablets?
What are the most important form factors to target?
Can you enable games for touch, game controller and keyboard/mouse simultaneously?
What are the most important screen sizes, aspect ratios and resolutions?

Game developers have been using a wide range of technologies to deliver entertaining games to the PC community for a long time. The APIs used on Windows have evolved significantly over time. With Windows 8, a new development platform has been added. The Windows Runtime API aggregates the best technologies from APIs of the past and brings significant improvements in performance, security, development consistency and servicing. The Windows Store adds a new way for games to be discovered, distributed and serviced. These new APIs significantly add value for game developers targeting the new development model. You might have some questions when you start to develop a Windows Store game, for example:

What are the best Windows Runtime APIs to use for game development?
How do the development models map to the different game genres?
How do I transition my code from other platforms?
How do I update my code from older versions of Windows?
What, if any, of my game assets might need updating?
Are there resources to help me reduce development costs?
Where is the DirectX SDK?

Gaming reimagined

Every game starts with an idea. Where that idea comes from can be very different. Sometimes it randomly pops into your head while you’re taking a walk, or while you’re in the shower. Other times, a more collaborative and iterative approach with your team may result in the idea. Once you’ve got your idea, you need to decide what type of game it is. Maybe you want a new unique game. Or perhaps you want to port your existing game. It could be a shooter, or puzzle, or racing game – no matter what type of game it is, there’s a home for it in the Windows Store. The Gaming Case Studies presented at //build/ 2012 might inspire you. If you have a Windows Store developer account you can browse the games’ subcategories to be inspired and see how different game categories are performing in different regions.

Game design guidance

Once you’ve decided what game you want to build, making design decisions on the front end can save you a lot of development time later on. The Windows 8 game category design guidance gives you some ideas about how best to attract players and keep them engaged with tiles and notifications. There are also suggestions about what type of overall layout to use and where to place primary and secondary controls.

You can find recommendations about interactions and how to incorporate touch, sensors and contracts into your game. Decisions about game mechanics and controls should be made as early as possible to scope development. That said, the Windows Runtime platform makes it more convenient than ever to support touch, pen (ink) and mouse with the same code so you don’t have to design special mechanics for different form factors. Because every Windows PC has a place to plug in a game controller, don’t miss out on the opportunity and make sure you include that control mechanism in your game as well.

Plan how – and at what pace – you’ll introduce game interactions and mechanics to the player. Too slow and they may lose interest; too fast and they may get frustrated. Perhaps most important of all, decide what monetization model and commerce platform you’d like to use. The Windows Store allows you to choose your business model. It supports Free to Play, Ad-based, In-app Purchases and Downloadable Content. Windows Store games can take advantage of the built-in time-based or feature-based trials. Alternately, you can use a third-party commerce provider or roll your own. Either way, as these issues can significantly impact your game’s success, monetarily or in popularity, they are important to consider.

Like all Windows Store apps, games have to support the different activation, view and suspension states. The design guidance offers some help with considerations for how and when to pause your game, how and when to suspend your game’s state, and how to handle full screen, snapped and filled view states. Decide how your game will support landscape and portrait orientations. Consider the size of hit targets and other on-screen controls when adjusting the resolution of your game’s assets to match different screen sizes (or parts of them). Also don’t forget to take screen aspect ratios, resolutions, and DPI settings into consideration. This will make sure your game’s content renders correctly on any screen size and scale factor.

Finally, remember to consider a few additional things that can help increase your game’s accessibility and socialization capabilities. A high contrast mode and extra audio queues could help increase visibility or playability and therefore encourage adoption among players in less than ideal lighting conditions or with visual impairments. Additionally, leveraging the platform’s built-in capabilities for online identity (authentication), data roaming and sharing to other apps can lead to increased engagement through social activity such as comparing game results and playing games across different PCs.

Game development guidance

DirectX is considered to be at the heart of the Windows game development platform. However, many other components were developed and transitioned in to the Windows 8 SDK to provide all the required capabilities the platform needs to support the diverse Windows gaming ecosystem. We provide a consistent and comprehensive development approach. We also incorporated best practices learned from other game development platforms. More than anything, however, we emphasized and observed two key architectural goals. Performance and power consumption were at the core of every architectural decision – as described in the Hardware Accelerating Everything: Windows 8 Graphics blog post. Developing games on Windows 8 rocks because the entire platform was designed to deliver fast and fluid entertainment experiences.

C++ with DirectX is the preferred development language for games

The Windows Runtime provides a rich set of APIs that expose all the new devices and sensors in a convenient, consistent way, and simplifies Windows event handling. There’s a single Windows SDK so every API you need to develop a Windows Store game is available in Microsoft Visual Studio 2012. For the most high-fidelity and immersive experiences, you’ll want to use the Windows 8 DirectX APIs to build 3D games. This is the easiest version of DirectX to develop with, and it supports a wide range of graphics feature levels, from DirectX 9.1 to all the latest hardware features exposed in DirectX 11.1, allowing you to tailor your game to every PC from power-efficient ARM-based portable Windows 8 tablet PCs to overclocked multi-GPU gamer rigs.

If you’re comfortable with a particular development language, you can use a lot of your existing skills and experience in Windows 8. Windows Store games can be developed in a number of technology combinations, depending on the type of game you’re developing and your preference. You’re not going to be forced or constrained to one syntax or model. Managed code developers can build great, smooth 2D games with XAML that leverage the strength and features of the Windows Store platform. If you’re a web developer, you can leverage your existing web and web game development skills to make a game that can be monetized through the Windows Store. For 3D interactive games, we recommend you use C++ with DirectX (and optionally XAML), which will be the main focus of the rest of this article.

Game development components

Windows 8 offers built-in game technology that ships with every version of the OS and resides on every PC so you don’t have to worry about distributing it or manage multiple versions. There’s no need to find, download and install additional components.

Figure 1: The Windows 8 game development components and libraries

From graphics, audio and input, to file I/O, scheduling, math and networking – each component is accessible in the development language of your choice. Lower level components offer more flexibility, resource management and performance but may require additional code to comprehensively control processing and the flow of data it requires. With C++, you have a direct line to the GPU, CPU and low-level services of the Windows 8 platform, allowing you to write high performance code. With the new C++/CX language extensions, the syntax approaches the simplicity of C#. You get transparent object management via reference counting, and yet there’s no runtime layer, garbage collection or just-in-time compilation behaviors that could compromise the smooth performance of your game.

For 3D and 2D graphics, media, imaging and many of the other gaming components – the Windows 8 DirectX technologies provide a comprehensive set of APIs, components and libraries to build upon. Check out Getting started with DirectX game development for a comprehensive overview. The new Windows 8 graphics stack is better integrated, making Direct2D, Direct3D, DirectVideo and DirectCompute components easier to use together and requiring fewer duplicated resources than before. We’ve also added built-in support for the Xbox controllers with the XInput library. To learn more about it see Working with Input and controls in your DirectX game. The improved APIs for audio and sound mixing with XAudio2 are covered in the Working with audio in your DirectX game section, and simplified math functions and types are covered in the DirectXMath programming guide.

One of the greatest advantages of the DirectX/C++ development approach is that you can reuse significant amounts of your code to create a Windows Store game (and Windows Desktop game), a Windows Phone game, and an Xbox 360 game. The DirectX APIs are relevant to all Microsoft gaming platforms. Everything you’ll need to develop a great Windows game is included in the Runtime, the Windows SDK and Visual Studio 2012. For info about the legacy DirectX SDK, see Where is the DirectX SDK? There are several additional development models available in Windows 8. A hybrid model that supports DirectX and XAML interop provides the best control and performance and the convenience of the WinRT UI toolkit.

Development tools

We provide a great set of tools to meet the demands of Windows Store game developers. Visual Studio 2012 includes a template for DirectX Windows Store apps that gives you a head start in developing for Direct3D. The template code provides the basic view provider infrastructure and window support, and references to all the necessary headers and components. There are other templates to explore that will make sure you are using best practices no matter which game development model you choose.

Additionally, new features in Visual Studio 2012 have been added to improve game development, debugging and profiling. Investments in Visual Studio 2012 Graphics Tools were made to ensure that graphics application development is seamlessly integrated. Work with 3D models, view textures and images, or create, edit and compile HLSL shaders without ever leaving the familiar IDE interface. Debugging graphics intensive DirectX applications in Visual Studio 2012 is now more intuitive with the integration of graphics API capture and playback features (previously known as Windows PIX).

Samples and tutorials

These samples provide a great range of source code examples to get you started on your game development quickly. Each sample focuses on a particular technology or technique. The tutorials and samples were developed with a progression in mind. They are in logical order beginning with the sparsest amount of code and simplest approach to help you get started. Each additional sample adds to the previous sample with one or two additional concepts until an entire game is created. Writing Code for DirectX and C++ Windows Store apps explains some of the things you need to know about writing DirectX and C++ code for Windows Store apps.

Direct3D Tutorial: This five step tutorial shows how to initialize Direct3D, draw to the surface, and display updates to the surface using the swap chain. The “spinning cube” displayed by this sample is extended by other Direct3D samples, so this is a great place to start if you’re new to the Direct3D APIs.
DirectX Touch Sample: This shows very minimal touch support added to the spinning cube from D3DTutorial. Specifically, this shows how to connect your Direct3D animation updates to the touch events provided by the Windows Runtime. See the Bump Mapping sample for pinch-to-zoom navigation.
Direct3D Sprite Sample: This provides a Direct3D implementation of sprite batch behaviors, similar to the XNA SpriteBatch API. Sprites are 2D bitmaps that can be transformed and managed independently in a 3D scene, typically used in 2D games or to represent computationally expensive or distant objects in 3D games.
Resource Loading Sample: This demonstrates an approach for loading resources and assets like shaders, textures, and meshes. (Note that each content type has an associated build rule in the project. You can add your own content processor apps, and build your own rules to invoke them.)
Direct3D Bump Mapping Sample: This demonstrates bump mapping using a normal map and per-pixel lighting. The sample provides code for Surface-shaded lighting of an object using a normal map and a color texture. It also implements a very basic pinch-to-zoom control without the gesture recognizer.
Direct3D Post-Processing Sample: This demonstrates post-processing the simple rotating cube scene using down-scaled intermediate buffers in a Windows Store C++ app with Direct3D. It demonstrates the use of two different shaders depending on the feature level of the hardware. The intermediate render target can be modified to render to a smaller surface to improve performance, and then scale up to the final native resolution of the device for high quality.
AUDIO2 Audio File Playback Sample: This sample app shows how to incorporate the XAudio2 APIs for low-latency interactive sound effects into your DirectX game for a better aural experience.
XINPUT Game Controller Sample: This shows how to add Xbox controller support to your DirectX game. It reads input from an Xbox game controller and displays data about the analog stick movements and button presses. It shows how to get input state from an attached controller and draw to the display using Direct2D and DirectWrite.
Direct3D Stereoscopic 3D Sample: Windows 8 supports stereo 3D as a core OS feature. This app shows how to incorporate stereoscopic 3D into your DirectX game. It also demonstrates how to respond to system stereo changes in Direct3D.
Trials and in-app purchases are so important to the success of games, so this sample demonstrates how to use the licensing API provided by the Windows Store to determine the license status of a game or a feature that is enabled by an in-app purchase.

The following are end-to-end samples that combine the individual techniques into full games:

DirectX Simple 3D Shooting Game: This end-to-end sample app and comprehensive code walkthrough shows how to incorporate various control types and DirectX techniques in a simple first-person shooting gallery game. If you’re comfortable with the basics of all the individual technique samples, this is a good place to see all the components of a Windows Store Direct3D game in action.
XAML DirectX Simple 3D Shooting Game: This demonstrates the basic end-to-end implementation of a simple first person 3-D game using DirectX (Direct3D 11.1, Direct2D, XInput, and XAudio2) and XAML in a C++ app. Direct3D is used to render the 3D content and XAML is used for the heads-up display and game state messages.
DirectX Marble Maze Game Sample: This end-to-end game app is a simple labyrinth game where the player is challenged to roll a marble through a maze of pitfalls using tilt controls. It demonstrates how to fit all the game components into a single application. We’ve also provided some rich guidance around this app in the form of a complete code walkthrough.

Techniques for developing games

Several development patterns, best practices and techniques that are particularly relevant to game development are worth pointing out:

Targeting different Direct3D feature levels helps you understand how to optimize across many devices that have different levels of graphics performance. This will enable you to reach a wider audience for your Windows Store game built for Windows using DirectX with C++.
Asynchronous programming ensures your game takes advantage of multiple cores and hyper-threaded CPUs. Your game’s graphics, audio, logic, file I/O and networking can all be parallelized for best performance and battery life.
Use thread pool parallelization for Windows Store games instead of traditional threading APIs (such as CreateThread). The task model is especially important for rendering and ensuring a responsive UI, as described in this post.
Supporting screen orientation, covers screen rotation and DPI scaling of content and input for DirectX applications. This helps make sure your game works well on various screen resolutions.
Adding mouse move/look controls to your game explains a traditional mouse-like navigation technique that has been adapted to add touch for the Windows Store development model.
Developing mouse controls discusses the implementation of relative mouse controls, which hides the system cursor and returns relative screen coordinates rather than absolute values.
Game publishing requirements provides Windows 8 game developers with info about the tools and support for common game publishing scenarios, such as ratings certification and packaging.
Supporting Windows RT and ARM processors gets your DirectX Windows Store game up and running on Windows RT devices, targeting Direct3D feature level 9_1 and compiling an ARM package.

Using middleware to reduce development time or cost

Developing high quality professional games can be costly. Developing games for multiple platforms can be complex, error prone, and even more costly. Many established game studios build tools and develop production technologies that make up their game development process or “pipeline.” These investments help studios leverage their game assets between different games and platforms. Rendering engines, user interface tool kits, visibility occlusion, physics simulators, audio video authoring, animation interpolation and artificial intelligence are just a few of the technology categories typically involved in game development. Some gaming technologies can take many years to develop and fine-tune.

Proprietary gaming pipelines are incredibly valuable and many studios consider their investments as strategic as the games they make. Not everyone can afford the time or cost of developing a pipeline however. Luckily, third-party vendors offer end-to-end game development pipelines or individual technology libraries that provide these capabilities. Since Windows 8 launched, many gaming middleware vendors have transitioned their offerings to the new Windows Store app model. Using these products will get your game in the Windows Store much faster and with much less risk. As time progresses, we expect more vendors to announce and ship products for Windows Store game development. The following (in alphabetical order) is a compilation of third-party gaming middleware vendors that (at the time of writing) have announced or delivered versions of their product that support Windows 8 game development.

Appcelerator	appMobi {!}	Audiokinetic Wwise
Autodesk Scaleform	Cocos2d	Epic Unreal Engine 3
Exit Games Photon Server	Fortumo Mobile Payments	Firelight Technologies FMOD
GameSalad Creator	Havok Physics	Havok Vision Engine
MonoGame	Ogre Rendering Engine	NVIDIA PhysX
Scirra Construct 2	SharpDX	ShiVa3D
SlimDX	Unigine Engine	Unity 3d
Yoyo Games GameMaker

Microsoft’s XNA Game Studio is a game development pipeline that targets the Xbox 360, Windows Phone and Windows. However, it’s not compatible with Windows Store game development, (although XNA games are supported as Windows 8’s desktop apps). DirectX development with Visual C++/CX borrows many patterns and practices from XNA, and shares many conceptual similarities. So many XNA game developers will find it relatively easy to transition to DirectX and C++ development than ever before. Alternatively, we have seen developers successfully use the open source MonoGame library that replicates many of the XNA Game Studio capabilities. Several articles have been written about leveraging assets created with XNA for games targeting the Windows Store. Here’s a link to more info on the subject.

Additional resources for developing games

The documentation has a dedicated game development area on MSDN
The game-centric sessions, slides decks and recordings of talks that were given at //build/ 2012
The game-centric sessions, slides decks and recordings of talks that were given at GDC 2012
The game-centric sessions, slides decks and recordings of talks that were given at //build/ 2011
Help and support is available on The Developer Center which has a dedicated forum for game development for game developers like you who can provide answers when you need them
The DirectX Toolkit is a collection of helper classes for writing Direct3D 11 C++ code
Other great resources include Chuck Walbourn’s blog and Shawn Hargreaves’ blog

Summary

Windows 8 reimagines PCs and with new form factors, innovative technologies and lucrative commerce models that are perfect for gaming. The platform represents a green-field of opportunity for those who take advantage of it. The Windows Store has several thousand games at the time of writing and that number grows daily. The goal of this post was to help you understand what it would take to create a great Windows Store game of your own to leverage the possibilities. The information was meant to clarify how Windows 8 can make game development easier, more creative, innovative and profitable. We’ve reviewed what tools, technologies and services are available on the platform and what third-party technologies are available. As we head out to the annual Game Developer Conference in San Francisco, look to this post for guidance as you develop Windows Store games.

Game On!

Shai Hinitz, Sr. Program Manager

Alive with Activity, Part 3: Push notifications and Windows Azure Mobile Services

Windows 8 Team — Wed, 13 Mar 2013 22:51:25 GMT

In Part 1 of this series we explored what “aliveness” means to a user and how apps participate in creating that experience. In Part 2 we looked at how to write and debug web services to support periodic updates for live tiles. Here in Part 3 we’ll complete the story by understanding how to deliver tile updates, toasts, and raw notifications to specific client devices on demand through the Windows Push Notification Service (WNS), and how Windows Azure Mobile Services simplifies the whole process.

Push notifications

Periodic updates, as we saw in Part 2, are initiated from the client side and provide a polling or “pull” method of updating a tile or badge. “Push” notifications happen when a service directly sends an update to a device, where that update can be specific to a user, an app, and even a secondary tile.

Unlike polling, push notifications can happen at any time with much greater frequency, though be aware that Windows will throttle the amount of push notification traffic on a device if it’s on battery power, in connected standby mode, or if notification traffic becomes excessive. This means there is no guarantee that all notifications will be delivered (especially if the device is turned off).

So avoid thinking that you can use push notifications to implement a clock tile or other tile gadgets with a similar kind of frequency or time resolution. Instead, think about how you can use push notifications to connect tiles and notifications to a back-end service that has interesting and meaningful information to convey to the user, which invites them to re-engage with your app.

Before we dive into the details, understand that there are two distinct kinds of push notifications:

XML updates that contain tile or badge updates, or toast notification payloads: Windows can process such push notifications and issue the update or toast on behalf of an app. An app can also handle these notifications directly, if desired.
Binary or raw notifications that contain whatever data the service wants to send: these must be handled by app-specific code because Windows won’t know what to do with the data otherwise. See Guidelines and checklist for raw notifications for details such as size limits (5KB) and encoding (base64).

In both cases, a running (foreground) app can handle push notifications directly through the PushNotificationChannel class and its PushNotificationReceived event. For XML payloads, the app can modify the contents, change tags, and so forth, before issuing it locally (or choosing to ignore it). For raw notifications, the app processes the contents and then decides which notifications to issue, if any.

If the app is suspended or not running, it can also provide a background task for this same purpose. The app must request and be granted lock screen access, which then allows such app-specific code to run when a notification is received.

A background task typically does one or two things when the notification arrives. First, it might save some relevant information from the notification into local app data, where the app can retrieve it when it’s next activated or resumed. Second, the background task can issue local tile and badge updates and/or toast notifications.

To understand raw notifications better, consider a typical email app. When its back-end service detects new messages for a user, it sends a raw push notification to WNS that contains a number of email message headers. The service does so using a channel URI that’s connected to the specific app on that user’s specific device.

WNS then attempts to push that notification to the client. Assuming it succeeds, Windows receives that notification and looks for the app that’s associated with the channel URI in question. If it cannot find a suitable app, the notification is ignored. If an app exists and it’s running, Windows fires the PushNotificationReceived event, otherwise Windows looks for and invokes an available background task for that app.

Either way the raw notification ends up in the hands of some app code, which then processes the data, issues a badge update to the app tile to indicate the number of new messages, and issues up to five cycling tile updates with message headers. The app can also issue toast notifications for each new message that’s arrived, or at least one that indicates there’s new mail.

As a result, toasts tell the user that new email has arrived, and the app’s tile on the Start screen provides a quick and immediate view of new mail activity.

For more info about these client-side event handlers and background tasks, see the Raw notifications sample, the Being productive in the background—background tasks post on this blog, and the Background networking whitepaper. For our purposes here, let’s turn now to the service side of the story.

Working with Windows Push Notification Service (WNS)

Through the cooperation of Windows, apps, services, and WNS, it’s possible to deliver user-specific data to a specific app tile (or toast or raw notification handler) on a specific device for a specific user. The relationships between all these pieces is shown below.

Clearly, some wiring is necessary to make all this work harmoniously:

You (the developer) register the app in the Windows Store to use push notifications. This provides an SID and client secret that the service uses to authenticate with WNS (these bits should never be stored on client devices for security purposes).
At runtime, the app requests a WNS channel URI from Windows for each of its live tiles (primary and secondary), or one for raw notifications. An app must also refresh these channel URIs every 30 days, for which you can use another background task.
The app’s service provides a URI through which the app can upload those channel URIs along with any data that describes its use (such as location for weather updates or a specific user account and activity). Upon receipt, the service stores those channel URIs and associated data for later use.
The service monitors its backend for changes that apply to each particular user/device/app/tile combination. When the service detects a condition that triggers a notification for a particular channel, it builds the content of that notification (XML or raw), authenticates itself with WNS using the SID and client secret, and then sends the notification to WNS along with the channel URI.

Let’s look at each step in detail. (And just as a preview, if dealing with HTTP requests makes you nervous, Windows Azure Mobile Services relieves you from many of the details, as we’ll see.)

App registration with the Windows Store

To obtain the SID and client secret for your service, refer to How to authenticate with the Windows Push Notification Service (WNS) on the Windows Developer Center. The SID is what identifies your app with WNS, and the client secret is what your service uses to tell WNS that it’s allowed to send notifications for your app. Again, these should only be stored in the service.

Note that Step 4 in How to authenticate with the Windows Push Notification Service (WNS), “Send the cloud server's credentials to WNS,” is something you do only when your service sends a push notification. We’ll come back to that shortly, because at this stage your service lacks the key piece that it needs to send a notification, namely a channel URI.

Obtaining and refreshing channel URIs

The client app obtains channel URIs at runtime through the Windows.Networking.PushNotifications.PushNotificationChannelManager object. This object has only two methods:

createPushNotificationChannelForApplicationAsync: creates a channel URI for the app’s primary tile as well as toasts and raw notifications.
createPushNotificationChannelForSecondaryTileAsync: creates a channel URI for a specific secondary tile identified by a tileId argument.

The result of both async operations is a PushNotificationChannel object. This object contains the channel URI in its Uri property, along with an ExpirationTime to indicate the deadline for refreshing that channel. A Close method specifically terminates the channel if needed, and most importantly is the PushNotificationReceived event, which is again what’s fired when the app is in the foreground and a push notification is received through this channel.

The lifetime of a channel URI is 30 days, after which WNS rejects any requests made for that channel. App code thus needs to refresh those URIs with the create methods above at least once every 30 days and send those URIs to its service. Here’s a good strategy:

On first launch, request a channel URI and save the string in the Uri property in your local app data. Because channel URIs are specific to a device, do not store them in your roaming app data.
On subsequent launches, request a channel URI again and compare it to the one previously saved. If it’s different, send it to the service, or send it and let the service replace an older one if necessary.
Also perform the previous step in your app’s Resuming handler (see Launching, resuming, and multitasking in the docs), because it’s possible that the app might have been suspended for more than 30 days.
If you’re concerned the app won’t be run within 30 days, implement a background task with a maintenance trigger to run every few days or once a week. For details, refer again to Being productive in the background—background tasks; the background task in this case will just execute the same code as the app to request a channel and send it to your service.

Sending channel URIs to the service

Typically, push notification channels work with user-specific updates like email status, instant messages, and other personalized information. It’s unlikely that your service will need to broadcast the same notification to every user and/or every tile. For this reason, the service needs to associate each channel URI with more specific information. For an email app, the user’s id is paramount, as that would specify the account to check. A weather app, on the other hand, would likely associate each channel URI with a specific latitude and longitude, such that each tile (primary and secondary) would reflect a distinct location.

The app, then, must include these details when it sends a channel URI to its service, and the service must store them for later use.

Where user identity is concerned, it’s best for the app to authenticate the user with the service separately, using service-specific credentials or through an OAuth provider such as Facebook, Twitter, Google, or the user’s Microsoft Account (using OAuth is helpful with Windows Azure Mobile Services, as we’ll see later). If for some reason that’s not possible, be sure to encrypt any user id you send to the service or make sure to send it over HTTPS.

Whatever the case, how you send all this information to your service (in headers, through data in the message body, or as parameters on the service URI) is up to you. This part of the communication is strictly between the app and its service.

As a simple example, let’s say we have a service with a page called receiveuri.aspx (as we’ll see in the next section), the full address of which is in a variable called url. The following code requests a primary channel URI from Windows for the app and posts it to that page via HTTP. (This code derived and simplified from the Push and periodic notifications client side sample where the itemId variable, defined elsewhere, is used to identify secondary tiles; the sample also has a C++ variant, not shown here):

JavaScript:

Windows.Networking.PushNotifications.PushNotificationChannelManager
    .createPushNotificationChannelForApplicationAsync()
    .done(function (channel) {
        //Typically save the channel URI to appdata here.
        WinJS.xhr({ type: "POST", url:url,
            headers: { "Content-Type": "application/x-www-form-urlencoded" },
            data: "channelUri=" + encodeURIComponent(channel.uri) 
                + "&itemId=" + encodeURIComponent(itemId)
        }).done(function (request) {
            //Typically update the channel URI in app data here.
        }, function (e) {
            //Error handler
        });
    });

C#:

using Windows.Networking.PushNotifications;

PushNotificationChannel channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
HttpWebRequest webRequest = (HttpWebRequest)HttpWebRequest.Create(url);
webRequest.Method = "POST";
webRequest.ContentType = "application/x-www-form-urlencoded";
byte[] channelUriInBytes = Encoding.UTF8.GetBytes("ChannelUri=" + WebUtility.UrlEncode(newChannel.Uri) + "&ItemId=" + WebUtility.UrlEncode(itemId));

Task<Stream> requestTask = webRequest.GetRequestStreamAsync();
using (Stream requestStream = requestTask.Result)
{
    requestStream.Write(channelUriInBytes, 0, channelUriInBytes.Length);
}

The following ASP.NET code is a basic implementation of a receiveuri.aspx page that processes this HTTP POST, making sure it received a valid channel URI, a user, and some identifier for the item.

I emphasize the “basic” nature of this code because, as you can see, the SaveChannel function simply writes the contents of the request into a fixed text file, which clearly won’t scale beyond a single user! A real service, of course, would employ a database for this purpose, but the structure here will be similar.

<%@ Page Language="C#" AutoEventWireup="true" %>

<script runat="server">

protected void Page_Load(object sender, EventArgs e)
{
    //Output page header
    Response.Write("<!DOCTYPE html>\n<head>\n<title>Register Channel URI</title>\n</head>\n<html>\n<body>");
    
    //If called with HTTP GET (as from a browser), just show a message.
    if (Request.HttpMethod == "GET")
    {
        Response.StatusCode = 400;
        Response.Write("<p>This page is set up to receive channel URIs from a push notification client app.</p>");
        Response.Write("</body></html>");
        return;
    }

    if (Request.HttpMethod != "POST") {
        Response.StatusCode = 400;
        Response.Status = "400 This page only accepts POSTs.";
        Response.Write("<p>This page only accepts POSTs.</p>");
        Response.Write("</body></html>");        
        return;
    }
    
    //Otherwise assume a POST and check for parameters    
    try
    {
        //channelUri and itemId are the values posted from the Push and Periodic Notifications Sample in the Windows 8 SDK
        if (Request.Params["channelUri"] != null && Request.Params["itemId"] != null)
        {
            // Obtain the values, along with the user string
            string uri = Request.Params["channelUri"];
            string itemId = Request.Params["itemId"];
            string user = Request.Params["LOGON_USER"];
                 
            //TODO: validate the parameters and return 400 if not.
            
            //Output in response
            Response.Write("<p>Saved channel data:</p><p>channelUri = " + uri + "<br/>" + "itemId = " + itemId + "user = " + user + "</p>");

            //The service should save the URI and itemId here, along with any other unique data from the app such as the user;
            SaveChannel(uri, itemId, user);

            Response.Write("</body></html>");
        }
    }
    catch (Exception ex)
    {
        Trace.Write(ex.Message);
        Response.StatusCode = 500;
        Response.StatusDescription = ex.Message; 
        Response.End();
    }
}
</script>

protected void SaveChannel(String uri, String itemId, String user)
{
    //Typically this would be saved to a database of some kind; to keep this demonstration very simple, we'll just use
    //the complete hack of writing the data to a file, paying no heed to overwriting previous data.
    
    //If running in the debugger on localhost, this will save to the project folder
    string saveLocation = Server.MapPath(".") + "\\" + "channeldata_aspx.txt";
    string data = uri + "~" + itemId + "~" + user;

    System.Text.ASCIIEncoding encoding = new System.Text.ASCIIEncoding();
    byte[] dataBytes = encoding.GetBytes(data);

    using (System.IO.FileStream fs = new System.IO.FileStream(saveLocation, System.IO.FileMode.Create))
    {
        fs.Write(dataBytes, 0, data.Length);
    }

    return;
}

The code for this service can be found in Chapter 13 of my free ebook, Programming Windows 8 Apps in HTML, CSS, and JavaScript, specifically in the HelloTiles sample of the companion content. It’s designed to work with the client-side SDK sample referenced earlier. If you run HelloTiles in the debugger (Visual Studio 2012 Ultimate or Visual Studio Express 2012 for Web) with the localhost enabled, you’ll have URL like http://localhost:52568/HelloTiles/receiveuri.aspx that you can paste into the client-side SDK sample. When the sample then makes a request to that URL, you’ll stop on any breakpoints in the service and can step through the code.

Sending the notification

In a real service, you’ll have some kind of ongoing process that monitors its data sources and sends push notifications to specific users when appropriate. This might happen in a number of ways:

A scheduled job can check for weather alerts for a specific location perhaps once every 15-30 minutes, depending on how often those alerts are issued, and issue push notifications in response.
Another service, like a messaging back-end, might make a request to a page on your server when a new message is available. That page can then issue appropriate notification.
Users might be interacting with webpages on your server, and their activities trigger push notifications to specific channels.

In short, there are a number of triggers for push notifications, depending entirely on the nature of your back-end service or website. For the purposes of this article, the same HelloTiles sample service from Chapter 13 of Programming Windows 8 Apps in HTML, CSS, and JavaScript has a page called sendBadgeToWNS.aspx that sends a push notification whenever you visit that page in a browser, using whatever channel URI was saved in the text file earlier. A real service performs some kind of database lookup to obtain channel URIs instead of reading the contents of a file, but again the overall structure is very similar.

ASP.NET Page:

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="sendBadgeToWNS.aspx.cs" Inherits="sendBadgeToWNS" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">    
    <title>Send WNS Update</title>
</head>
<body>
    <p>Sending badge update to WNS</p>    
</body>
</html>

C# code-behind:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Net;
using System.IO;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Json;
using System.Text;

public partial class sendBadgeToWNS : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        //Load our data that was previously saved. A real service would do a database lookup here
        //with user- or tile-specific criteria.
        string loadLocation = Server.MapPath(".") + "\\" + "channeldata_aspx.txt
        byte[] dataBytes;
        
        using (System.IO.FileStream fs = new System.IO.FileStream(loadLocation, System.IO.FileMode.Open))
        {
            dataBytes = new byte[fs.Length];
            fs.Read(dataBytes, 0, dataBytes.Length);
        }

        if (dataBytes.Length == 0)
        {
            return;
        }
        
        System.Text.ASCIIEncoding encoding = new System.Text.ASCIIEncoding();

        string data = encoding.GetString(dataBytes);
        string[] values = data.Split(new Char[] { '~' });
        string uri = values[0]; //Channel URI
        string secret = "9ttsZT0JgHAFveYahK1B6jQbvMOIWYbm";
        string sid = "ms-app://s-1-15-2-2676450768-845737348-110814325-22306146-1119600341-293560589-2707026538";
        
        //Create some simple XML for a badge update
        string xml = "<?xml version=\"1.0\" encoding=\"utf-8\" ?>";
        xml += "<badge value='alert'/>";
                    
        PostToWns(secret, sid, uri, xml, "wns/badge");
    }
}

All we’re doing here is retrieving the channel URI, building the XML payload, and then authenticating with WNS and doing an HTTP POST to that channel URI. The last two steps are done in the PostToWns function that comes from the QuickStart: Sending a push notification topic on the Windows Developer Center. I’m omitting a full listing because the bulk of it is just authenticating with WNS via OAuth (at https://login.live.com/accesstoken.srf) using your client secret and SID from the Windows Store. The result of this authentication is an access token that’s then included in the HTTP POST we send to the channel URI:

C#:

public string PostToWns(string secret, string sid, string uri, string xml, string type = "wns/badge")
{
    try
    {
        // You should cache this access token
        var accessToken = GetAccessToken(secret, sid);

        byte[] contentInBytes = Encoding.UTF8.GetBytes(xml);

        // uri is the channel URI
        HttpWebRequest request = HttpWebRequest.Create(uri) as HttpWebRequest;
        request.Method = "POST";
        request.Headers.Add("X-WNS-Type", type);
        request.Headers.Add("Authorization", String.Format("Bearer {0}", accessToken.AccessToken));

        using (Stream requestStream = request.GetRequestStream())
            requestStream.Write(contentInBytes, 0, contentInBytes.Length);

        using (HttpWebResponse webResponse = (HttpWebResponse)request.GetResponse())
            return webResponse.StatusCode.ToString();
    }
    catch (WebException webException)
    {
        // Implements a maximum retry policy (omitted)
    }
}

In this example, note that the X-WNS-Type header in the HTTP request is set to wns/badge and the Content-Type header defaults to text/xml. For tiles, the type should be wns/tile; toasts use wns/toast. With raw notifications, use the type wns/raw and set Content-Type to application/octet-stream. For full details on headers, refer to the Push notification service request and response headers page in the documentation.

Push notification failures

Of course, sending an HTTP request like this might not always work, and there are a number of reasons why WNS will respond with something other than a 200 code (success). For specific details, see the “Response code” section of the Push notification service request and response headers; here are the more common errors and causes:

The channel URI is invalid (404 Not Found) or expired (410 Gone). In these cases the service should remove the channel URI from its database and not make any further requests to it.
The client secret and SID might be invalid (401 Unauthorized) or there’s a mismatch between the app’s package ID in its manifest and the one in the Windows Store (403 Forbidden). The best way to ensure that these match is to use the Store > Associate App with Store menu command in Visual Studio (this command is found on the Project menu in Visual Studio 2012 Ultimate).
The raw notification payload is over 5KB (413 Request Entity Too Large).
The client could be offline, in which case WNS will automatically try again, but eventually report a failure. For XML notifications, the default behavior is that push notifications are cached and delivered when the client comes back online. For raw notifications, caching is disabled by default; you can change this by setting the X-WNS-Cache-Policy header to cache in the request to the channel URI.

For other errors (400 Bad Request), make sure that XML payloads contain UTF-8 encoded text, and that raw notifications are in base64 with the Content-Type header set to application/octet-stream. It’s also possible that WNS is throttling delivery because you’re simply trying to send too many push notifications within a specific time period.

A raw push notification might also be rejected if the app isn’t present on the lock screen and the device is in connected standby. Because Windows blocks raw notifications to non-lock screen apps in this state (and anytime the app isn’t in the foreground), WNS has optimizations to drop notifications that it knows won’t be delivered.

Windows Azure Mobile Services

Now that we’ve gone through the intricate details of working with push notifications, even omitting the question of storage, you’re probably wondering, “Is there any way to make all this simpler?” Just imagine what it would take to manage potentially thousands or millions of channel URIs for a hopefully large and expanding customer base!

Fortunately, you’re not the first to ask such questions. Besides third-party solutions such as those offered by Urban Airship, Windows Azure Mobile Services can make your life a whole lot easier.

Windows Azure Mobile Services, which I’ll just abbreviate as AMS, provides a pre-built solution (basically a number of REST endpoints) for most of the service details we’ve been discussing. A “mobile service” is basically one that manages a database on your behalf and provides library functions to easily send payloads to WNS. An introduction to AMS can be found on Add cloud to your app with Windows Azure Mobile Services.

For push notifications in particular, first obtain the client-side library in the Windows Azure Mobile Services SDK for Windows 8. Then refer to Get started with push notifications in Mobile Services (note that there’s a JavaScript version of the topic too), which describes how AMS helps you fulfill all the wiring requirements we saw earlier:

App registration with the Windows Store: Once you obtain the client secret and SID for your app from the Windows Store, save those values in the mobile service configuration. See the “Register your app for the Windows Store” section in the Get started topic just mentioned.
Obtaining and refreshing channel URIs: requesting and managing channel URIs in the app is purely a client-side concern, and is the same as before.
Sending channel URIs to the service: this step becomes far easier with AMS. First you create a database table in the mobile service (through the Windows Azure portal). Then the app can simply insert records into that table with channel URIs and any other key information you need to attach. The AMS client library takes care of the HTTP request behind the scenes, and even updates the client-side record with any changes made on the server. Furthermore, AMS can automatically handle authentication through the user’s Microsoft Account or through three other OAuth providers—Facebook, Twitter, or Google—if you’ve registered your app with one of them. See Get started with authentication in Mobile Services.
Sending the notification: within the mobile service, you can attach scripts (written in the variant of JavaScript known as Node.js) to database operations, and also created scheduled jobs in JavaScript. In these scripts, a simple call to the push.wns object with a channel URI and a payload generates the necessary HTTP request to the channel. It’s also a simple matter to capture push failures and record the response with console.log. Those logs are easily reviewed on the Windows Azure portal.

For extensive details, see these two sample tutorials: Tile, Toast, and Badge Push Notifications using Windows Azure Mobile Services and Raw Notifications using Windows Azure Mobile Services. Here, instead of repeating all those instructions, let’s review a few of the highlights.

When you set up a mobile service, it will have a specific service URL. This is what you use when creating an instance of the MobileServiceClient object in the AMS SDK:

JavaScript:

var mobileService = new Microsoft.WindowsAzure.MobileServices.MobileServiceClient(
    "https://{mobile-service-url}.azure-mobile.net/",
    "{mobile-service-key}");

C#:

using Microsoft.WindowsAzure.MobileServices;

MobileServiceClient MobileService = new MobileServiceClient(
    "https://{mobile-service-url}.azure-mobile.net/",
    "{mobile-service-key}");

C++ (taken from an additional sample):

using namespace Microsoft::WindowsAzure::MobileServices;

auto MobileService = ref new MobileServiceClient(
    ref new Uri(L" https://{mobile-service-url}.azure-mobile.net/"), 
    ref new String(L"{mobile-service-key}"));

This class encapsulates all the HTTP communication with the service, relieving you from all that low-level plumbing that you probably don’t want to think about.

To authenticate with a particular OAuth provider, use the login or LoginAsync method, the result of which is a User object that provides that information to the app. (Once authenticated, CurrentUser property of the client object will also contain the user id.) When you authenticate the mobile service directly like this, the service will have access to the user id and there’s no need for the client to send it explicitly:

JavaScript:

mobileService.login("facebook").done(function (user) { /* ... */ });
mobileService.login("twitter").done(function (user) { /* ... */ });
mobileService.login("google").done(function (user) { /* ... */ });
mobileService.login("microsoftaccount").done(function (user) { /* ... */ });

C#:

MobileServiceUser user = await MobileService.LoginAsync(MobileServiceAuthenticationProvider.Facebook);
MobileServiceUser user = await MobileService.LoginAsync(MobileServiceAuthenticationProvider.Twitter);
MobileServiceUser user = await MobileService.LoginAsync(MobileServiceAuthenticationProvider.Google);
MobileServiceUser user = await MobileService.LoginAsync(MobileServiceAuthenticationProvider.MicrosoftAccount);

C++:

task<MobileServiceUser^> (MobileService->LoginAsync(MobileServiceAuthenticationProvider::Facebook))
    .then([this](MobileServiceUser^ user) { /* */ } );
task<MobileServiceUser^> (MobileService->LoginAsync(MobileServiceAuthenticationProvider::Twitter))
    .then([this](MobileServiceUser^ user) { /* */ } );
task<MobileServiceUser^> (MobileService->LoginAsync(MobileServiceAuthenticationProvider::Google))
    .then([this](MobileServiceUser^ user) { /* */ } );
task<MobileServiceUser^> (MobileService->LoginAsync(MobileServiceAuthenticationProvider::MicrosoftAccount))
    .then([this](MobileServiceUser^ user) { /* */ } );

Sending a channel URI to the service is again a simple matter of storing a record in the service’s database, and the client object makes the HTTP requests. To do this, just request the database object and insert the record as shown in the examples below from the push notification tutorial sample linked earlier. In each code snippet, assume that ch contains the PushNotificationChannel object from the WinRT APIs. You can also include any other properties in the channel object that’s built up, such as a secondary tile id or other data that identifies the channel’s purpose.

JavaScript:

var channelTable = MobileServicesSample.mobileService.getTable('Channels');

var channel = {
    uri: ch.uri, 
    expirationTime: ch.expirationTime.
};

channelTable.insert(channel).done(function (item) {

    },
    function () {
        // Error on the insertion.
    });
}

C#:

var channel = new Channel { Uri = ch.Uri, ExpirationTime = ch.ExpirationTime };
var channelTable = privateClient.GetTable<Channel>();

if (ApplicationData.Current.LocalSettings.Values["ChannelId"] == null)
{
    // Use try/catch block here to handle exceptions
    await channelTable.InsertAsync(channel);
}

C++:

auto channel = ref new JsonObject();
channel->Insert(L"Uri", JsonValue::CreateStringValue(ch->Uri));
channel->Insert(L"ExpirationTime", JsonValue::CreateBooleanValue(ch->ExpirationTime));

auto table = MobileService->GetTable("Channel");
task<IJsonValue^> (table->InsertAsync(channel))
    .then([this, item](IJsonValue^ V) { /* ... */ });

Note that once the channel record has been inserted, any changes or additions that the service might have made to that record will be reflected in the client.

In addition, if you misspell the name of the database in the GetTable/getTable call, you won’t see any exceptions until you try to insert a record. This can be a hard bug to track down, so if you’re convinced everything should be working, but it isn’t, check that database name.

Now again, these insertions on the client side are translated into HTTP requests to the service, but even on the service side this is also hidden from you. Instead of receiving and processing the requests, you attach custom scripts to each database operation (insert, read, update, and delete).

These scripts are written as JavaScript functions using the same intrinsic objects and methods that are available in Node.js (all of which has nothing whatsoever to do with any client-side JavaScript in the app). Each function receives appropriate parameters: insert and update receive the new record, delete receives the id of the item, and read receives a query. All the functions also receive a user object, if the app authenticated the user with the mobile service, and a request object that lets you execute the operation and generate what becomes the HTTP response.

The simplest (and default) insert script, just executes the request and inserts the record, item, as-is:

function insert(item, user, request) {
    request.execute();
}

If you want to attach a timestamp and the user id to the record, it’s as easy as adding those properties to the item parameter prior to executing the request:

function insert(item, user, request) {
    item.user = user.userId;
    item.createdAt = new Date();
    request.execute();
}

Note that the changes made to item in these scripts before insertion into the database are automatically propagated back to the client. In the code above, the channel object in the client would contain user and createdAt properties once the insertion succeeds. Very convenient!

The service scripts can also perform additional actions after request.execute, especially in response to success or failure, but I’ll leave such details to the Server script example how tos documentation.

To return now to push notifications, saving channel URIs into a table is just one part of the equation, and the service may or may not send notifications in response to this particular event. It’s more likely that the service will have other tables with additional information, where operations performed on those tables trigger notifications to some subset of channel URIs. We’ll discuss a few examples in the next section. Whatever the case may be, you send a push notification from a script using the push.wns object. This again has many methods to send specific types of updates (including raw), where tiles, toasts, and badges work directly through names methods that match the available templates. For example:

push.wns.sendTileSquarePeekImageAndText02(channel.uri, {
    image1src: baseImageUrl + "image1.png",
    text1: "Notification Received",
    text2: item.text
}, {
    success: function (pushResponse) {
        console.log("Sent Tile Square:", pushResponse);
    },
    error: function (err) {
        console.log("Error sending tile:", err);
    }

});

push.wns.sendToastImageAndText02(channel.uri, {
    image1src: baseImageUrl + "image2.png",
    text1: "Notification Received",
    text2: item.text
}, {
    success: function (pushResponse) {
        console.log("Sent Toast:", pushResponse);
    }
});

push.wns.sendBadge(channel.uri, {
    value: value,
    text1: "Notification Received"
}, {
    success: function (pushResponse) {
        console.log("Sent Badge:", pushResponse);
    }
});

Again, the console.log function creates an entry in the logs that you can view on the Azure Mobile Services portal, and you’ll typically want to include log calls in error handlers as shown with the tile notification above.

You might have noticed that the send* methods are each tied to a specific template, and for tiles it means that wide and square payloads must be sent separately as two notifications. Remember that you almost always want to send both sizes together because the user controls how that tile appears on their Start screen. With the template specific send functions of push.wns, then, it means making two sequential calls each of which generate a separate push notification.

To combine multiple updates, which includes sending multiple tile updates with different tags at one time or sending multiple toasts, use the push.wns.sendTile and push.wns.sendToast methods. For example:

var channel = '{channel_url}';

push.wns.sendTile(channel,
    { type: 'TileSquareText04', text1: 'Hello' },
    { type: 'TileWideText09', text1: 'Hello', text2: 'How are you?' },
    { client_id: '{your Package Security Identifier}', client_secret: '{your Client Secret}' },

    function (error, result) {
        // ...
    });

On an even lower level, push.wns.send lets you be very exact with the notification contents; push.wns.sendRaw is also there for raw notifications. For all the details, refer again to the push.wns object documentation.

Real-world scenarios with Windows Azure Mobile Services

The sample app in the Tile, Toast, and Badge Push Notifications using Windows Azure Mobile Services shows how to send push notifications in response to a new message being inserted into a database table. However, this means that the app ends up sending a push notification to itself, which it wouldn’t typically need to do (except perhaps to send notifications to the same app on the user’s other devices).

What’s more likely to happen is that the service will send push notifications in response to events that occur outside the app/tile that ultimately receives those notifications. Consider a few scenarios:

Using Social Networks:

Apps can employ a user’s social network to implement features like issuing challenges to one’s friends. For example, when one user sets a new high score in a game, you might want to issue challenges via tile updates or toasts to the user’s friends who also have that game installed. The same thing can happen in fitness apps where you might be posting a new best time for a certain kind of activity.

To do this, the app can insert a new record into an appropriate mobile service table (Scores, BestTimes, etc.). Within the insert script, the service queries its database for appropriate friends of the current user, then sends notifications to those channel URIs. Additional query criteria describe the exact aspect of a game, the particular kind of exercise (for secondary tiles), and so on.

Weather updates and alerts:

Weather apps typically allow you to assign a location to the app’s primary tile and to create secondary tiles for additional locations. The important information with each tile is the latitude and longitude of the location, which the app sends to the service along with each channel URI (by inserting into a table). To trigger an update to that channel, the service might have another process (such as a scheduled job described below) that periodically queries a central weather service for updates and alerts, and then processes those responses and inserts the appropriate messages into an alerts table in the mobile service. The insert script then retrieves appropriate channel URIs and sends the updates. Alternately, if a weather service itself allows you to register for alerts or periodic updates, another page in the service would receive those requests (HTTP PUTs, most likely), process them, and invoke the mobile service to insert a record, thus triggering an update.

Messaging:

Handling instant messaging happens very much in the same way as receiving weather updates. Again, another process monitors the receipt of new messages, such as one that checks the incoming messages periodically, or registers with the message source for alerts when new messages arrive. In either case, the arrival of a new message triggers push notifications to the appropriate channels. In this case the channel URIs is associated with a user’s tile for a particular kind of messaging. You’d likely use raw notifications in this case, as it’s similar to the email scenario described at the beginning of this post.

In all of these scenarios, note that it’s not actually necessary to insert anything into a database table at all. If you don’t call request.execute in the insertion script, nothing ends up in the database, yet you can still perform other tasks within that script such as sending notifications. In other words, there’s no need to fill up a database with records that you aren’t going to use later on, especially because storing data incurs costs.

Note too that Azure Mobile Services has a facility for scheduling jobs, which you can read about on Schedule recurring jobs in Mobile Services. Such jobs could routinely retrieve data from other services, process it, and insert records into the service’s database, again triggering push notifications. Likewise, as we pointed out in Part 2 of this series, other webpages and mobile apps can also make changes to that database and trigger push notifications. The database scripts in the mobile service will run in all of these cases.

In closing

To wrap up this series, then, we’ve explored the whole scope of what “alive with activity” means-for users, for developers, for apps, and for services. We’ve seen the capabilities of tile, badge, and toast updates, how to set up periodic notifications, how to use background tasks as part of this process, and the structure of services to handle periodic and push notifications. And clearly, Windows Azure Mobile Services provides a much higher-level view of the whole process of working with push notifications. It can certainly help you be much more productive—and save you many headaches, most likely!—than writing new services from scratch.

Kraig Brockschmidt
Program Manager, Windows Ecosystem Team
Author, Programming Windows 8 Apps in HTML, CSS, and JavaScript

Alive with activity, part 2: Writing and debugging services for live tiles

Windows 8 Team — Mon, 04 Mar 2013 18:00:00 GMT

In Part 1 of this series we explored the nature of tile updates, badge updates, and toast notifications that bring a sense of “aliveness” to the overall user experience of Windows 8. In particular, we saw how these notifications are composed with XML payloads that are then issued locally, from a running app or a background task, or can be supplied upon request by an online service.

Generating an XML payload and issuing it from a running app is something you can easily develop and debug within an app using Visual Studio Ultimate 2012 or Visual Studio Express 2012 for Windows 8. The App tiles and badges sample, Secondary tiles sample, and the Scheduled notifications sample, give you everything you need here.

What takes a little more effort is developing and debugging a web service to support periodic updates as well as push notifications. The client side of these stories is well-demonstrated in the Push and periodic notifications client-side sample, but in order to make use of that sample at all you need some services to work with! In this post, we’ll specifically explore how to develop services that support periodic notifications for tile and badge updates, with a focus on using Visual Studio tools and the localhost to debug your services before deploying them to a production environment. We’ll also begin to explore how you can use Windows Azure Mobile Services for this purpose, which are also very helpful in supporting push notifications as we’ll see in Part 3.

The basic nature of services

What does a service that supports periodic tile and badge updates actually do? Let’s begin by reviewing what we mean by a “service,” because that word is often rather intimidating for developers who have primarily been focused on client apps.

In the simplest terms, a service is some piece of code sitting on some web server that runs on that server whenever an HTTP request is made to it. HTML pages (.htm or .html) are not like this: as there’s no server-side code involved, the server simply returns that page’s text and all processing is done on the client (including running any client-side script contained in that page). However, if you have URIs to pages that end with php, asp, aspx, cgi, cshtml, or any number of other server-side extensions, you’re effectively talking to a “service” in this most general sense.

A service is responsible to receive a client HTTP request, process whatever arguments might be included with the URI, and return an appropriate text response. For web pages written with technologies like PHP or ASP.NET, the response should be in the form of HTML. Services that implement web APIs, such as those of Facebook and Twitter (and thousands of others!), typically accept any number of parameters in URI query strings (or in the request header), and return either XML or JSON data in response. (And just to note, we’re talking here of services built on representational state transfer, or REST, rather than those build on other protocols like SOAP, as REST the most common among services today.)

Thus a service that provides periodic tile and/or badge updates is simply one that exists at whatever URI an app gives to Windows for this purpose, and which responds to HTTP requests with an appropriate XML payload. That payload contains elements that correspond to any supported template, where images are referenced with other URIs (inline encoding is not supported). The specific information included in the payload can also come from any source, as we’ll discuss in a bit.

Regardless of such details, however, all such services share a similar structure that receives and processes the request, and constructs the XML response. Let’s now look at how to create that basic structure.

Writing services

To write and debug services you can use whatever tools you want as long as they support your chosen server-side language. Here we’ll focus on Visual Studio, specifically Visual Studio Ultimate 2012 and Visual Studio Express 2012 for Web, the latter of which is available for free alongside its Windows partner that you already know. To install it, run the Web Platform Installer through which you can also install a variety of other related technologies such as PHP and WebMatrix. This allows you to create services in a variety of languages.

As a very simple example, the following code comprises a complete PHP service that responds with a badge update XML payload in which the badge value is set to the current day of the month (according to the server, mind you!). It comes from the HelloTiles sample site that’s included in Chapter 13 of my free ebook, Programming Windows 8 Apps with HTML, CSS, and JavaScript:

<?php
    echo '&lt;?xml version="1.0" encoding="utf-8" ?>';
    echo "<badge value='".date("j")."'/>";
?>

You can try this service directly. Click this link on the Windows Azure site I set up for this purpose--http://programmingwin8-js-ch13-hellotiles.azurewebsites.net/dayofmonhservice.php--and you’ll see that the XML that comes back is something like this:

<?xml version="1.0" encoding="UTF-8"?>
<badge value="24"/>

Try this same URI in the Push and periodic notifications client-side sample, scenario 5, “Polling for badge updates.” When you first run the app (within Visual Studio Express for Windows), its tile appears on the start screen as follows:

Now enter the URI above into the text box in scenario 5, press the Start periodic updates button, and, assuming you have network connectivity, you’ll soon see a numerical badge appear on the sample’s tile:

Note that Windows tries to poll for an update as soon as the app starts periodic updates, then continues to poll at the specified interval thereafter.

For a fuller PHP example, see Creating a great tile experience, part 2, which shows more customization of a tile update. In that example, the hypothetical get_trucks_from_database function queries a database using a zip code that’s included in the URI’s query string parameters, then builds the XML response with the results of that query.

There’s much more the service could do along these lines. For example:

With the day-of-month PHP service above, the app could indicate its local time zone in the query string to get a more accurate date, because the server can easily be located in another time zone.
A weather service could use latitude and longitude values in the URI to retrieve current conditions for that location.
The service could generate images on the fly and store them on a web server, then insert appropriate URIs into the XML payload.
The service would send its own requests to other services to obtain additional data, customized with the query string parameters (more on this later).
If an app enables the queue for tile updates (see the EnableNotificationQueue method), it can specify up to five separate URIs to poll for periodic updates, as demonstrated in scenario 4 of the Push and periodic notifications client-side sample. The tile update queue will be populated with an update from each URI. Each one of those URIs, of course, can have its own query string for further customization such that the same service could accommodate all the requests itself.
An app could include a user id in the query string such that the service could query its data stores for the user’s workout history, their high scores in a game, news items from the feeds they’re registered, and so forth. In such cases, a user id could be personally-identifiable information (PII), so the app must respect privacy concerns. This means that the app should either encrypt the username in the query string or use https:// URIs.

Note: Windows doesn’t provide a means within the periodic update mechanism to authenticate the user with the service. That level of support can only be accomplished with push notifications (or in enterprise scenarios with the Enterprise Authentication capability declared in the manifest).

Services can be written with other technologies, of course. ASP.NET is a good choice because you can then employ the same Notifications Extensions Library (written in C#) that you can use in an app to easily generate well-structured XML payloads.

To walk through a quick example, consider the very basic WebMatrix service I created for the HelloTiles sample service in Chapter 13 of my book (see the companion content). This particular service just returns a fixed XML payload (with bindings for both square and wide tiles) and is structurally similar to the first ASP.NET example given in Creating a great tile experience, part 2:

@{
  //
  // This is where any other code would be placed to acquire the dynamic content
  // needed for the tile update. In this case we'll just return static XML to show
  // the structure of the service itself.
  // 
  var weekDay = DateTime.Now.DayOfWeek;
}
<?xml version="1.0" encoding="utf-8" ?>
<tile>
    <visual lang="en-US">
        <binding template="TileSquarePeekImageAndText02" branding="none">
            <image id="1" src="http://www.kraigbrockschmidt.com/images/Liam07.png"/>
            <text id="1">Liam--</text>
            <text id="2">Giddy on the day he learned to sit up!</text>
        </binding>
        <binding template="TileWideSmallImageAndText04" branding="none">
            <image id="1" src="http://www.kraigbrockschmidt.com/images/Liam08.png"/>
            <text id="1">This is Liam</text>
            <text id="2">Exploring the great outdoors!</text>
        </binding>
    </visual>
</tile>

This particular service is deployed to http://programmingwin8-js-ch13-hellotiles.azurewebsites.net/Default.cshtml if you want to give it a try in scenario 4 of the Push and periodic notifications client-side sample. In doing so, after a few seconds, you’ll see the following tile updates (wide on the left, and the two parts of the square peek tile on the right):

Let’s now write the same thing using the Notification Extensions Library. The first thing you’ll need to do is build a version of the library for your website as follows:

Go to the App tiles and badges sample and copy the Notifications Extensions folder from that project into a folder of your own. (You can also install the library from Visual Studio directly by right-clicking on a project, selecting Manage NuGet Packages… and searching for NotificationsExtensions.WinRT. However, this is meant to bring the library into an existing app project whereas we need to build a standalone DLL here.)
In Visual Studio Express for Windows, open the NotificationsExtensions.csproj file.
In Solution Explorer, right click the NotificationExtensions project, select Properties, and make the following changes:

In the Application settings, change the Output type to Class Library (a .dll). This is necessary to use the library with an ASP.NET site.
In the Build settings, change the Configuration to All Configurations, change the conditional compilation symbols to read NETFX_CORE; WINRT_NOT_PRESENT, and make sure XML documentation file is checked near the bottom of the page. The WINRT_NOT_PRESENT flag enables the library to compile without WinRT.

Select a Debug or Release target, then right-click the Notifications Extensions project, and select Build.

This should generate a DLL and associated files in that project folder. Now we need to pull it into a website project.

In Visual Studio Express for Web, right-click your website project and select Add > Add ASP.NET folder > Bin if your site doesn’t have a Bin folder already.
Right-click that Bin folder and select Add Reference…. In Add Reference, go to the bin\Debug or bin\Release folder of the Notifications Extensions project and select the DLL found there.

If you’re using Visual Studio Ultimate, you can add the Notification Extensions project to your website solution, if desired, as the tool can handle both project types. Just be sure you don’t deploy the source code for that project to your web server!

Also note that if you build your site to run it locally in a browser (as we’ll see in the Debugging section below), you might get an error about adding a reference to System.Runtime. To correct this, open the web.config file and change the compilation element to read as follows:

<compilation debug="true" targetFramework="4.0">
  <assemblies>
    <add assembly="System.Runtime, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> 
  </assemblies>
</compilation>

With all this in place, here’s a page (called DefaultNE.aspx) that produces the same output as the earlier hard-coded example:

<?xml version="1.0" encoding="utf-8" ?>
<%@ Page Language="C#" %>
<script runat="server">   1:  
   2:     public string GenerateTileXML()
   3:     {
   4:         // Construct the square template
   5:         NotificationsExtensions.TileContent.ITileSquarePeekImageAndText02 squareTile = 
   6:             NotificationsExtensions.TileContent.TileContentFactory.CreateTileSquarePeekImageAndText02();
   7:         squareTile.Branding = NotificationsExtensions.TileContent.TileBranding.None;        
   8:         squareTile.Image.Src = "http://www.kraigbrockschmidt.com/images/Liam07.png";
   9:         squareTile.TextHeading.Text = "Liam--";
  10:         squareTile.TextBodyWrap.Text = "Giddy on the day he learned to sit up!";
  11:         
  12:         // Construct the wide template
  13:         NotificationsExtensions.TileContent.ITileWideSmallImageAndText04 wideTile =
  14:             NotificationsExtensions.TileContent.TileContentFactory.CreateTileWideSmallImageAndText04();
  15:         wideTile.Branding = NotificationsExtensions.TileContent.TileBranding.None;
  16:         wideTile.Image.Src = "http://www.kraigbrockschmidt.com/images/Liam08.png";
  17:         wideTile.TextHeading.Text = "This is Liam";
  18:         wideTile.TextBodyWrap.Text = "Exploring the great outdoors!";
  19:                 
  20:         // Attach the square template to the notification
  21:         wideTile.SquareContent = squareTile;
  22:         wideTile.Lang = "en-US";
  23:         
  24:         // The wideTile object is an XMLDOM object, suitable for issuing tile updates
  25:         // directly. In this case we just want the XML text.
  26:         return wideTile.ToString();        
  27:     }
</script>
<%   1:  = GenerateTileXML() 
%>

You can visit this service at http://programmingwin8-js-ch13-hellotiles.azurewebsites.net/DefaultNE.aspx, from which you’ll get essentially the same XML back as before, with very minor differences. Pasting the URI into scenario 4 of the Push and periodic notifications client-side sample will also generate the same tile updates as before.

Debugging services

Generating a successful tile or badge update assumes, of course, that the XML in the service’s response is properly formed: Windows rejects any XML that isn’t. This is a good reason to use the Notifications Extensions Library as it greatly reduces the errors you might otherwise make in the process.

But what if your service isn’t working well at all? How you can diagnose and debug how it’s handling requests and generating its response?

In fact, when I first tried the ASP.NET service code above, the updates didn’t appear because there was a leading newline at the top of the XML response. This is specifically why the <?xml ?> header appears as the first line in the file rather than after the <%@ Page %> directive, and why there aren’t any extra line feeds.

Clearly, there are many reasons why you’ll want to be able to step through your service code and debug it line by line, especially if you’re querying a database and processing those query results.

The trick to doing this is to use the localhost on your development machine, which allows you to run and debug your service locally at the same time you’re running client test code such as the SDK samples.

Having a localhost means you’re running a local web server like Internet Information Services or Apache. To turn on IIS in Windows (its built-in), go to Control Panel > Turn Windows features on or off. Check the Internet Information Services box at the top level, as shown below, to install the core features:

After IIS is installed, the local site addressed by http://localhost/ is found in the folder c:\inetpub\wwwroot. That’s where you drop something like the PHP page described in the last section so that you can use a URI like http://localhost/dayofmonthservice.php in the client samples.

To use PHP with IIS, you might need to install it through Microsoft’s Web platform installer or the server-side code won’t execute properly. After PHP installation, try entering a URI for a local PHP page in your browser. If you get an error message that says “Handler PHP53_via_FastCGI has a bad module�� (yeah, that’s really helpful!), return to the Turn Windows features on or off dialog shown earlier, go to Internet Information Services > World Wide Web Services > Application Development Features, check the box for CGI, and press OK. After the CGI engine is installed, your PHP page should work.

With your localhost in place, you can then debug services on your own machine using Visual Studio Express for Web or Visual Studio Ultimate. You can also use Visual Studio Express for Web alongside Visual Studio Express for Windows to debug client and server code together.

When you run a service or website in the Visual Studio (for Web) debugger, it runs in the browser at a URL like http://localhost:<port>/ where <port> is randomly assigned for that project. For example, when I run the DefaultNE.aspx page from the previous section in Visual Studio Express for Web, that page opens in Internet Explorer with the URI of http://localhost:52568/HelloTiles/DefaultNE.aspx. If I’ve set a breakpoint in that page’s code, the debugger immediately stops at that point.

Breakpoints are also hit if you use that same localhost URI in client code to initiate requests. So, for example, if I’m running the Push and periodic notifications client side sample in Visual Studio Express for Windows and paste the URI into scenario 4, Visual Studio Express for Web will stop my service in the debugger as soon as Windows makes a request. I can then step through that code (Windows is fortunately patient) and make sure the right response is being generated. If not, I can fix the code and restart the service on the localhost.

When you’re confident that your service is operating as intended, you can then upload it to your live web host (or staging environment) and do your final production testing.

Note that it’s not necessary to run client code in a debugger to use the localhost in this way. If you do, however, there’s an option in Visual Studio that must be turned on for localhost to work. It’s checked by default, but if you need to change it, you’ll find it in you project properties under Debugging > Allow Local Network Loopback:

Data from external sources

In addition to querying its own database, it’s entirely possible for a periodic notification service to send requests to other services to obtain data for its response. The caveat, however, is that such requests are asynchronous in nature and are prone to a variety of failure conditions. As such, using them can greatly complicate the implementation of your service.

To simplify matters, we can take advantage of the fact that Windows only makes requests to your service at 30-minute or longer intervals, as enforced by the client API. This means you have lots of time during which other server-side processes can make external requests to monitor weather alerts, leaderboards, RSS feeds, and just about anything else for which there’s a web API. Those processes store results in your database, which are then ready for your periodic notification service to query (synchronously) when it receives its next request.

Indeed, any number of agents can update the same database. For example, users might be entering data through your website. They might be using mobile phone apps to track their activities, with results being automatically uploaded to a database. The database might also be getting updated by friends who are using the same app on their individual devices.

Such an arrangement is shown below, where the database serves as the central store for your back-end state and the periodic notification service acts only as a simple consumer of that state.

Using Windows Azure Mobile Services with periodic update services

As you begin to understand and build out back-end services to support live tiles and other notifications, you really owe it to yourself to explore Windows Azure Mobile Services, which I’ll refer to as AMS for short. In addition to greatly simplifying push notifications, as we’ll see in Part 3 of this series, AMS can be used to support periodic updates services in several ways:

In a mobile service you can create scheduled background jobs that can make requests to other services and store the results in your database. An example of this, to obtain tweets from Twitter, can be found on the Schedule recurring jobs in Mobile Services topic.
When you create a SQL Server database in AMS (or elsewhere in Windows Azure), that database is accessible like any other web-hosted SQL Server database, so you can use it from websites and other services, including those written in PHP.
AMS makes it very easy to insert records into a database from a client app, using the Mobile Services SDK.
Separate from mobile services, Windows Azure can host server-side processes written in a variety of languages, including Node.js, Python, Java, PHP, and .NET.

In the future, also watch for a new feature called “service operations” In Azure Mobile Services, through which you will be able to create arbitrary http endpoints, including a periodic notification service.

For more information about Windows Azure, visit http://www.windowsazure.com. For introductory videos, also visit Windows Azure Mobile Services Tutorials on Channel 9.

Having now explored how to create periodic notification services, we’re ready to take the next step into push notifications. Push notifications are necessary when you need to issue updates more frequently than periodic notifications allow, essentially on demand (hence the name, “push”). This is the topic that we’ll return to in Part 3 of this series, where we’ll see much more of Azure Mobile Services.

Kraig Brockschmidt
Program Manager, Windows Ecosystem Team
Author, Programming Windows 8 Apps in HTML, CSS, and JavaScript