It’s very important–thought easy to overlook–that you test your app under varying levels of network connectivity, or at least consider what they might mean for your design. Those levels are:

  • Full connectivity to the Internet, with unmetered data and high speed transfers. This is the situation that we typically assume, because it means unrestricted access to network resources and whatever data we might want to acquire or share.
  • Limited connectivity (local network only). This is where there could be some access to resources on other local devices, but Internet resources are not available. This would only be a concern for apps that are specifically written to communicate with themselves or related apps on a local network (via IP addresses and mechanisms like sockets) and are not relying on remote resources from http[s] sources and such.
  • Connectivity with high latency. This means having connectivity to the resources you need, but the data comes down slowly, perhaps much more slowly that you expect. This is a concern where overall app performance is concerned. For example, an app might assume that it can just wait until the data is available to refresh its display and not show anything like progress indicators and such to tell the user that the app is waiting for some operation to complete. I’ve seen apps that assume they get their data in short order, but when there are timeouts or other such problems, the app becomes unresponsive or uninformative. Apps that do a better job have built-in resiliancy to timeouts, builthave -in retry mechanisms, and keep the user updated as to the status of network connectivity. (As an example, some of the system UI will say things like “Connecting to a network is taking longer than usual” with an option to cancel.
  • No connectivity (local or internet). This is the most important one to consider, becaue many apps, assuming the best where connectivity is concerned, are not written to gracefully handle the lack or loss of connectivity, and oftentimes just end up in a state where they appear hung. Worse still, some apps just fail to deliver any meaningful user experience without connectivity and give no suggestion that connectivity might be the problem. A bad app in this regard fails to give the user a means to retry whatever they might have done earlier, if they’ve taken steps to remedy connectivity problems. In these cases, the user is forced to close the app and launch is again, hoping for the best.
  • Metered connectivity (typically a mobile broadband network that might be pay-as-you-go or possibly nearing its data limit). The Store certification requirements state that apps that do large transfers need to be sensitive to possible overage charges. See section 4.5 of those requirements for details. Fortunately, the Background Transfer APIs in WinRT pay attention to this, but if you’re using your own mechanisms you’ll need to be attentive to metered situations.
  • Roaming a device between networks. For the most part, apps don’t need to concern themselves with this if they’re handling the other situations above. Windows itself automatically handles roaming to a new network and choosing the best one of those available. Sometimes this means entering a metered network, sometimes it means leaving one. Sometimes the network speed will increase, other times it will decrease.

You might also consider airplane mode, meaning that wi-fi is disabled by a wired network could still be used, though this is generally a case of “no connectivity” above when a wired connection doesn’t exist.

Whatever the case may be, the important event to know about and listen to is the Windows.Networking.NetworkInformation.onnetworkstatuschanged event. This is fired whenever there’s a change in connectivity, including cost. Similar to this event is aso the networkStatusChange background task trigger, which you can use to execute a small piece of background task code for this condition if the app itself is suspended or not running.

In the former case, you can learn more about the details from the Network information sample; in the latter, refer to the Network status background sample. I discuss these topics in more depth in Chapter 14 and 13 (respectively) of Programming Windows 8 Apps in HTML, CSS, and JavaScript.

 

Now knowing what conditions to test for is one thing; the second part is knowing when to test for these, that is, what app states to test along with the different levels of connectivity. The primary ones here are:

  • During first startup: what happens if the app is launched (from its tile and through whatever contracts it supports, such as Search and being a Share target)?
  • During subsequent startup: same tests as above, but now with the possibility that previously-cached data is available for offline use.
  • While the app is running; what happens when connectivity levels change while the app is active? This is important to test both on single pages that might make network requests, and especially on page transitions where the app might be making network requests to populate the new page with data.

The most reliable and robust apps will respond to different conditions at these different times in such a way that the user is never left confused as to what’s going on and what they might be able to do about it. The worst thing for an app is where the user ends up staring at a blank screen without any idea of what might be wrong. I’ve seen this with some apps, where I tried to launch them in airplane mode after just installing them while waiting for a flight, or when I run the app after having travelled somewhere and not having connected to the Internet yet.

It’s also very confusing when the app is working just fine, but goes through an indeterminate visual state while waiting for its data. Let’s say that you have the kind of app that shows a list of search results, then navigates into a details page for one of those items. Let’s say that under normal conditions that list of results comes down within half a second and acquiring the details within a similar timeframe. With those timings, the app doesn’t need to pay attention to visual details going between the results and details pages. However, increase those times to two seconds or more and a user could see blank screens or otherwise unresponise UI for too long a time. This could easily happen when the user is in a hotel or other situation with a shared internet connection that is handling many demands from multiple users. It could also happen where the servers providing all that data are slow to respond for whatever reason (say, a problem at one data center that is placing a larger-than-usual demand on the others).

The answer to such times may be as simple as putting up a progress indicator or other message that tells the user to wait a bit (something that’s good to do after two seconds of waiting). But these things often need to be designed, and should involve whatever designers you worked with on the rest of the app’s UX because such things are, in the end, part of that user experience. This is important to understand, because you often don’t see the need for such designs until you’re well into development and testing of the app. So be sure that you can go back to your designers for some of these concerns when you need to.

In some cases you can eliminate some of the delays with clever implementation. In apps with results-details pages, it’s not necessary to completely navigate away from the results page to show the details page, that is, it’s not necessary to tear down the results page when showing the details page. Instead, just create and show the details page on top of the results page. In HTML/CSS, this just means placing a full-screen div for the details page over the top of the results page. That way, when navigating back to the results page, which is often a very common activity, you just hide or tear down the details page, letting the pre-existing results page just become visible again. (You’ll want to determine how long it’s been since it was last visible, in case it’s appropriate to refresh the data.) This way you avoid most needs to reacquire the data for that page, thus eliminating a case where connectivity is a concern.

Whenever you acquire data, too, consider caching it in some way so that you can start the app again without connectivity and have something meaningful to show. There have been times where I know I’ve been using an app, as I have a website, and wanted later to return to that same data/page to see something again. So if connectivity has been lost, and the app is reloading that previously saved data, then I get to see something familiar instead of a blank page and a message saying there’s nothing to show. With cached data, at least I can see and interact with what I saw before, which may, in fact, be exactly what I wanted.

 


Access to the file system on the local device is an increasingly important capability for apps that interact with the user and the user’s data on that file system. Until APIs were added to HTML5, client-side JavaScript code in web apps did not have much access to the file system except through plug-ins, which are not necessarily supported in all browsers. For Windows Store apps, access to the file system is of course a very important need, so there are extensive APIs for this purpose as well as protections for that file system. As we’ll see, Windows Store apps really need to use the WinRT APIs to work within those protections; the HTML5 file APIs are of only limited used.

This comparison is different from others posted here in that the HTML APIs and WinRT APIs really address different uses and purposes; they do not overlap as other APIs we’ve compared.

Note: a key difference for any comparison with WinRT APIs is that HTML 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 are limited to HTML5/JS APIs.

 

HTML File API and File System API

HTML5 has two emerging standards for file-related APIs: the File API and the File System API.

The File API, a working draft at the time of writing, is oriented around handling of filenames that a user provides in a form, typically for upload purposes. It’s entirely oriented around the workflow of obtaining one or more filenames through <input type=”file”> elements, then asynchronously accessing the contents of those files in various forms (text, binary, array, and URL). It is not intended to be a generic means of accessing files, and provides reading capabilities only. Files, in fact, are represented by a File object type that only surfaces the name, not the path, of the files—the API, in other words, hides those details that are specific to the underlying operating system.

The File System API, also a working draft (and not generally available to apps at this time), provides for more general read/write access to “a sandboxed section of the user’s local file system.” The API provides for folder operations like moving, copying, deleting, and creating files, as well as reading and writing files. The API provides both synchronous and asynchronous forms.

 

WinRT File API

The Windows.Storage API is intended as the means of asynchronous file system access for Windows Store apps. The API is fully aware of app container restrictions, brokering, and restrictions placed on the app by the capabilities (or lack thereof) as declared in the manifest. It provides for reading and writing to arbitrary files (if access is allowed) as well as to app-specific data folders (local, roaming, and temp) and user data libraries (music, pictures, videos, and documents, with the latter having additional requirements).

Unlike the working draft HTML5 File System API, the WinRT API is completely available to app Windows Store apps today. The capabilities also go far beyond the HTML5 specifications. WinRT provides a file picker that allows the user to point to and thus give permission to apps to use any non-sensitive area of the file system. Apps can cache this permission for future access through the Windows.Storage.AccessCache APIs.

WinRT also provides capabilities to perform deep and detailed searches of the file system through file queries (see Windows.Storage.StorageFolder). Furthermore, WinRT is designed to accommodate the needs of online storage systems (e.g. SkyDrive) and local caching of files obtained from those systems.

 

Recommendations

If an app wishes, it can use the HTML5 File API for its intended and specific purpose, that is, for an <input type=”file”> form field and resulting data transfer. It should be noted that using this method, the app will only have the ability to use the methods in the HTML FileReader object to read data from the file; if any other capabilities are needed, the app should collect pathnames directly through the WinRT file picker and use the Windows.Storage API for reading (and/or writing). This is because the paths are otherwise hidden (and not accessible) in the HTML File objects.

The HTML File System APIs, for their part, are not presently available to Windows Store apps at all (they are only available in Google Chrome at present). At such a time that the standard becomes more finalized, it would seem an open question as to how the API would operate. Generally speaking, since the File System API is designed to provide access to an app-specific section of the file system, as is already provided by Windows.Storage.ApplicationData, making such an API available to Windows Store apps would seem both redundant and pointless, since WinRT already provides a much richer set of features.


I worked directly with Sonoma Partners in late 2011 and early 2012 when they worked on the first enterprise app for Windows 8, specifically for New Belgium Brewery. I found this recent post of their blog which clarifies that for HTML, you generally don’t want to use self-closing tags. They had all kinds of trouble with a self-closed iframe. See http://blog.sonomapartners.com/2013/02/missing-some-content-in-your-windows-8-htmljs-app.html.

 


Along with testing the functionality of your app, it's also important to do performance testing on a variety of machines to make sure that your implementation is flexible enough to handle differences in processor speeds (for work on the UI thread) and GPU capabilities (especially affecting animations and rendering). Testing on different network speeds can also be helpful if you rely on online content–testing on a slow network, for example, can reveal the need to use progress controls in key places of your app (so the user doesn't think it's just hung). It can also help reveal places where you might implement strategies to avoid progress controls altogether, such as caching page content or switching between pages just with changes in visibility and not tearing down and rebuilding pages each time.

In any case, I wanted to provide some links to resources over a few posts. Here are a few topics in the docs for starters:

Performance (Windows Store Apps) – all languages

General Best Practices for Performance – all languages

Performance Best Practices – JavaScript

Performance Best Practices – C++, C#, VB, XAML

You'll also want to look at Tool: Performance Analyzer (JavaScript), which is one of the key tools to use for this task.

More to come later on–this is probably enough for you to chew on at present!

 


If you look around within the WinJS source code files, you’ll see a curious structure for commenting functions. For example, here’s what we see for WinJS.Namespace.define:

function define(name, members) {
    /// <signature helpKeyword=”WinJS.Namespace.define”>
    /// <summary locid=”WinJS.Namespace.define”>
/// Defines a new namespace with the specified name.
    /// </summary>
    /// <param name=”name” type=”String” locid=”WinJS.Namespace.define_p:name”>
    /// The name of the namespace. This could be a dot-separated name for nested namespaces.
    /// </param>
    /// <param name=”members” type=”Object” locid=”WinJS.Namespace.define_p:members”>
    /// The members of the new namespace.
    /// </param>
    /// <returns type=”Object” locid=”WinJS.Namespace.define_returnValue”>
/// The newly-defined namespace.
/// </returns>
/// </signature>
return defineWithParent(global, name, members);
}

On first glance, you’ll wonder why someone wrote comments like this that are somewhat hard to read. But there is a real purpose: they are what provide IntelliSense data to Visual Studio. That is, because IntelliSense provides you with immediate, in-line documentation when you start writing code, there’s no need for you to look at the source code for functions that you’re consuming to understand how they work. That is, when you type out WinJS.Namespace. and highlight define, you’ll see this pop up:

Intellisense comments 1b

When you continue to enter in define, IntelliSense will pop up the details of the function–you can see that all this information is coming straight from those code comments:

Intellisense comments 2b

There is nothing special about WinJS’ use of these kinds of comments: you can use them in your own code to provide IntelliSense for your own functions. The documentation for doing this is on JavaScript IntelliSense (the overview) and XML Documentation Comments (the details). Here’s a simple example with a function that doesn’t actually do anything meaningful:

function myFunction(item, identifier, options) {
    /// <signature helpKeyword=”MyNamespace.myFunction”>
    /// <summary locid=”MyNamespace.myFunction”>
    /// Does some nifty stuff with the parameters you provide.
    /// </summary>
    /// <param name=”item” type=”Object” locid=”MyNamespace.myFunction_p:item”>
    /// The object to process.
    /// </param>
    /// <param name=”identifier” type=”String” locid=”MyNamespace.myFunction_p:identifier”>
    /// Another parameter that I just made up.
    /// </param>
    /// <param name=”options” type=”Object” locid=”MyNamespace.myFunction_p:options”>
    /// A fine ubiquitous catch-all parameter.
    /// </param>
    /// <returns type=”Object” locid=”MyNamespace.myFunction_returnValue”>
    /// Whatever it is we emit from this function.
    /// </returns>
    /// </signature>
    item.identifier = identifier;
    item.options = options;
    return item;
}

Now when you start typing out myFunction(, you’ll see this:

Intellisense comments 3

As you enter each parameter, the bold highlight in the first line will change and the description at the bottom will update as well.

The other piece to this story is that if you’re working in another .js file and referencing functions in another, you’ll want to add a reference comment at the top to those other files:

/// <reference path=”ScriptFile1.js” />

This is what tells Visual Studio to scan that other file and extract those IntelliSense comments from it. You’ll see this at the top of the WinJS file ui.js, in fact:

/// <reference path=”ms-appx://Microsoft.WinJS.1.0/js/base.js” />
/// <reference path=”ms-appx://Microsoft.WinJS.1.0/js/ui.js” />

 


Besides having great design and great execution in coding the features of an app, one of the other most important aspects is good testing. Indeed, if you look at Microsoft's own engineering structure, it's composed of the 'triad' of Program Management (handling requirements and design), Development (handling implementation), and Testing (handling quality assurance, performance, and functional proof). Be that as it may, the available resources for developing Windows Store apps are plentiful on the first two but somewhat lacking on the latter. So with this post I want to start providing some tips to functional testing in particular, and I'll also be providing some resources for performance work along the way.

For the first tip, I'll mention something that should be obvious but can be easily overlooked: when testing your app, be sure to try it on fresh machines where you've just installed Windows anew (or at least a virtual machine). And I do mean "machines," not just one: you should always test on a variety of hardware to see how your app performs.

The core reason for this is that installing on a fresh machine is exactly what the Windows Store certification testers will be doing (on a virtual machine), and what your customers will be doing as well. It means that there won't be anything whatsoever related to your app already on that machine, such a caches or existing state.

We encountered this with one of our early app partners in 2012, leading up the Windows 8 Consumer Preview. The developer working on this app (there was just one, and no testers!) saw everything running beautifully, so he submitted the app for certification. It failed because the home page came up entirely blank. It did that for me as well. The reason: on the developer's machine he had already cached the home screen's contents, so it was showing up fine, and he'd neglected to test on a fresh machine.

It was a simple fix, but the oversight caused a painful delay in certification.


Having covered the basics of WinJS.Class.define in Part 1 and WinJS.Class.derive in Part 2, we come to the third method in WinJS.Class, which is the mix method.

Let’s first see what differentiates a mixin from a derived class. When you derive one class from another, the new class is the combination of the base class’ members and those additional ones you specify for the derivation. In WinJS.Class.derive, you can only specify one base class.

In object-oriented programming, there is the concept of multiple inheritance whereby you can derive a class from multiple base classes. This is frequently used to attach multiple independent interfaces on the new class (it’s used all the time in Win32/COM programming, where an interface is typically defined as a virtual base class with no implementation, and provides the necessary function signatures to the derived class).

As JavaScript itself doesn’t have object-oriented concepts baked into the language–thus necessitating helpers like WinJS.Class.define to play the necessary tricks with prototypes and all that–there isn’t a built-in method to express multiple inheritance.

Hence the idea of a mix or mixin, which isn’t unique to WinJS as evidenced by this article on WikipediaWinJS.Class.mix is basically a way to do something like multiple inheritance by simply mixing together all the instance members of any number of other mixin objects. The description in the documentation for WinJS.Class.mix puts it this way: “Defines a class using the given constructor and the union of the set of instance members specified by all the mixin objects. The mixin parameter list is of variable length.”

So here we see two other differences between a mix and a derivation: a mix does not operate on static members, and does not concern itself with any constructors other than the one given directly to WinJS.Class.mix. (This is also why it’s not true multiple inheritance in the strict object-oriented sense.)

WinJS itself uses the mixing concept for its own implementation. If you look in the docs, you’ll see that there are several mixins in WinJS that you can use yourself: WinJS.UI.DOMEventMixinWinJS.Utilities.eventMixinWinJS.Binding.observableMixin, and WinJS.Binding.dynamicObservableMixin:

  • WinJS.UI.DOMEventMixin contains standard implementations of addEventListener, removeEventListener, dispatchEvent, and setOptions, which are commonly used for custom controls. If you look in the WinJS file ui.js, you’ll see that all the WinJS controls bring this into their mix.
  • WinJS.Utilities.eventMixin is basically the same thing without setOptions, as it is meant for objects that don’t have associated UI elements (it also can’t just use the listener methods on the element in the DOM, so it has its own implementation of these methods).
  • WinJS.Binding.observableMixin adds functionality to an object that makes it “observable” meaning that it can participate in data binding. This consistes of methods bind, unbind, and notify. This is used with the WinJS.Binding.List class.
  • WinJS.Binding.dynamicObservableMixin builds on the idea with methods called setProperty, getProperty, updateProperty, addProperty, and removeProperty. This is helpful for wiring up two-way data binding, something that WinJS doesn’t do itself, but isn’t too hard to pull together. The Declarative binding sample in the SDK shows how.

With events (in the first two mixins), you commonly use WinJS.Utilities.createEventProperties to also create all the stuff a class needs to support named events. createEventProperties returns a mixin object that you can then use with WinJS.Class.mix. For example, if you pass this method an array with just [“statusChanged”] when you’ll get a function property in the mixin names onstatuschanged and the ability to create a listener for that event.

So mixins, again, are a way to add pre-canned functionality to a class, and is a convenient way to modularive code that you’ll use in multiple classes. It’s also good to know that you can call WinJS.Class.mix multiple times with additional mixins, and the results simply accumulate (if there are duplicates, the last member mixed is the one retained).

 


In contrast to other posts in this series of HTML5/WinRT comparisons, this one on web sockets is relatively short. I haven’t worked too much with either set of APIs, so only have a few details to write up.

Standard WebSockets, as they’re defined in the W3C/HTML5 API, are entirely supported for Windows Store apps. However, they support only a transaction-based UDP model like DatagramSocket and only text content. The MessageWebSocket in WinRT supports both text and binary, plus you can use the StreamWebSocket for a streaming TCP model as well. The WinRT APIs also emit more detailed error information.

For all these reasons, we generally recommend using the WinRT APIs for web sockets over the HTML5 APIs.