For those of you currently subscribed to our RSS feed, don’t worry. We’ll automatically redirect posts from the old blog to the new blog so you don’t miss a beat. And we’ll continue to host all our existing blog posts right here, so you can always come back to check out the info we’ve written on developing apps for Windows 8.

I hope you’ve enjoyed the content on the blog so far and look forward to seeing you on the Windows App Builder blog.

-Ian LeGrow, Group Program Manager, Windows

Item rendering in a ListView happens through either a declarative template defined in HTML or through a custom JavaScript rendering function that’s called for every item in the list. Although using a declarative template is the simplest, it doesn’t provide much latitude for specific control over the process. A rendering function, on the other hand, lets you customize rendering on a per-item basis and enables a number of optimizations that are demonstrated in the HTML ListView optimizing performance sample. Those optimizations are:

• Allowing for asynchronous delivery of item data and a rendered element, as supported by basic rendering functions.
• Separating the creation of an item’s shape, which is necessary for the ListView’s overall layout, from its internal elements. This is supported through a placeholder renderer.
• Reusing a previously-created item element (and its children) by replacing its data, avoiding most of the element-creation steps, provided for through a recycling placeholder renderer.
• Deferring expensive visual operations like image loading and animations until an item is visible and the ListView isn’t being rapidly panned, which is accomplished through a multistage renderer.
• Batching together those same visual operations to minimize re-rendering of the DOM with a multistage batching renderer.

In this post we’ll go through all these stages and learn how they cooperate with the ListView’s item rendering process. As you can imagine, optimizations around the when of item rendering involves lots of asynchronous operations and therefore lots of promises. So in the process, we’ll also gain a deeper understanding of promises themselves, building upon the earlier All about promises on this blog.

As a general note that applies to all renderers, it’s always important to keep your core item rendering time (not counting deferred operations) to a minimum. Because the ListView’s final performance greatly depends on how well its updates are aligned to screen refresh intervals, a few extra milliseconds spent in an item renderer can bump the ListView’s overall rendering time over the next refresh interval, resulting in dropped frames and visual choppiness. In other words, item renderers are one place where it really does count to optimize your JavaScript code.

Basic renderers

Let’s start with a quick review of what an item rendering function—which I’ll simply call a renderer—looks like. A renderer is a function that you assign to the ListView’s itemTemplate property instead of a template name, and that function will be called, as necessary, for items that the ListView wants to include in the DOM. (Basic documentation for renderers, by the way, is found on the itemTemplate page, but it’s the sample that really shows the optimizations.)

You might expect that an item rendering function would just be given an item from the ListView’s data source. It would then create the HTML elements needed for that particular item and return the root element that the ListView can add to the DOM. This is essentially what happens, but there are two added considerations. First, the item data itself might be loaded asynchronously, so it makes sense to tie element creation to the availability of that data. Furthermore, the process of rendering the item itself might involve other asynchronous work, such as loading images from remote URIs or reading data in other files identified in the item data. The different levels of optimization that we’ll see, in fact, allow for an arbitrary amount of async work between the request of the item’s elements and actual delivery of those elements.

So, again, you can expect that promises are involved! For one, the ListView doesn’t just give the renderer the item data directly, it supplies a promise for that data. And instead of the function directly returning the item’s root element, it returns a promise for that element. This allows the ListView to join many item rendering promises together and wait (asynchronously) until a whole page worth of items has been rendered. It does this, in fact, to intelligently manage how it builds up different pages, first building the page of visible items, then two offscreen pages forward and back where users are most likely to pan to next. In addition, having all these promises in place means that the ListView can easily cancel the rendering of unfinished items if the user pans away, thereby avoiding unnecessary element creation.

We can see how these promises are used in the simpleRenderer function of the sample:

function simpleRenderer(itemPromise) {
    return itemPromise.then(function (item) {
        var element = document.createElement("div");
        element.className = "itemTempl";
        element.innerHTML = "<img src='" + item.data.thumbnail +
            "' alt='Databound image' /><div class='content'>" + item.data.title + "</div>";
        return element;
    });
}

This code first attaches a completed handler to the itemPromise. The handler is invoked when the item data is available and effectively creates the elements in response. But notice again that we’re not actually returning the element directly—we’re returning a promise that’s fulfilled with that element. That is, the return value from itemPromise.then() is a promise that’s fulfilled with element if and when the ListView needs it.

Returning a promise allows us to do other asynchronous work if necessary. In this case the renderer can just chain those intermediate promises together, returning the promise from the last then in the chain. For example:

function someRenderer(itemPromise) {
    return itemPromise.then(function (item) {
        return doSomeWorkAsync(item.data);
    }).then(function (results) {
        return doMoreWorkAsync(results1);
    }).then(function (results2) {
        var element = document.createElement("div");
        // use results2 to configure the element
        return element;
    });
}

Note that his is a case where we do not use done at the end of the chain because we’re returning the promise from the last then call. The ListView takes responsibility for handling any errors that might arise.

Placeholder renderers

The next stage of ListView optimization uses a placeholder renderer that separates building up the element into two stages. This allows the ListView to ask for just those parts of an element that are necessary to define the list’s overall layout, without having to build up all the elements inside each item. As a result, the ListView can complete its layout pass quickly and continue to be highly responsive to further input. It can then ask for the remainder of the element at a later time.

A placeholder renderer returns an object with two properties instead of just a promise:

• element The top-level element in the item’s structure that’s enough to define its size and shape and is not dependent on the item data.
• renderComplete A promise that’s fulfilled when the remainder of the element’s contents are constructed, that is, returns the promise from whatever chain you have starting with itemPromise.then as before.

The ListView is smart enough to check whether your renderer returns a promise (the basic case as before) or an object with element and renderComplete properties (more advanced cases). So the equivalent placeholder renderer (in the sample) for the previous simpleRenderer is as follows:

function placeholderRenderer(itemPromise) {
    // create a basic template for the item that doesn't depend on the data
    var element = document.createElement("div");
    element.className = "itemTempl";
    element.innerHTML = "<div class='content'>...</div>";

    // return the element as the placeholder, and a callback to update it when data is available
    return {
        element: element,

        // specifies a promise that will be completed when rendering is complete
        // itemPromise will complete when the data is available
        renderComplete: itemPromise.then(function (item) {
            // mutate the element to include the data
            element.querySelector(".content").innerText = item.data.title;
            element.insertAdjacentHTML("afterBegin", "<img src='" +
                item.data.thumbnail + "' alt='Databound image' />");
        })
    };
}

