One of the things we do in the Windows Ecosystem Scenario Adoption Team is work with top-tier software vendors to help them get key apps ready for things like launch events. Leading up to the General Availability (GA) of Windows 8 in late October, 2012, you can imagine that we were suitably busy (not to mention getting //Build 2012 together and, for myself, finishing up Programming Windows 8 Apps in HTML, CSS, and JavaScript!). Among those companies I worked with, one of them holds the record for the shortest time from first conceptualization to actually being available in the Store: two weeks! (I'm electing to not identify the app, simply because doing so in the context of this post can be interpreted a number of ways.) To be more specific, the first meeting I and a few of my teammates had with this company, its developers, and members of the agency that would be helping them with the app, was October 3rd, 2012. A working app was the available to the public from the Windows Store on October 17th, and we had time to make a few updates and improvements before the Windows 8 launch events a week later. How did we manage to pull this app together so quickly? In addition to the direct support provided by myself and my team, there are a number of factors that contributed to the speedy turnaround as I've written below. This list is also my answer to a question posed by one of my managers: "Why do some partners struggle when we have some who turn out an app very quickly?" What I've written here are then the guidelines of how to avoid struggling and get your productivity in high gear.

  • Complete commitment. These guys weren’t sitting on the fence or making passive agreements. They made a decision and then didn't let anything get in their way. Another way of saying this is that they just completely accepted the job and the platform as it is, and wanted to make the best experience within that reality. Another company I worked with early in 2012 for the first Windows 8 Consumer Preview, a travel app, took the same approach and got their first app done in 6 weeks, even with early tools and platform bugs. Conversely, some partners we've worked with seem to resist this level of commitment, making a big deal out of some small branding issue or turning other molehills into mountains, meaning that we seemed to slog through the process for month after month.
  • Prior experience: The company and their partner agency were also doing their Windows Phone 8 app at the same time. They knew their C# and XAML and didn’t need to struggle with the tools, language, and presentation layer. Other partners I worked with in Consumer Preview also ramped up quickly on the JavaScript side as their devs really knew their HTML/CSS/JS and just needed to learn the Windows platform specifics.
  • Knowing the Resources for a Quick Start: with the two-week project, the first thing I did, given that I'm deeply familiar with the Win8 platform, was to bang out an 8-page summary of what controls, APIs, and samples to use to implement what features in the design. I think this significantly shortened the amount of time they needed to do the job. Indeed, I highly recommend that developers really know the scope of the resources available in the samples, because you can then just grab code from a certain sample to solve a certain need–the Windows 8 samples in fact cover about 95% of the platform, so for most needs you're find code that you can quickly borrow and adapt. You can use my book as a reference for this, because I made note of every JS sample in the appropriate feature context, and by extension this also hits a significant number of C#/C++/XAML samples as well.
  • Properly scoped design: In short, don't try to do too much the first time out the door. Locking down the scope of an app early on and limiting design and development work to just that scope is super helpful. The app we did in two weeks was like this: we had a design in two days to which we only made minor modifications after thorough review. This meant that we could focus on developing just that, and not get sidetracked into other ideas. I’ve seen other partners, in contrast, go back and forth many times with many different ideas, which meant that the developers were having to rewrite stuff. Given that it's so easy to update apps in the Windows Store, you don't have to worry about getting it perfect the first time. Be sure to make it good enough to be useful and get good initial reviews, of course, but understand too that providing updates with more features later on will help to reengage customers.Another way of saying this is that because the development cycle for apps can be short (a matter of weeks instead of months or a year), then it seems to work better to have the designers and planners lock down a rev of the app and let the developers go at it, rather than have too much back-and-forth while the app is being developed, trying to add features, etc., as that just bogs down the dev team.
  • Clear, efficient, and appropriate methodologies: when a dev shop has clarity about who is doing what in their own teams, the process seems much smoother. The team on the two week app, for instance, had multiple teams or individuals working in parallel on app features that were easy to integrate together (my initial document also outlined what could be done in parallel). I've worked with other partners and agencies who had clear processes, as well; some partners, on the other hand, felt like they did everything by committee (too much methodology), as decisions were very slow in coming. Some partners, on the flip side, also end up being too chaotic (lack of methodologies).By the way, if you don't have a testing methodology, get one. Because the turnaround time for an app is not immediate like it is for the web, and because the customer reviews and ratings for your app stick across updates, you need to invest in up-front testing and not leave it to your customers to do that work for you!
  • Experience with tools: Having a solid familiarity with the tool stack ahead of time makes a big difference. With Visual Studio, I think newcomers are put off by the complexity of the whole thing, not knowing where to begin, exactly. For my book I made a 10-minute introduction to Visual Studio to address this, in which I show the core features you need to know about for writing and debugging code. This is Video 2-1 in the book's companion content; I've also posted to Channel 9 and YouTube.I also highly recommend learning to use Blend for Visual Studio Express, especially for CSS styling and probably for XAML, because the tool can make you highly productive. Blend very much helped the travel app developer last year—saved many hours, if not some says, when tracking down style issues. I show some of this tool in Video 2-2 of my book's companion content (I haven't posted it elsewhere).I can also recommend A deep dive into Expression Blend for designing Metro style apps using HTML (//Build 2011), Building Awesome HTML apps in Blend for Windows 8 (//Build 2012), and Designing awesome XAML apps in Visual Studio and Blend for Windows 8 and Windows Phone 8 (//Build 2012).And again, knowing where to find answers (docs, samples, forums–see http://dev.windows.com) is a kind of tool. Some devs just don’t know what’s available to them. Third party libraries, if you know how to use them (e.g. jQuery), can also help productivity.
  • Courage to ask questions: This has surprised me sometimes. Some devs are quick to reach out when they get stuck, whereas others seems to struggle along for a day or two before asking. I’ve made it a point to tell my partners that if they find themselves spending more than 30 minutes trying to find an answer, to just ask me. Otherwise you lose momentum and can get a little emotionally depressed (devs are not machines!) when you look too long for something, especially if you’re unsuccessful.Similarly, some devs are too fine-grained in their questions—asking how to solve something that doesn’t need solving if you step back and look at the larger issue at hand. I think the best results have come from devs who seek advice first on the general development approach, then ask good mid-level questions, then ask on specific details. This is again why the 8-pager I banged out for the two-week app was so effective.More generally, having good ongoing communication is helpful for a variety of reasons. I worry most about partners that don’t say anything for a while; having a regular sync call helps to keep the doors open. This is very necessary if you're working with an agency or have developers in different locales.
  • Making the right assumptions: Beyond core architecture decisions, I’ve seen devs make a design choice based on mistaken assumptions about how the platform works, and didn’t consult with us until they were a ways down that road and started to run into trouble (e.g. assuming that they could do more with an iframe or webview than is actually allowed). Of course, devs don’t always know that they’re making wrong assumptions, and if they didn't communicating well with us then we weren't able to provide timely feedback (hence again the utility of having regular sync calls).Checking one's assumptions is especially important for developers coming from other platforms like iOS and Android, because what works on those platforms might not work like you think on Windows.

 


A few week ago I answered a question on the MSDN forums that basically asked, “I ran code in a promise, so why didn’t it run asynchronously.” It was a good opportunity to clarify the nature of a promise and the relationship between promises and asynchronous code. So here I offer an edited version of my response.

The basic thing to understand is that a promise is just a way of saying “execute this code when the promised value becomes available (that is, when the promise of that value is fulfilled).” It says nothing about how the code is actually run in the CPU scheduler. So if you take a block of code and just wrap it with WinJS.Promise.as or such, e.g.:

return new WinJS.Promise(function (complete) {  /* some code */ });

you’re just saying that /* some code */ will execute when you call the promise’s then/done methods, but all that still happens on the UI thread.

True async behavior–that is, running code on another thread–happens through three means:

  1. A JavaScript worker (web worker), which you can wrap in a promise (new WinJS.Promise to handle the worker messages) in order to chain/join the async operation to others.
  2. An async method written in a C#/VB WinRT component where the code uses the Task class.
  3. An async method written in a C++ WinRT component where the code uses the concurrency library.

In the latter two cases, async methods (including those from the built-in WinRT APIs) happen to be projected into JavaScript as promises; in #1 you use new WinJS.Promise to do the same manually. But in every case, it’s not the promise that runs code on another thread–it’s purpose is just to manage completed/error/progress handlers. It’s the underlying worker or async method that runs code on another thread.

Creating async APIs in WinRT components as well as with web workers is something I cover in Chapter 16 of my book, in the section “Implementing Async Methods,” if you want all the details.

Here’s a link to the original forum discussion where I extract some of those details.



Section 3.6 of the Store Certification Requirements say this:

Your app must neither programmatically close nor offer UI affordances to close it. Windows 8 Process Lifetime Management closes Windows Store apps automatically.

Obviously, then, your app should haven’t close buttons on its canvas or in the app bar. What’s a little tricky is that an app should also avoid closing itself into anything but the most catastrophic circumstances. That is, if an app has detected that it simply cannot run because of corrupt state or such, then perhaps it can close itself (using MSApp.terminateApp, by the way, not window.close, as the former will give you the opportunity to provide information that will surface in the Windows Store Dashboard).

However, situations like not having network connectivity, or really any external condition from which the app can recover, are not ground for closing the app programmatically. I’ve seen some apps do this that clearly weren’t caught by the certification process: I’ll be running along just fine, then I lose connectivity, and then the app informs me of that with a MessageDialog and then closes itself. Ouch! I just lost whatever state I’d built up in the app, so when I restart I have to get back to where I was. This is a big no-no. In such cases, the app should let me know that I don’t have connectivity, but then give me a way to retry whatever I was doing (that is, an app bar command), when I connectivity has been restored.

In other words, be nice to your users and never assume that you should just up and quit because of some external condition. Again, if you detect an internal condition that would make it impossible for the app to continue running, that’s one thing. But if it’s an external condition that the user can remedy, give them the chance to do that and continue using your app.

I, for one, promise to give poor ratings to apps that I find don’t behave well in this way! 🙂


For some, the Windows Library for JavaScript, or WinJS, seems to take on an aura of mystique, as if it’s something really special or privileged, or something that is absolutely required by a Windows Store App.

The truth is that WinJS is actually just a JavaScript library, like other libraries you might employ. It does have one unique privilege in that it’s obtained automatically via the Windows Store when a dependent app is installed, and is also serviced through the Store.

But otherwise, it’s just a bunch of JavaScript code that makes writing a Windows Store app in JavaScript a whole lot easier, but isn’t absolutely required. For example, WinJS contains the HTML/CSS/JS implementation of those standard Windows 8 controls that aren’t already covered by HTML5. These include AppBar, DatePicker, FlipView, Flyout, ListView, Rating, SemanticZoom, TimePicker, ToggleSwitch, Tooltip, and ViewBox. You can roll your own versions of these if you want, but I’d think you’d want to spend time on those things that make your app really special.

Similarly, WinJS contains an animations library with the Windows 8 personality built right it…all this is implemented on CSS animations and transitions, so you can do it all manually, but what’s the point?

WinJS contains a bunch of utilities that simplify certain tasks in JavaScript–and many of these are pure JS and have nothing to do, really, with Windows itself. For example, WinJS.Namespace.define and WinJS.Class.define provide some built-in ways to deal with module and class patterns, which I find convenient. WinJS.Binding does the same for data binding, and WinJS.Navigation and WinJS.UI.Pages (along with WinJS.UI.Fragments) does the same for implementing a page navigation (that is, DOM-replacement) mechanism so you maintain the script context within an app.

Then there’s the WinJS.Application object that simplifies your interactions with the core Windows structures provided through WinRT–basically giving you an easier way to keep track of the details. All of this is stuff you can again write yourself, but the WinJS team decided that you’d probably like to have something written for you!

Consider something like promises as well. A promise is basically an object that has .then and .done methods on it. Even if you didn’t use WinJS, you’d get promise objects back from async WinRT APIs thanks to the JavaScript language projection. What the code in WinJS.Promises does, then, is give you a set of utilities for doing more with these basic promises, like joining them or creating new ones from scratch. Again, all stuff you might end up writing on your own, just like the wrapper for XmlHttpRequests in WinJS.xhr that makes that async JS API look like a promise such that it can be easily integrated in with other async code using WinRT.

The short of it is that WinJS is a library full of all kinds of stuff for which people inside Microsoft figured a standard implementation would be really, really helpful.

Now along these lines, questions about the nature of WinJS sometimes arise in the context of whether it’s possible to write a Windows Store app using HTML, CSS, and JavaScript and have that app run within other browsers or other frameworks that also use these standards.

You can certainly write code that can be used in both an app and a site, and they can use common services, but an app written in HTML, CSS, and JavaScript has specific structures that are distinctly different from the structure of a web site/web app.

In particular, an app ties into various platform features such as the WinRT API, many parts of WinJS, and the fact that it’s running inside the WWAHost process instead of a browser. Apps are also generally written in an AJAX style (a single HTML page wherein parts of the DOM are swapped in and out) rather than using <a> navigation (which is again why WinJS provides many utilities here).

So again if you modularize your app code to separate pure app logic that can run in a browser (and doesn’t have any Windows-specific dependencies) from that which is platform-specific, then you can achieve some amount of code-sharing. But those apps won’t just run in a browser. They aren’t web apps: they are Windows Store apps that just so happen to be written with the same technologies as web apps.

Is it possible to use WinJS code in a web app, then? Originally, WinJS wasn’t licensed for this purpose, but as of April 2014, WinJS is an open source project so that you can use it anywhere. See http://try.buildwinjs.com/. It’s important to note that WinJS will take advantage of WinRT APIs when they’re available, but it was written to adapt when WinRT isn’t there.

In short, WinJS is a very useful library with many different controls and other capabilities, and now that it’s open source it’s really helpful for creating a Windows-like experience in apps and on the web.


A somewhat frequent question from developers is how to keep some piece of data secret within an app, such as a secret app key provided by a service.

If this is something that an app acquires at runtime, then you want to use the Credential Locker API to securely store that bit of information. The Credential Locker API is found in the Windows.Security.Credentials.PasswordVault namespace. Whatever is stored here is encrypted, of course, and can only be retrieved by the app that saved it in the first place. What’s also very cool about this feature is that the contents of the Credential Locker is also roamed to the user’s other devices if they have PC Settings > Sync your settings > Password option turned on (and the PC is trusted). So if your app is installed on one device, obtains a secret key for a web service, stores it in the locker, and the user allows those credentials to be roamed, then that secret key will be available to your app when that same user installs it on another device. So you’d want to check for the existence of that secret key even on first run.

If you acquire such a key during app development and include it directly in the app package, then there is the possibility that the key can be discovered and extracted. In this case, the best approach is to store that key in a web service that you query on first run, after which you can save it in the credential locker and retrieve it from there during subsequent sessions.

In other words, assume that everything in your app package is public information and take appropriate steps.


HTML5 contains a geolocation API to find the user’s location, something that used to be accomplished by analyzing IP addresses. As shown in the specification, http://www.w3.org/TR/geolocation-API/, the API itself is fairly simple. For Windows Store apps written in HTML/CSS/JavaScript, then, there is an overlap with the Windows.Devices.Geolocation API in WinRT. So which one should you use?

Note: one key difference for any comparison with WinRT APIs is that HTML5 and native JavaScript APIs are available in the web context whereas WinRT is not. This comparison therefore only applies to pages running in the local context; in the web context you’ll want to use the HTML5/JS APIs.

It’s also helpful to note that overlaps such as these exist (a) because of the local and web contexts, and (b) to provide the capability to Windows Store apps written in other languages where an intrinsic API is not available.

With that, let’s look at both APIs in turn.

Geolocation in HTML5

HTML5’s geolocation is available through the navigator.gelocation object in JavaScript. With this you can obtain a single reading, which is useful to present location-relevant content for a visitor, and also watch the position for ongoing readings.

A single reading is retrieved through the navigator.geolocation.getCurrentPosition method, to which you pass a function that receives a position object:

navigator.geolocation.getCurrentPosition(function(position) {
     var lat = position.coords.latitude;
     var long = position.coords.longitude;
     …
});

Additional parameters to getCurrentPosition include an error function and an object containing the options enableHighAccuracy (bool), maximumAge (maximum age of cached data in milliseconds), and timeout (in milliseconds).

Ongoing (asynchronous) readings are taken by passing a callback function to navigator.geolocation.watchPosition that takes the same parameters as getCurrentPosition. watchPosition returns an ID for the operation which can be passed to clearWatch to end the readings.

The timeout option value is important as it determines the maximum length of time that can elapse between a call to getCurrentPosition and watchPosition and a callback with a position value. If that timeout is exceeded, the error function is called with a TIMEOUT error. Other error conditions are PERMISSION_DENIED (see below) and POSITION_UNAVAILABLE (no geolocation capability is available, or there’s an error in determining the location). Note that a watch will remain in place when an error occurs.

The position object passed to the callback in both cases contains a timestamp member as well as a coords object. The latter contains latitude, longitude, altitude, accuracy, altitudeAccuracy, heading, and speed (all doubles). Complete details are, of course, in the specification.

Privacy is a concern with geolocation. The W3C specification places the responsibility for insuring privacy on the agent that implements the API. Internet Explorer, for instance, pops up an alert to the user asking their permission on behalf of sites that use the API. This can be seen with the IE9 TestDrive site’s Geolocation page, http://ie.microsoft.com/testdrive/HTML5/Geolocation/Default.html.

If the user disallows geolocation, the error function given to getCurrentPosition or watchPosition is called with a PERMISSION_DENIED error.

Note that when using HTML5 geolocation in a Windows Store app (including any web content in iframes and pages within navigation domains), it is necessary to declare the Location capability in the app manifest. Without this declaration, the APIs will fail with PERMISSION_DENIED errors.

Note also that if a Windows Store app navigates to any additional websites (e.g. uses navigation domains or includes content in iframes) that utilize geolocation, it must also include the domain in the ApplicationContentUris list.

Geolocation in WinRT

In WinRT, geolocation is provided through the Windows.Devices.Geolocation API. In WinRT you create (with new) a Windows.Devices.Geolocation.Geolocator object, which you then configure with various properties if desired: desiredAccuracy (default or high), movementThreshold (double), and reportInterval (double).

Obtaining a one-time position reading is done through the getGeopositionAsync method that produces a Windows.Devices.Geolocation.Geoposition object. Its properties are civicAddress and coordinate, where the properties of the latter are accuracy, altitude, altitudeAccuracy, heading, latitude, longitude, speed, and timestamp.
var gl = new Windows.Devices.Geolocation.Geolocator();
gl.getGeopositionAsync().then(function (posOp) {
     var position = posOp.getResults();
     var lat = position.coordinate.latitude;
     var long = position.coordinate.longitude;
     …
});

A variation of getPositionAsync lets you specify maximumAge and timeout parameters.

You can also assign functions to the positionChanged and statusChanged members of the Geolocator object for ongoing readings. positionChanged will be called within the reportInterval setting, and statusChanged is called when the device status changes between the following states:

  • ready: location data is available.
  • initializing: the location provider is initializing (e.g. a GPS receiver is still acquiring satellites).
  • noData: no location data is available from any location provider (like POSITION_UNAVAILABLE in HTML5).
  • disabled: the application doesn’t have permission to access location (like PERMISSION_DENIED in HTML5).
  • notInitialized: an operation to retrieve location has not yet been initialized (i.e. the app has not called getGeopositionAsync or registered for the positionChanged event).
  • notAvailable: the Windows Sensor and Location Platform is not available on this version of Windows.

Where privacy is concerned, this API will fail unless the app has declared the Location capability in its manifest. At runtime, Windows will also prompt the user for consent.

API Differences and Distinctions

As with other overlapping parts of WinRT and HTML5/JavaScript, the Geolocation APIs in WinRT are primarily there for apps written in C++ and .NET languages, where no other option is available. For written in HTML/CSS/JS, the two alternatives are more or less equal, with a few distinctions:

  • Geolocation options: The movementThreshold option is unique to WinRT, which is used for system power management and which allows an app to only receive readings there has been enough of a change. This is helpful for geo-fencing apps that only want to update themselves when the user has moved far enough away from a given point. To do the same with the HTML5 API requires more frequent location polling and calculating distance to filter out events.
  • Position information: When address information is supported by a location provider, WinRT provides for surfacing that data through the civicAddress property (and its individual sub-propeities).

Thus, developers with existing HTML5 geolocation code, or those who want to maintain as much platform-neutral code in their apps as possible, will likely use the HTML5 API. On the other hand, the convenience of movementThreshold and its positive effect on power management is a significant benefit of the WinRT API.


This isn’t so much a tip for certification, as for improving the chances that your app might be highlighted in the Store. To put it simply, if you don’t include great promotional graphics with your app submission, then the Store doesn’t have what it needs to put your app in the spotlight. Here’s the quote from the documentation, from What to include in your app’s description:

Promotional images

The Windows Store editorial team uses promotional images when they feature  apps in the Windows Store. Providing promotional images for your app doesn’t guarantee your app will be featured. But not providing them almost guarantees that it won’t be.

For more info about creating and uploading promotional images for your app, see Promotional images.

That last link above will give you exact dimensions and other requirements for those image.


It occasionally comes up that you need to serially iterate over a synchronous collection, but doing so involves async APIs. For example, you have a vector of StorageFile objects and want to call copyAsync on each of them, one at a time, in the order of the vector.

This can be accomplished with the following code (thanks to Adam Comella for this solution). Assuming that storageItems is the list over which you want to iterate and destination is the folder into which you want to copy those items, you can do this:

var storageItemsPromise = WinJS.Promise.as();
storageItems.forEach(function (item) {
     storageItemsPromise = storageItemsPromise.then(function () {
         return item.CopyAsync(destination);
     });
});
// Call done so that if CopyAsync throws an exception, it’ll cause the app to terminate
storageItemsPromise.done();


I installed the Win8 app called “Logo Quiz” the other day and noticed that the authors used a default splash screen image that simply contained an hourglass:

I found this definitely curious because a splash screen, while serving the same purpose of the hourglass–namely giving the user something to look at while an app is loading–is also an app’s first opportunity for promoting their brand and creating a sense of identity in the mind of the user. So having an app’s splash screen contain nothing but an hourglass works, for sure, but can be made so much better. I certainly hope that Logo Quiz improves upon this in their next version, because they do have a much more interesting tile image to serve as a basis.

At the same time, it’s clear that some of the blame for this misunderstanding lies with Microsoft’s early app templates in Visual Studio, where the default splash screen image from those templates showed a clock face:

This could easily have been interpreted to say that the purpose of the splash screen image is to show an hourglass representation of some sort, but indeed, that’s not the point at all. This is one reason why the current templates now just have a box with a big X through it as if to say “please don’t use this image!” (though some apps still do!).

In the end, always remember that the splash screen image is the first thing a user sees when they tap your app tile, so you want to make it as engaging and inspiring as you can–make the user happy that they tapped your tile! Help them to look forward to spending time in your app! As one example, I offer the splash screen of Pinball Fx2, an app with which I spent far too much time over the Christmas holidays:

I would almost venture to say that a great splash screen image is one that makes your users wish the app would load faster–and then, of course, you’re in great shape to use an extended splash screen….