Windows Runtime–What’s Supported Where?

As I’m sure you've heard, Windows Phone 8 and Windows Store (nee Metro) applications share a common core operating system, and that’s great news for developers looking to take advantage of both platforms with a single or complementary applications.

The common core does not, however, mean that the platforms are identical – in fact, only about 1/3 of the Windows Runtime API members are available on both platforms, and there are some APIs that are specific to either Windows Phone or Windows 8 due the unique experiences or features of the hardware.

Then, of course, there’s a .NET API available for both Windows Store applications and Windows Phone applications each a somewhat differing subset of the complete .NET API you’ve been using to build Windows Forms, WPF and ASP.NET applications for years.

As someone that’s been transitioning his skills from core .NET development to the Windows Runtime, I share the pain of trying to make that call to API X and finding it’s not supported on Windows 8 (or Windows Phone) or wondering why the namespace that I’ve used for years refused to resolve in a new Windows 8 app.

The good news is that the documentation is there, but there are some subtleties and nuances, so I’ve pulled this post together to outline some of the tricks and links I’ve discovered.

Laundry Lists

First of all, here are the itemized lists of APIs for the new platforms

	Windows (Runtime) API Reference for Windows Store apps .NET for Windows Store apps – supported APIs Win32 and COM for Windows Store apps
	Windows Runtime API adopted from Windows 8 (the “2,800” value above) Phone additions to Windows Runtime API adopted from Windows 8 Phone-only Windows Phone Runtime API (the Windows.Phone namespace) .NET API for Windows Phone Win32 and COM API for Windows Phone 8

If you're like me though, one of your primary research tools is a Bing search, and I'm generally looking for the hit that brings me right to the font of knowledge: the MSDN Library. Once there, it can be a bit tricky to determine if what you're looking at applies to your specific case. Is it available for Windows 8 Store apps? Is it available for Windows Phone? What about Windows Phone 8 versus 7.1?

MSDN Documentation Overview

At the high level, you’ll find yourself dealing with three namespaces:

• Windows – the Windows Runtime namespace. This means it’s available for Windows 8 or Windows Phone 8 (but not necessarily both!)
• System – the core .NET Framework namespace. A subset of this namespace is available for Windows 8 and Windows Phone 8.
• Microsoft – other namespaces related to Microsoft languages and features. Some of these are supported for Windows 8 and Windows Phone 8; some are not.

and if you’re doing native development, of course, you’ll be looking at Win32 API calls.

Windows Namespace

If you see a Windows namespace, you’ll know it’s for use with Windows 8 or Windows Phone 8 applications – but not necessarily both!

Let’s take a look at the LocalFolder property that’s part of the Windows.Storage namespace. If you do a search for LocalFolder, you might end up at one of two landing spots on MSDN. On the left is the documentation page for the LocalFolder property on the Windows Dev Center, and on the right is the documentation for the Windows Phone Dev Center.

Windows Dev Center	Windows Phone Dev Center

This feature is supported on both devices, and you’ll see that the documentation is nearly identical (the Windows Dev Center version provides JavaScript samples, and the phone version does not since JavaScript is not a supported native language on Windows Phone).

At the bottom of each, you’ll see the listing of platform support as well:

If you run into an API on either site, and there’s not a “Minimum supported” section for client or phone, that’s your cue that you’re not dealing with one of the 2800 or so APIs that are shared in the common core.

Unfortunately, the converse isn’t true. Take a look at the page for ApplicationData.RoamingSettings on the Windows Dev Center, and you’ll see a similar statement of support for Windows Phone 8 in the Requirements section.

Try to use that feature in a Windows Phone 8 application with code like the following:

String bar = ApplicationData.Current.RoamingSettings.Values["foo"] as String;

and you’ll get an exception! That’s because the API is technically supported, but it’s not implemented. Bottom line, you can’t use it in a Windows Phone 8 application.

Here’s how you’d know:

• In the Remarks section of the API documentation is the following statement:

• and Intellisense will also indicate you’re on the road to nowhere:

• If you miss all that in your frenzy of coding, rest assured, you’ll be greeted with a System.NotImplementedException at runtime.

System and Microsoft Namespaces

When working with Windows Forms, ASP.NET, WPF, and the other .NET technologies, these two namespaces are your bread and butter. You’ll find a subset of these namespaces available for both Windows 8 and Windows Phone, and there are a few additions to the Microsoft namespace for new features as well (e.g., the Microsoft.Phone namespace). You now could find yourself at three different landing pages, such as the documentation incarnations of System.IO below:

MSDN Library	Windows Dev Center	Windows Phone Dev Center

Of course, if you hit the Windows Dev Center and you’re writing a Windows 8 app, you’re all set; likewise, for the Windows Phone Dev Center when writing a Windows Phone app.

If you end up at the core MSDN Library, there are actually even more choices, since there’s a Version drop down taking you all the way from the current .NET Framework 4.5 back in time to 1.1!

On the page for the .NET Framework 4.5, you’ll notice there are glyphs decorating each of the classes, methods, properties, events, etc. The first should be familiar – it differentiates classes from structures from delegates from enumerations and so on, but there are a couple of new glyphs too, as noted below:

This shows that both BinaryReader and BinaryWriter are available (in whole or part) for Windows Store apps, and they are also supported in Portable Class Libraries. Support of a feature in a portable class library bodes well for being able to reuse code across multiple platforms, such as Windows 8 and Windows Phone 8; however, it doesn’t guarantee it. While .NET and Windows Store have a considerable amount of overlap in support, as you add additional options – like Windows Phone – to your portable class library target frameworks, the combined API surface decreases.

Looking more closely at BinaryReader, the Version Information section (toward the bottom of the page) provides additional detail on the applicability of the class:

This works well for Windows Store applications, but you’ll note that there is no mention of Windows Phone support here, even though BinaryReader is absolutely supported on that platform. In fact, Directory, which is neither available for Windows Store nor for use in a portable class library is supported in Windows Phone, yet the core MSDN documentation wouldn’t really clue you in to that.

Win32

If you’re using Win32 APIs, let’s use FlushFileBuffers as an example, Windows Store support is noted in the Requirements section at the end of the documentation page.

FlushFileBuffers is also available on Windows Phone 8 though. And the way you’d know that is by looking more closely at the Remarks section which includes this callout:

As you might note, that's nearly the opposite approach as taken for the Windows namespace, where the Requirements section may indicate support for Windows Phone 8 but the Remarks section shows it’s actually not implemented and will thrown an exception.

TL;DR

If you’ve read the entire post, that's probably more info than you cared to know, and I do suspect the various documentation 'centers' will align as they evolve over time. For now, if you're just writing Windows Store apps, be sure to navigate to the Windows Dev Center pages; likewise, visit the Windows Phone Dev Center if you're just writing Windows Phone 8 apps.

But, if you’re working to reuse your code across both target platforms, you may want to file this post away so you can properly decode what you can and can’t use across the two.