Note that the element.innerHTML assignment could be moved inside renderComplete because the itemTempl class in the sample’s css/scenario1.css file specifies the width and height of the item directly. The reason why it’s included in the element property is because it provides the default “…” text in the placeholder. You could just as easily use an img element that refers to a small in-package resource that’s shared across all the items (and thus renders quickly).

Recycling placeholder renderers

Note: This option is only available on Windows 8 and the WinJS 1.0 ListView. On Windows 8.1 Preview and later the WinJS 2.0 ListView doesn’t recycle items because of changes in loading behaviors.

The next optimization, the recycling placeholder renderer, doesn’t add anything new where promises are concerned. It rather adds awareness of a second parameter to the renderer called recycled, which is the root element of an item that was previously rendered but is no longer visible. That is, the recycled element already has is child elements in place, so you can simply replace the data and perhaps tweak a few of those elements. This avoids most of the otherwise costly element-creation calls needed for a wholly new item, saving quite a bit of time in the rendering process.

The ListView may provide a recycled element when its loadingBehavior is set to "randomaccess". If recycled is given, you can just clean data out of the element (and its children), return it as the placeholder, and then fill in data and create any additional children (if necessary) within renderComplete. If a recycled element is not provided (as when the ListView is first created or when loadingBehavior is "incremental"), you’ll create the element anew. Here’s the code from the sample for that variation:

function recyclingPlaceholderRenderer(itemPromise, recycled) {
    var element, img, label;
    if (!recycled) {
        // create a basic template for the item that doesn't depend on the data
        element = document.createElement("div");
        element.className = "itemTempl";
        element.innerHTML = "<img alt='Databound image' style='visibility:hidden;'/>" +
            "<div class='content'>...</div>";
    }
    else {
        // clean up the recycled element so that we can reuse it 
        element = recycled;
        label = element.querySelector(".content");
        label.innerHTML = "...";
        img = element.querySelector("img");
        img.style.visibility = "hidden";
    }
    return {
        element: element,
        renderComplete: itemPromise.then(function (item) {
            // mutate the element to include the data
            if (!label) {
                label = element.querySelector(".content");
                img = element.querySelector("img");
            }
            label.innerText = item.data.title;
            img.src = item.data.thumbnail;
            img.style.visibility = "visible";
        })
    };
}

In renderComplete, be sure to check for the existence of elements that you don’t create for a new placeholder, such as label, and create them here if needed.

If you’d like to clean out recycled items more generally, note that you can provide a function to the ListView’s resetItem property. This function would contain similar code to that shown above. The same is true for the resetGroupHeader property, because you can use template functions for group headers as well as items. We haven’t spoken of these as much because group headers are far fewer and don’t typically have the same performance implications. Nevertheless, the capability is there.

Multistage renderers

This brings us to the penultimate optimization, the multistage renderer. This extends the recycling placeholder renderer to delay-load images and other media until the rest of the item is wholly present in the DOM. It also delays effects like animations until the item is actually on screen. This recognizes that users often pan around within a ListView quite rapidly, so it makes sense to asynchronously defer the more expensive operations until the ListView has come to a stable position.

The ListView provides the necessary hooks as members on the item result from itemPromise: a property called ready (a promise) and two methods, loadImage and isOnScreen, both of which return (more!) promises. That is:

renderComplete: itemPromise.then(function (item) {
    // item.ready, item.loadImage, and item.isOnScreen available
})

Here’s how you use them:

• ready Return this promise from the first completed handler in your chain. This promise is fulfilled when the full structure of the element has been rendered and is visible. This means you can chain another then with a completed handler in which you do other post-visibility work like loading images.
• loadImage Downloads an image from a URI and displays it in the given img element, returning a promise that’s fulfilled with that same element. You attach a completed handler to this promise, which itself returns the promise from isOnScreen. Note that loadImage will create an img element if one isn’t provided and deliver it to your completed handler.
• isOnScreen Returns a promise whose fulfillment value is a Boolean indicating whether the item is visible or not. In present implementations, this is a known value so the promise is fulfilled synchronously. By wrapping it in a promise, though, it can be used in a longer chain.

We see all this in the sample’s multistageRenderer function, where completion of the image load is used to start a fade-in animation. Here I’m just showing what’s returned from the renderComplete promise:

renderComplete: itemPromise.then(function (item) {
    // mutate the element to update only the title
    if (!label) { label = element.querySelector(".content"); }
    label.innerText = item.data.title;

    // use the item.ready promise to delay the more expensive work
    return item.ready;
    // use the ability to chain promises, to enable work to be cancelled
}).then(function (item) {
    // use the image loader to queue the loading of the image
    if (!img) { img = element.querySelector("img"); }
    return item.loadImage(item.data.thumbnail, img).then(function () {
        // once loaded check if the item is visible
        return item.isOnScreen();
    });
}).then(function (onscreen) {
    if (!onscreen) {
        // if the item is not visible, don't animate its opacity
        img.style.opacity = 1;
    } else {
        // if the item is visible, animate the opacity of the image
        WinJS.UI.Animation.fadeIn(img);
    }
})

Even though there’s a lot going on, we still just have a basic promise chain here. The first async operation in the renderer updates simple parts of the item element structure, such as text. It then returns the promise in item.ready. When that promise is fulfilled—or, more accurately, if that promise is fulfilled—we use the item’s async loadImage method to kick off an image download, returning the item.isOnScreen promise from that completed handler. This means that the onscreen visibility flag gets passed to the final completed handler in the chain. When and if that isOnScreen promise is fulfilled—meaning the item is actually visible—we can perform relevant operations like animations.

I emphasize the if part because it’s again likely that the user will be panning around within the ListView while all this is happening. Having all these promises chained together again makes it possible for the ListView to cancel the async operations whenever these items are panned out of view and/or off any buffered pages. Suffice it to say that the ListView control has gone through a lot of performance testing!

It’s also important to remind ourselves again that we’re using then throughout all these chains because we’re still returning a promise from the rendering function within the renderComplete property. We’re never the end of the chain in these renderers, so we’ll never use done at the end.

Thumbnail batching

The last optimization is truly the coup de grace for the ListView control. In the function called batchRenderer, we find this structure for renderComplete (most code omitted):

