BUILD 2015 session recap: API Contracts

Session url: http://channel9.msdn.com/Events/Build/2015/3-733?format=html5

Note: As you might notice in the url above, you have to use the HTML5 format to play this video as the default format isn’t available yet at the time of posting.

Objective: Learn how to check which API is available for the platform you’re targetting.

Adaptive dimensions

There are multiple dimensions in which the target for your app changes:

• Version of the OS / API.
• Device family.
• Form factor (solved by responsive layout).

Why build a version adaptive app? Target the release with the most market share, but be able to target the latest release with its new features.

• Windows is shipping on a more frequent cadence (cfr. Windows as a service).
• What API version do you target: cutting edge users versus slow adopting enterprises.

Why build a device adaptive app? More devices equals a larger potential market.

• ‘Solved’ by a Universal API running accross all device families.
• What about the small differences that still exist? Use “least common denominator” API? How to leverage the device specific capabilities?

In Windows 8, metadata was introduced by the means of attributes to define since which version a particular class/method was introduced (Windows 8 - 8.1) and this was extended to Windows Phone. For the developer it’s quite a task to find the common denominator between Windows and Windows Phone, both version wise as implementation wise.

Dependencies

Portability is a function of dependencies.

• Hardware architecture is not controlling: JS and .NET runs on all, C++ compiles to all.
• Device architecture is not controlling:
  • Mobile may not have telephony or SMS.
  • Mobile may have a large screen (projecting, Continuum, …).
  • Tablet may have a physical keyboard attached.
• An app should run on every device that can satisfy its dependencies.

Code at API intersactions? Lots of different intersections with each new version. Discourages multiple device family support, because it’s hard to reason about API availability.

How to write an adaptive app

For Windows 10, > 85% of WinRT APIs are common and present. But when is an API ‘present’:

• Full functionality is implemented. 
• Partial functionality: API is present but responds in certain expected ways.
  • No exceptions are thrown because of missing pieces.
  • E.g. get the webcams will return an empty set.

What about the ‘optional’ APIs? Determine, at runtime, whether API is available (don’t check for device family!) by using the ApiInformation class.

API Contract

Every Microsoft WinRT API resides in an API Contract, which is:

• a named and versioned set of functionally-related APIs (types, interfaces, properties, …).
• an atomic unit of functionality: all APIs in the contract are implemented or none of them are.
• can be queried at runtime.
• later versions are always backwards compatible.

The actual checking is done with the ApiInformationClass and the code writen below works through static type references, which is only available in Windows 10 and not in .NET 4.5. This code does not compile in Visual Studio 2013 and below.

using Windows.Foundation.Metadata;

// check a single class
if (ApiInformation.IsTypePresent ("Windows.Networking.HttpClient2") {
    HttpClient2 client = new Windows.Networking.HttpClient2();
    // some more code
}

// check a single property on a class
if (ApiInformation.IsPropertyPresent ("Windows.Networking.HttpRequest.SecureSendRequired")) {
    client.SecureSendRequired = true;
}

// check a complete contract instead of all classes one by one
if (ApiInformation.IsApiContractPresent ("Windows.Networking.NetworkingGameBroadcastContract", 2, 0)) {  // ver 2.0
    GameBroadcast gb = new GameBroadcast();
    gb.Announce ();

    GameParty gp = new GameParty();
    GameJoin gj = new GameJoin();
}

Device Family

• an implementation of a selected set of API contracts, also called a ‘Platform’.
• the Universal Windows Platform (UWP) implements the set of universally implemented API contracts (= available everywhere). 
• UWP-based device families (Mobile, Xbox, …) implement
  • all API contracts of the UWP
  • plus possible additional API contracts (unique to that family or not), grouped in Extension SDKs

Extension SDKs

• works on one or more device families. 
• enables Design Time experience, not runtime. SDK specific code won’t compile without adding the reference.
• part of the Windows SDK, may ship at different schedules to enable functionality