renderComplete: itemPromise.then(function (i) {
    item = i;
    // ...
    return item.ready;
}).then(function () {
    return item.loadImage(item.data.thumbnail);
}).then(thumbnailBatch()
).then(function (newimg) {
    img = newimg;
    element.insertBefore(img, element.firstElementChild);
    return item.isOnScreen();
}).then(function (onscreen) {
    //...
})

             

This is almost the same as the multistageRenderer except for the insertion of this mysterious call to a function called thumbnailBatch between the item.loadImage call and the item.isOnScreen check. The placement of thumbnailBatch in the chain indicates that its return value must be a completed handler that itself returns another promise.

Confused? Well, we’ll get to the bottom of it! But we first need a little more background as to what we’re trying to accomplish.

If we just had a ListView with a single item, various loading optimizations wouldn’t be noticeable. But ListViews typically have many items, and the rendering function is called for each one. In the multistageRenderer of the previous section, the rendering of each item kicks off an async item.loadImage operation to download its thumbnail from an arbitrary URI, and each operation can take an arbitrary amount of time. So for the list as a whole, we might have a bunch of simultaneous loadImage calls going on, with the rendering of each item waiting on the completion of its particular thumbnail. So far so good.

An important characteristic that’s not at all visible in multistageRenderer, however, is that the img element for the thumbnail is already in the DOM, and the loadImage function sets that image’s src attribute as soon as the download has finished. This in turn triggers an update in the rendering engine as soon as we return from the rest of the promise chain, which is essentially synchronous after that point.

It’s possible, then, that a bunch of thumbnails could come back to the UI thread within a short amount of time. This will cause excess churn in the rendering engine and poor visual performance. To avoid this churn, we want to fully create these img elements before they’re in the DOM, and then add them in batches such that they’re all handled in a single rendering pass.

The sample does this through a piece of promise-magic code a function called createBatch. createBatch is called just once for the whole app, and its result—another function—is stored in the variable named thumbnailBatch:

var thumbnailBatch;
thumbnailBatch = createBatch();

A call to this thumbnailBatch function, as I’ll refer to it from here on, is again inserted into the promise chain of the renderer. This purpose of this insertion, given the nature of the batching code as we’ll see shortly, is to group together a set of loaded img elements, releasing them for further processing at suitable intervals. Again, just looking at the promise chain in the renderer, a call to thumbnailBatch() must return a completed handler function that returns a promise, and the fulfillment value of that promise (looking at the next step in the chain) must be an img element that can then be added to the DOM. By adding those images to the DOM after the batching has taken place, we combine that whole group into the same rendering pass.

This is an important difference between the batchRenderer and the multistageRenderer of the previous section: in the latter, the thumbnail’s img element already exists in the DOM and is passed to loadImage as the second parameter. So when loadImage sets the image’s src attribute, a rendering update is triggered. Within batchRenderer, however, that img element is separately created within loadImage (where src is also set), but the img is not yet in the DOM. It’s only added to the DOM after the thumbnailBatch step completes, making it part of a group within that single layout pass.

So now let’s see how that batching works. Here’s the createBatch function in its entirety:

function createBatch(waitPeriod) {
    var batchTimeout = WinJS.Promise.as();
    var batchedItems = [];

    function completeBatch() {
        var callbacks = batchedItems;
        batchedItems = [];
        for (var i = 0; i < callbacks.length; i++) {
            callbacks[i]();
        }
    }

    return function () {
        batchTimeout.cancel();
        batchTimeout = WinJS.Promise.timeout(waitPeriod || 64).then(completeBatch);

        var delayedPromise = new WinJS.Promise(function (c) {
            batchedItems.push(c);
        });

        return function (v) {
            return delayedPromise.then(function () {
                return v;
            });
        };
    };
}

Again, createBatch is called just once and its thumbnailBatch result is called for each rendered item in the list. The completed handler that thumbnailBatch generates is then called whenever a loadImage operation completes.

Such a completed handler might just as easily have been inserted directly into the rendering function, but what we’re trying to do here is coordinate activities across multiple items rather than just on a per-item basis. This coordination is achieved through the two variables created and initialized at the beginning of createBatch: batchedTimeout, initialized as an empty promise, and batchedItems, initialized an array of functions that’s initially empty. createBatch also declares a function, completeBatch, that simply empties batchedItems, calling each function in the array:

function completeBatch() {
    // Copy and clear the array so that the next batch can start to accumulate
    // while we're processing the previous one.
    var callbacks = batchedItems;
    batchedItems = [];
    for (var i = 0; i < callbacks.length; i++) {
        callbacks[i]();
    }
}

Now let’s see what happens within thumbnailBatch (the function returned from createBatch), which is again called for each item being rendered. First, we cancel any existing batchedTimeout and immediately recreate it:

batchTimeout.cancel();
batchTimeout = WinJS.Promise.timeout(waitPeriod || 64).then(completeBatch);

The second line shows the future delivery/fulfillment pattern discussed in the All About Promises post <TODO: link>: it says to call completeBatch after a delay of waitPeriod milliseconds (with a default of 64ms). This means that so long as thumbnailBatch is being called again within waitPeriod of a previous call, batchTimeout will be reset to another waitPeriod. And because thumbnailBatch is only called after an item.loadImage call completes, we’re effectively saying that any loadImage operations that complete within waitPeriod of the previous one will be included in the same batch. When there’s a gap longer than waitPeriod the batch is processed—images are added to the DOM—and the next batch begins.

After handling this timeout business, the thumbnailBatch creates a new promise that simply pushes the complete dispatcher function into the batchedItems array:

var delayedPromise = new WinJS.Promise(function (c) {
    batchedItems.push(c);
});

Remember from All About Promises <TODO: link> that a promise is just a code construct, and that’s all we have here. The newly created promise has no async behavior in and of itself: we’re just adding the complete dispatcher function, c, to batchedItems. But of course, we don’t do anything with the dispatcher until batchedTimeout completes asynchronously, so there is in fact an async relationship here. When the timeout happens and we clear the batch (inside completeBatch), we’ll invoke any completed handlers given elsewhere to delayedPromise.then.

This brings us to the last lines of code in createBatch, which is the function that thumbnailBatch actually returns. This function is exactly the completed handler that gets inserted into the renderer’s whole promise chain:

return function (v) {
    return delayedPromise.then(function () {
        return v;
    });
};

In fact, let’s put this piece of code directly into the promise chain so we can see the resulting relationships:

return item.loadImage(item.data.thumbnail);
}).then(function (v) {
    return delayedPromise.then(function () {
        return v;
    });
).then(function (newimg) {

Now we can see that the argument v is the result of item.loadImage, which is the img element created for us. If we didn’t want to do batching, we could just say return WinJS.Promise.as(v) and the whole chain would still work: v would then be passed on synchronously and show up as newimg in the next step.

Instead, though, we’re returning a promise from delayedPromise.then which won’t be fulfilled—with v—until the current batchedTimeout is fulfilled. At that time—when again there’s a gap of waitPeriod between loadImage completions—those img elements are then delivered to the next step in the chain where they’re added to the DOM.

And that’s it!

In Closing

The five different rendering functions demonstrated in the HTML ListView optimizing performance sample all have one thing in common: they show how the asynchronous relationship between the ListView and the renderer—expressed through promises—allows the renderer tremendous flexibility in how and when it produces elements for items in the list. In writing your own apps, the strategy you use for ListView optimization greatly depends on the size of your data source, the complexity of the items themselves, and the amount of data that you’re obtaining asynchronously for those items (such as downloading remote images). Clearly, you’ll want to keep item renderers as simple as you can to still meet your performance goals. But in any case, you now have all the tools you need to help the ListView—and your app—perform its best.

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

In the course of your development work, however, you’ll probably encounter other uses of promises where it’s not entirely clear to see what’s going on. A good example of this is optimizing item rendering functions for a ListView control as shown in the HTML ListView optimizing performance sample. We’ll explore this in a subsequent post. Or consider this little gem that Josh Williams showed in his Deep Dive into WinJS talk at //build 2012 (slightly modified):

list.reduce(function callback (prev, item, i) {
    var result = doOperationAsync(item);
    return WinJS.Promise.join({ prev: prev, result: result}).then(function (v) {
        console.log(i + ", item: " + item+ ", " + v.result);
    });
})

This snippet joins promises for parallel async operations and delivers their results sequentially according to the order in list. If you can look at this code and immediately understand what it does, feel free to skip this post altogether! If not, let’s take a closer look at how promises really work, and their expression in WinJS—the Windows Library for JavaScript—so we can understand these kinds of patterns.

What is a promise, exactly? The promise relationships

Let’s begin with a fundamental truth: a promise is really nothing more than a code construct or, if you will, a calling convention. As such, promises have no inherent relationship to async operations—they just so happen to be very useful in that regard! A promise is simply an object representing a value that might be available at some point in the future, or might already be available. In this way, a promise is just like how we use the term in human relationships. If I say, “I promise to deliver you a dozen donuts,” then clearly I don’t need to have those donuts in my possession right now, but I certainly assume that I will have them some time in the future. And when I do, I’ll deliver them.

A promise thus implies a relationship between two agents: the originator who makes the promise to deliver some goods, and the consumer who is both the recipient of that promise and the goods themselves. How the originator goes about obtaining those goods is its own business. Similarly, the consumer can do whatever it wants with the promise itself and the delivered goods. It can even share the promise with other consumers.

Between originator and consumer, there are also two stages of this relationship, creation and fulfillment. All this is shown in the following diagram.

Having two stages of the relationship is why promises work well with asynchronous delivery, as we can see when we follow the flow in the diagram. The key part is that once the consumer gets acknowledgment of the request—the promise—it can go on with life (asynchronously) rather than waiting (synchronously). This means the consumer can do something else while it’s waiting for the promise to be fulfilled, such as responding to other requests, which is the whole purpose of async APIs in the first place. And what if the goods are already available? Then the promise is immediately fulfilled, making the whole thing a kind of synchronous calling convention.

Of course, there’s a bit more to this relationship that we have to consider. You’ve certainly made promises in your life, and have had promises made to you. Although many of those promises have been fulfilled, the reality is that many promises are broken—it’s possible for the pizza delivery person to have an accident on the way to your home! Broken promises are just a fact of life, one that we have to accept in both our personal lives and in asynchronous programming.

Within the promise relationship, then, this means that originator needs a way to say, “I’m sorry, but I can’t make good on this promise” and the consumer needs a way to know that this is the case. Secondly, as consumers, we can sometimes be rather impatient about promises made to us! So if the originator can track its progress in fulfilling its promise, the consumer also needs a way to receive that information. And third, the consumer can also cancel the order and tell the originator that it no longer needs the goods.

Adding these requirements to the diagram, we can now see the complete relationship:

Let’s now see how these relationships manifest in code.

The promise construct and promise chains

There are actually a number of different proposals or specifications for promises. The one used in Windows and WinJS is known as Common JS/Promises A, which says a promise—what’s returned by an originator to represent a value to deliver in the future—is an object with a function called then. Consumers subscribe to fulfillment of the promise by calling then. (Promises in Windows also support a similar function called done that’s used in promise chains, as we’ll see shortly.)

To this function the consumer passes up to three optional functions as arguments, in this order:

1. A completed handler. The originator calls this function when the promised value is available, and if that value already is available, the completed handler is called immediately (synchronously) from within then.
2. An optional error handler that’s called when there’s a failure to acquire the promised value. For any given promise, the completed handler is never called if the error handler has been called.
3. An optional progress handler, that’s periodically called with intermediate results if the operation supports it. (In WinRT, this means the API has a return value of IAsync[Action | Operation]WithProgress; those with IAsync[Action | Operation] don’t.)

Note that you can pass null for any of these arguments, as when you want to attach only an error handler and not a completed handler.

On the other side of the relationship, a consumer may subscribe as many handlers as it wants to the same promise by calling then multiple times. It can also share the promise with other consumers who may also call then to their hearts’ content. This is entirely supported.

This means that a promise must manage lists of all the handlers it receives and invoke them at the appropriate times. Promises also need to allow for cancellation, as outlined in the full relationship.

The other requirement that comes from the Promises A specification is that the then method itself returns a promise. This second promise is fulfilled when the completed handler given to the first promise.then returns, with the return value being delivered as the result of this second promise. Consider this code snippet:

var promise1 = someOperationAsync();
var promise2 = promise1.then(function completedHandler1 (result1) { return 7103; } );
promise2.then(function completedHandler2 (result2) { });

The chain of execution here is that someOperationAsync gets started, returning promise1. While that operation is underway, we call promise1.then, which immediately returns promise2. Be very clear that completedHandler1 is not called unless the result of the async operation is already available. Let’s assume we’re still waiting, so we go right into the call to promise2.then, and again, completedHandler2 will not be called at this time.

Sometime later, someOperationAsync completes with a value of, say, 14618. promise1 is now fulfilled, so it calls completedHandler1 with that value, so result1 will be 14618. completedHandler1 now executes, returning the value 7103. At this point promise2 is fulfilled, so it calls completedHandler2 with result2 equal to 7103.

Now what if a completed handler returns another promise? This case is handled a little differently. Let’s say that completedHandler1 in the code above returns a promise like so:

var promise2 = promise1.then(function completedHandler1 (result1) {
    var promise2a = anotherOperationAsync();
    return promise2a;
});

In this case, result2 in completedHandler2 won’t be promise2a itself, but the fulfillment value of promise2a. That is, because the completed handler returns a promise, promise2 as returned from promise1.then, will be fulfilled with the results of promise2a.

This characteristic is precisely what makes it possible to chain together sequential async operations, where the results from each operation in the chain feeds into the next. Without intermediate variables or named handlers, you often see this pattern for promise chains:

operation1().then(function (result1) {
    return operation2(result1)
}).then(function (result2) {
    return operation3(result2);
}).then(function (result3) {
    return operation4(result3);
}).then(function (result4) {
    return operation5(result4)
}).then(function (result5) {
    //And so on
});

Each completed handler, of course, will likely do something more with the results it receives, but in all chains you’ll see this core structure. What’s also true is that all the then methods here execute one right after the other, as all they’re doing is saving away the given completed handler and returning another promise. So by the time we reach the end of this code, only operation1 has started and no completed handlers have been called. But a bunch of intermediate promises from all the then calls have been created and wired up to one another to manage the chain as the sequential operations progress.

It’s worth noting that the same sequence can be achieved by nesting each subsequent operation within the previous completed handler, in which case you won’t have all the return statements. However, such nestings become an indentation nightmare, especially if you start adding progress and error handlers with each call to then.

Speaking of which, one of the features of promises in WinJS is that errors that occur in any part of the chain automatically propagate to the end of the chain. This means you should be able to simply attach a single error handler on the last call to then instead of having handlers at every level. The caveat, however, is that for various subtle reasons, those errors get swallowed if the last link in the chain is a call to then. This is why WinJS also provides a done method on promises. This method accepts the same arguments as then but indicates that the chain is complete (it returns undefined rather than another promise). Any error handler attached to done is then called for any errors in the entire chain. Furthermore, lacking an error handler, done throws an exception to the app level where it can be handled by window.onerror of WinJS.Application.onerror events. In short, all chains should ideally end in done to make sure exceptions surface and get handled properly.

Of course, if you write a function whose purpose is to return the last promise from a long chain of then calls, you’ll still use then at the end: the responsibility for handling errors then belongs to the caller who might use that promise in another chain altogether.

Creating promises: the WinJS.Promise class

While you can always create your own promise classes around the Promises A spec, it’s actually quite a lot of work that’s best left to a library. For this reason WinJS provides a robust, well-tested, and flexible promise class called WinJS.Promise. This allows you to easily create promises around different values and operations without having to manage the details of the originator/consumer relationships or the behavior of then.

When needed, you can (and should) use new WinJS.Promise–or a suitable helper function, as noted in the next section—to create promises around both asynchronous operations and existing (synchronous) values alike. Remember that a promise is just a code construct: there’s no requirement that a promise has to wrap an async operation or async anything. Similarly, the mere act of wrapping some piece of code in a promise doesn’t automatically make it run asynchronously. That’s still work you have to do yourself.

As a simple example of using WinJS.Promise directly, let’s say we want to perform a long computation—just adding up a bunch of numbers from one to some maximum—but do it asynchronously. We could invent our own callback mechanism for such a routine, but if we wrap it within a promise, we allow it to be chained or joined with other promises from other APIs. (Along these lines, the WinJS.xhr function wraps the asynchronous XmlHttpRequest of JavaScript within a promise, so you don’t have to deal with the latter’s particular event structure.)

We can of course use a JavaScript worker for a long computation, of course, but for the sake of illustration we’ll just keep this on the UI thread and use setImmediate to break the operation into steps. Here’s how we can implement it within a promise structure using WinJS.Promise:

function calculateIntegerSum(max, step) {
    //The WinJS.Promise constructor's argument is an initializer function that receives 
    //dispatchers for completed, error, and progress cases.
    return new WinJS.Promise(function (completeDispatch, errorDispatch, progressDispatch) {
        var sum = 0;

        function iterate(args) {
            for (var i = args.start; i < args.end; i++) {
                sum += i;
            };

            if (i >= max) {
                //Complete--dispatch results to completed handlers
                completeDispatch(sum);
            } else {
                //Dispatch intermediate results to progress handlers
                progressDispatch(sum);
                setImmediate(iterate, { start: args.end, end: Math.min(args.end + step, max) });
            }
        }
            
        setImmediate(iterate, { start: 0, end: Math.min(step, max) });
    });
}

When calling new WinJS.Promise, the single argument to its constructor is an initializer function (anonymous in this case). The initializer encapsulates the operation to perform, but be very clear that this function itself executes synchronously on the UI thread. So if we just performed a long calculation here without using setImmediate, we would block the UI thread for all that time. Again, placing code inside a promise doesn’t automatically make it asynchronous—the initializer function needs to set that up itself.

For arguments, the initializer function receives three dispatchers for the completed, error, and progress cases that promises support. As you can see, we call these dispatchers at appropriate times during the operation with the appropriate arguments.

I call these functions “dispatchers” because they’re not the same thing as the handlers that consumers subscribe to the promise’s then method (or done, but I won’t keep reminding you). Under the hood, WinJS is managing arrays of those handlers, which is what allows any numbers of consumers to subscribe any number of handlers. When you invoke one of these dispatchers, WinJS iterates through its internal list and invokes all those handlers on your behalf. WinJS.Promise also makes sure that its then returns another promise, as required for chaining.

In short, WinJS.Promise is providing all the surrounding details of a promise. This allows you to concentrate on the core operation that the promise represents, which is embodied in the initializer function.

Helpers for creating promises

The primary helper function to create a promise is the static method WinJS.Promise.as, which wraps any value in a promise. Such a wrapper on an already existing value just turns right around and calls any completed handler passed to then. This specifically allows you to treat arbitrary known values as promises, such that you can intermix and compose them (through joining or chaining) with other promises. Using as on an existing promise just returns that promise.

The other static helper function is WinJS.Promise.timeout, which provides a convenient wrapper around setTimeout and setImmediate. You can also create a promise that cancels a second promise if that second one is not fulfilled within a certain number of milliseconds.

Do note that the timeout promises around setTimeout and setImmediate are themselves fulfilled with undefined. A common question is then, “How can these be used to deliver some other result after the timeout?” The answer uses the fact that then returns another promise that’s fulfilled with the return value of the completed handler. This line of code, for example:

var p = WinJS.Promise.timeout(1000).then(function () { return 12345; });

creates the promise p that will be fulfilled with the value 12345 after one second. In other words, WinJS.Promise.timeout(…).then(function () { return <value>} ) is a pattern to deliver <value> after the given timeout. And if <value> itself is another promise, it means to deliver the fulfillment value from that promise at some point after the timeout.

Cancellation and generating promise errors

In the code we just saw, you might have noticed two deficiencies. First is that there’s no way to cancel the operation once it gets started. The second is that we don’t do a very good job handling errors.

The trick in both these cases is that promise-producing functions like calculateIntegerSum function must always return a promise. If an operation can’t complete or never gets started in the first place, that promise is in what’s called the error state. This means that the promise doesn’t have and never will have a result that it can pass to any completed handlers: it only ever calls its error handlers. Indeed, if a consumer calls then on a promise, that’s already in the error state, the promise immediately (synchronously) invokes the error handler given to then.

A WinJS.Promise enters the error state for two reasons: the consumer calls its cancel method or the code within the initializer function calls the error dispatcher. When this happens, error handlers are given whatever error value was either caught or propagated in the promise. If you’re creating an operation within a WinJS.Promise, you can also use an instance of WinJS.ErrorFromName. This is just a JavaScript object that contains a name property identifying the error and a message property containing more information. For example, when a promise is canceled, error handlers receive an error object with both name and message name set to “Canceled”.

But now what if you can’t even start the operation in the first place? For example, if you call calculateIntegerSum with bad arguments (like 0, 0), it shouldn’t even attempt to start counting and should instead return a promise in the error state. Such is the purpose of the static method WinJS.Promise.wrapError. This takes an instance of WinJS.ErrorFromName and returns a promise in the error state, which we would return in this case instead of a new WinJS.Promise instance.

The other part to all this is that although a call to the promise’s cancel method puts the promise itself into the error state, how do we stop the async operation that’s underway? In the previous calculateIntegerSum implementation, it will just keep calling setImmediate until the operation is complete, regardless of the state of the promise we created. In fact, if the operation calls the complete dispatcher after the promise has been canceled, the promise just ignores that completion.

What’s needed, then, is a way for the promise to tell the operation that it no longer needs to continue its work. For this reason the WinJS.Promise constructor takes a second function argument that’s called if the promise is canceled. In our example, a call to this function would need to prevent the next call to setImmediate, thereby stopping the computation. Here’s how that looks, along with proper error handling:

function calculateIntegerSum(max, step) {
    //Return a promise in the error state for bad arguments
    if (max < 1 || step < 1) {
        var err = new WinJS.ErrorFromName("calculateIntegerSum", "max and step must be 1 or greater");
        return WinJS.Promise.wrapError(err);
    }

    var _cancel = false;

    //The WinJS.Promise constructor's argument is an initializer function that receives 
    //dispatchers for completed, error, and progress cases.
    return new WinJS.Promise(function (completeDispatch, errorDispatch, progressDispatch) {
        var sum = 0;

        function iterate(args) {
            for (var i = args.start; i < args.end; i++) {
                sum += i;
            };

            //If for some reason there was an error, create the error with WinJS.ErrorFromName
            //and pass to errorDispatch
            if (false /* replace with any necessary error check -- we don’t have any here */) {
                errorDispatch(new WinJS.ErrorFromName("calculateIntegerSum (scenario 7)", "error occurred"));
            }

            if (i >= max) {
                //Complete--dispatch results to completed handlers
                completeDispatch(sum); 
            } else {
                //Dispatch intermediate results to progress handlers
                progressDispatch(sum);

                //Interrupt the operation if canceled
                if (!_cancel) {
                    setImmediate(iterate, { start: args.end, end: Math.min(args.end + step, max) });
                }
            }
        }
            
        setImmediate(iterate, { start: 0, end: Math.min(step, max) });
    },
    //Cancellation function for the WinJS.Promise constructor
    function () {
        _cancel = true;
    });
}

Altogether, creating instances of WinJS.Promise has many uses. For example, if you have a library that talks to a web service through some other async method, you can wrap those operations within promises. You might also use a new promise to combine multiple async operations (or other promises!) from different sources into a single promise where you want control over all the relationships involved. Within the code of an initializer for WinJS.Promise, you can certainly have your own handlers for other async operations and their promises. You can use these to encapsulate automatic retry mechanisms for network timeouts and such, hook into a generic progress updater UI, or add under-the-hood logging or analytics. In all these ways, the rest of your code never needs to know about the details and can just deal with promises from the consumer side.

Along these lines, it’s fairly straightforward to wrap a JavaScript worker into a promise such that it looks and behaves like other asynchronous operations in WinRT. Workers, as you might know, deliver their results through a postMessage call that raises a message event on the worker object in the app. The following code, then, links that event to a promise that’s fulfilled with whatever results are delivered in that message:

// This is the function variable we're wiring up.
var workerCompleteDispatch = null;

var promiseJS = new WinJS.Promise(function (completeDispatch, errorDispatch, progressDispatch) {
    workerCompleteDispatch = completeDispatch;
});

// Worker is created here and stored in the 'worker' variable

// Listen for worker events
worker.onmessage = function (e) {
    if (workerCompleteDispatch != null) {
        workerCompleteDispatch(e.data.results); /* event args depends on the worker */
    }
}

promiseJS.done(function (result) {
    // Output for JS worker
});

To expand this code to handle errors from the worker, you’d save the error dispatcher in another variable, have the message event handler check for error information in its event args, and the call the error dispatcher instead of the complete dispatcher as appropriate.

Joining parallel promises

As promises are often used to wrap asynchronous operations, it’s certainly possible that you can have multiple operations going on in parallel. In these cases, you might want to know when either one promise in a group is fulfilled, or when all the promises in the group are fulfilled. The static functions WinJS.Promise.any and WinJS.Promise.join provide for this.

Both functions accept an array of value or an object with value properties. Those values can be promises, and any non-promise values are wrapped with WinJS.Promise.as, such that the whole array or object is composed of promises.

Here are the characteristics of any:

• any creates a single promise that is fulfilled when one of the others is fulfilled or fails with an error (a logical OR). In essence, any attaches completed handlers to all those promises, and as soon as one completed handler is called, it calls whatever completed handlers the any promise has itself received.
• After the any promise is fulfilled (that is, after the first promise in the list is fulfilled), the other operations in the list continue to run, calling whatever completed, error, or progress handlers are assigned to those promises individually.
• If you cancel the promise from any, then all the promises in the list are canceled.

As for join:

• join creates a single promise that is fulfilled when all the others are fulfilled or fail with errors (a logical AND). In essence, join attaches completed and error handlers to all those promises, and waits until all those handlers are called before it calls whatever completed handlers it receives itself.
• The join promise also reports progress to any progress handlers you provide. The intermediate result in this case is an array of results from those individual promises that have been fulfilled so far.
• If you cancel promise from join it cancels all the other promises that are still pending.

Beyond any and join, there are two other static WinJS.Promise methods to know about, which can come in handy:

• is determines whether an arbitrary value is a promise, returning a Boolean. It basically makes sure it’s an object with a function named “then”; it doesn’t test for “done”.
• theneach applies completed, error, and progress handlers to a group of promises (using then), returning the results as another group of values inside a promise. Any of the handlers can be null.

Parallel promises with sequential results

With WinJS.Promise.join and WinJS.Promise.any we have the ability to work with parallel promises, that is, with parallel async operations. The promise returned by join, again, is fulfilled when all the promises in an array are fulfilled. However, those promises will likely complete in a random order. What if you have a set of operations that can execute this way, but you want to process their results in a well-defined order, namely the order that their promises appear in an array?

To do this you need to join each subsequent promise to the join of all those that came before, and the bit of code with which we began this post does exactly that. Here’s that code again, but rewritten to make the promises explicit. (Assume list is an array of values of some sort that are used as arguments for a hypothetical promise-producing async call doOperationAsync):

list.reduce(function callback (prev, item, i) {
    var opPromise = doOperationAsync(item);
    var join = WinJS.Promise.join({ prev: prev, result: opPromise});

    return join.then(function completed (v) {
        console.log(i + ", item: " + item+ ", " + v.result);
    });
})

To understand this code we have to first understand how the array’s reduce method works. For each item in the array, reduce calls the function argument, here named callback, which receives four arguments (only three of which are used in the code):

• prev The value that was returned from the previous call to callback (this is null for the first item).
• item The current value from the array.
• i The index of item in the list.
• source The original array.

For the first item in the list, we get promise which I’ll call opPromise₁. As prev is null, we’re joining [WinJS.Promise.as(null), opPromise₁]. But notice that we’re not returning join itself. Instead, we’re attaching a completed handler (which I’ve called completed) to that join and returning the promise from its then.

Remember that the promise returned from then will be fulfilled when the completed handler returns. This means that what we’re returning from callback is a promise that’s not completed until the first item’s completed handler has processed the results from opPromise₁. And if you look back at the result of a join, it’s fulfilled with an object that contains the results from the promises in the original list. That means that the fulfillment value v will contain both a prev property and a result property, where the latter is the result of opPromise₁.

With the next item in list, callback receives a prev that contains the promise from the previous join.then. We’ll then create a new join of opPromise₁.then and opPromise₂. As a result, this join not completes until both opPromise₂ is fullfilled and the completed handler for opPromise₁ returns. Voila! The completed₂ handler we now attach to this join isn’t called until after completed₁ has returned.

The same dependencies continue to be built up for each item in list—the promise from join.then for item n aren’t fulfilled until completed_n returns. This guarantees that the completed handlers are called in the same sequence as list.

In closing

In this post we’ve seen that promises in themselves are just a code construct or a calling convention—albeit a powerful one—to represent a specific relationship between an originator, who has values to deliver at an arbitrarily later time, and a consumer that wants to know when those values are available. As such, promises work very well to represent results from asynchronous operations, and are used extensively within Windows Store apps written in JavaScript. The specification for promises also allows sequential async operations to be chained together, with each intermediate result flowing from one link to the next.

The Windows Library for JavaScript, WinJS, provides a robust implementation of promises that you can use to wrap any kind of operation of your own. It also provides helpers for common scenarios such as joining together promises for parallel operations. With these, WinJS makes it possible to work with asynchronous operations very efficiently and effectively.

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

We’ll be using GameMaker: Studio from YoYo Games, to show you how to create and publish high-quality games in less time. GameMaker:Studio has a lot of great built-in design options and drag-and-drop tools that make it easy to get started even if you don’t have a game idea or development experience just yet. However, if you’re a more experienced game developer, the advanced tools help you to create a one-of-a-kind game experience.

The online event begins on Saturday, June 15^th, 10 am PDT, with a launch session and live chat. You’ll learn about different game types and how to add graphics, levels and sound to base games, while exploring ways to make the game your own. Support continues throughout the week with one-on-one assistance through the GameMaker forums.

Whether you’re a student, first-time developer, or seasoned pro, this event can get you started creating, uploading, and publishing games to the Windows Store. Learn more, sign up, and check out the free tools and resources at http://msdnevents.com/gameon/.

--Robert Rodriguez-Lawson, Senior Content Publishing Manager, Windows Developer Content

Say you have an app that connects to a service to access protected resources such as media files, social networking, etc. Your service requires login information for each user. So, you’ve built UI into your app that gets the username and password for the user, which is then used to log the user into the service. Everything works like a champ.

Now you want to go that extra mile for your users and store their login information securely so they don’t have to log in every time they use your app. Enter Credential Locker. With a few simple calls to the Credential Locker API, you can store the username and password for your user and easily retrieve them and log the user in the next time they open your app.

Secure storage

The great advantage that Credential Locker brings to your app is that it stores the user credentials in a secure location, and the credential information is encrypted when it’s stored on disk. Sure, you could store your user credentials in a file in the local storage for your app, but storing user credentials in plain text presents a considerable security hole. If a user’s system is compromised in some way, the user’s username and password are easy to access and manipulate. If the username and password are stored using Credential Locker, the best that a malicious source could get a hold of is an encrypted file.

The Credential Locker is unique to each Windows PC user and access to a credential is limited to the app that stored it. That is, you can only retrieve a credential that you stored for your app. Likewise, no other apps can get to the credentials that your app has stored in the locker.

Roaming credentials

As an added benefit to your users, when you store their username and password using Credential Locker, the stored credentials roam with their Microsoft account to any other trusted machine they use with that Microsoft account. This makes your secure app even more convenient for your users because your app can log them in automatically—without re-prompting the user for credentials--from any trusted machine they have installed your app on and associated with their Microsoft account.

Things work a little differently for domain accounts. If there are credentials stored with your Microsoft account, and you associate that account with a domain account (such as the account that you use at work), your credentials will roam to that domain account. However, any new credentials added when signed on with the domain account won’t roam. This ensures that private credentials for the domain aren’t exposed outside of the domain.

Storing user credentials

Storing user credentials in the Credential Locker is a quick, two-step process. First, you obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace. Then, you create a PasswordCredential object that contains an identifier for your app, the username and the password, and pass that to the PasswordVault.Add() method to add the credential to the locker.

C#

var vault = new Windows.Security.Credentials.PasswordVault();
vault.Add(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

JavaScript

var vault = new Windows.Security.Credentials.PasswordVault();
vault.add(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

Retrieving user credentials

You have several options for retrieving user credentials from the Credential Locker after you have a reference to the PasswordVault object.

• You can retrieve all the credentials the user has supplied for your app in the locker with the PasswordVault.RetrieveAll() method.
• If you know the username for the stored credentials, you can retrieve all the credentials for that username with the PasswordVault.FindAllByUserName() method.
• If you know the resource name for the stored credentials, you can retrieve all the credentials for that resource name with the PasswordVault.FindAllByResource() method.
• Finally, if you know both the username and the resource name for a credential, you can retrieve just that credential with the PasswordVault.Retrieve() method.

Let’s look at an example where we have stored the resource name globally in an app and we log the user on automatically if we find a credential for them. In the case where we find multiple credentials for the user, we ask the user to select a default credential to use when logging on.

C#

private string resourceName = "My App";
private string defaultUserName;

private void Login()
{
    var loginCredential = GetCredentialFromLocker();

    if (loginCredential != null)
    {
        // There is a credential stored in the locker.
        // Populate the Password property of the credential
        // for automatic login.
        loginCredential.RetrievePassword();
    }
    else
    {
        // There is no credential stored in the locker.
        // Display UI to get user credentials.
        loginCredential = GetLoginCredentialUI();
    }

    // Log the user in.
    ServerLogin(loginCredential.UserName, loginCredential.Password);
}


private Windows.Security.Credentials.PasswordCredential GetCredentialFromLocker()
{
    Windows.Security.Credentials.PasswordCredential credential = null;

    var vault = new Windows.Security.Credentials.PasswordVault();
    var credentialList = vault.FindAllByResource(resourceName);
    if (credentialList.Count > 0)
    {
        if (credentialList.Count == 1)
        {
            credential = credentialList[0];
        }
        else
        {
            // When there are multiple usernames,
            // retrieve the default username. If one doesn’t
            // exist, then display UI to have the user select
            // a default username.

            defaultUserName = GetDefaultUserNameUI();

            credential = vault.Retrieve(resourceName, defaultUserName);
        }
    }

    return credential;
}

var resourceName = "My App";
var defaultUserName;

function login() {
    var loginCredential = getCredentialFromLocker();

    if (loginCredential != null) {
        // There is a credential stored in the locker.
        // Populate the Password property of the credential
        // for automatic login.
        loginCredential.retrievePassword();
    } else {
        // There is no credential stored in the locker.
        // Display UI to get user credentials.
        loginCredential = getLoginCredentialUI();
    }

    // Log the user in.
    serverLogin(loginCredential.userName, loginCredential.password);
}


function GetCredentialFromLocker() {
    var credential = null;

    var vault = new Windows.Security.Credentials.PasswordVault();
    var credentialList = vault.findAllByResource(resourceName);
    if (credentialList.length > 0) {
        if (credentialList.length == 1) {
            credential = credentialList[0];
        } else {
            // When there are multiple usernames,
            // retrieve the default username. If one doesn’t
            // exist, display UI to have the user select
            // a default username.

            defaultUserName = getDefaultUserNameUI();
            credential = vault.retrieve(resourceName, defaultUserName);
        }
    }

    return credential;
}

Deleting user credentials

Deleting user credentials in the Credential Locker is also a quick, two-step process. Again, you obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace. Then, you pass the credential you want to delete to the PasswordVault.Remove() method.

C#

var vault = new Windows.Security.Credentials.PasswordVault();
vault.Remove(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

JavaScript

var vault = new Windows.Security.Credentials.PasswordVault();
vault.remove(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

Easy and secure

As you can see, the Credential Locker is an easy-to-use feature that simplifies your task of authenticating users and storing those user credentials for future use—all in a highly secure fashion.

Other Windows 8 app authentication topics include the Web Authentication Broker, which you can use to retrieve an authentication token from a website (for example, OAuth), and personalizing your app based on a user’s Microsoft account.

For more info, see

• Managing user info (JavaScript)
• Managing user info (Windows Store apps using C#/VB/C++ and XAML)
• Credential Locker sample
• Windows.Security.Credentials

--Doug Rothaus, Senior Content Developer, Windows Developer Content

Special thanks to Yashar Bahman for his help and contributions to this post.

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:

1. The accuracy level requested. This is the ideal level of accuracy to meet your app’s needs.
2. 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 50-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:

C#

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

C#

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

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:

C#

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:

C#

double zoomLevel = 13.0f;

Map.SetView(location, zoomLevel);

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

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:

1. The navigation model has changed so you can find the content relevant to where you are in the app development lifecycle
2. 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

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:

• Restaurant
• Place
• LocalBusiness
• FoodEstablishment

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:

1. A new instance of the app is launched in the share target window over the source app.
2. A share target activation event is fired and your app receives a ShareOperation object as a result.
3. Your app can retrieve the data that the user shared from this object.
4. 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

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:

1. 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

2. 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

1. 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.
2. 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:

1. Mario launches the alarm app and sets a time, say 7.00 AM. Normal alarm stuff, nothing with NFC yet.
2. 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.
3. 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
}

1. 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.
2. 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.
3. 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

Thanks,

Priya Dandawate
Program Manager, Devices and Networking

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

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

C#

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.

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:

1. 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.
2. 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.

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.

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

C#

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:

1. 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.
2. 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);
    }
}

C#

// 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.
        });
}

C#

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