Figure 1-1 shows the three technology stacks you can use to create a Windows Store app. The bottom of the figure shows a large rectangle titled “Windows.” This box indicates the various features that Windows exposes to developers. On the right, the “Win32 and COM” box represents APIs that have shipped with Windows for many versions now; these technologies continue to ship in order to support desktop apps. The Win32 and COM APIs are old and complicated. Furthermore, they were designed to be used by native C/C++ developers. The WinRT box on the left represents the new WinRT APIs. WinRT is a modern, simple, and object-oriented API designed for use by many programming languages. By the way, the boxes are not shown to scale: there are far more Win32 and COM APIs than there are WinRT APIs.

Technically speaking, all the Win32, COM, and WinRT APIs are callable from both desktop apps as well as Windows Store apps. However, the WinRT APIs are simpler and easier to use, so you should use them whenever possible. And although a Windows Store app can call any Win32 or COM API, many of them will fail due to the app container’s security context. Other Win32 and COM APIs should not be called because their use violates the principles presented earlier. In fact, Microsoft created an approved list of Win32 and COM APIs that a Windows Store app is allowed to use. (See http://msdn.microsoft.com/en-us/library/windows/apps/br205757.) If your Windows Store app uses any Win32 or COM API not on the approved list, your app will fail Windows Store certification.

Figure 1-1. Window Store app technology stacks.

The main purpose of an operating system is to abstract hardware devices to the application developer. For example, a PC can store files on a hard disk, an SSD drive, a USB drive, a DVD, a network share, and so on. The OS abstraction for this is a file, and an app developer can simply write code that opens a file and reads its contents. The app developer doesn’t have to know what kind of hardware device contains the file and how to communicate with that device. If you look closely at the WinRT APIs, you’ll see that many of them are about abstracting hardware devices—although there are a few APIs (like the Application Model APIs) related to managing your app within the system.

Microsoft supports three different technology stacks that developers can use to build Windows Store apps: native C/C++, .NET (C# and Visual Basic), and JavaScript. Each technology stack has its own programming language, supporting class libraries, presentation layer, and optionally an execution engine or virtual machine. Now, let me explain each technology stack (as shown in Figure 1-1):

Developers commonly ask which language or framework is the best one to use when building a Windows Store app. For the most part, Microsoft encourages developers to use what they already know. The WinRT API is equally exposed to the three technology stacks, but there are reasons you might prefer one stack over another:

The WinRT APIs that ship as part of Windows are all written in native C/C++, which makes sense for platform code because it has to be fast and use as little memory as possible. However, these WinRT APIs are callable from C/C++, C#, Visual Basic, and JavaScript. To call WinRT APIs from all these languages, a small and simple type system had to be defined. This type system must use features available to all consuming programming languages. Here are the core concepts you need to know to consume the Windows Runtime type system from C#:

In addition, the WinRT type system supports delegates, methods, properties (but not indexer properties), events, exceptions, and arrays (single-dimension, 0-based only). It also allows collections created in one language to be passed to and accessed from another language. For more information about the Windows Runtime type system, see my CLR via C#, Fourth Edition book (Microsoft Press, 2012). In Chapter 25, “Interoperating with WinRT Components,” I explain how to define your own WinRT components in C# and consume them from other languages, such as C++ or JavaScript.

How is it possible for the various programming languages to know about and call WinRT APIs? There must be some description of the APIs consumable by all the languages. In the .NET Framework, code written in one language can interoperate with types written in a different language because of metadata. The metadata is programming-language-agnostic information that describes types and their members. Microsoft’s WinRT team uses the same metadata format (ECMA-335) created by Microsoft’s .NET team. That is, the Windows SDK ships with a DLL containing metadata describing all the WinRT components that ship with Windows itself. This DLL has a WinMD file extension (which stands for Windows MetaData), and Visual Studio automatically adds a reference to this WinMD file when you create a new Windows Store app project. The WinMD file is typically found here:

Because this file is just like a normal .NET assembly, you can use standard .NET utilities (such as ILDasm.exe or Reflector.exe) to open this file and explore its contents. Of course, because the WinRT APIs are written in native code, this WinMD file does not contain any IL code; it contains only metadata.

When compiling a native C/C++ app, the compiler itself parses the Windows.WinMD file, making the WinRT APIs callable to native C/C++ apps. Similarly, when developing a C# or Visual Basic app, the compiler parses the Windows.WinMD file, ensuring that our code calls the WinRT APIs correctly. At runtime, the CLR uses different WinMD files installed in the %WinDir%System32WinMetadata directory. Having separate, smaller WinMD files at runtime decreases the memory needed by apps because few apps (if any) will use all of Windows’ WinRT components. When running a JavaScript app, Internet Explorer’s virtual machine (VM) also parses the WinMD files, making the WinRT APIs callable to JavaScript code.

What’s happening here is that the C++ compiler, the C# and Visual Basic compilers, the CLR, and Internet Explorer’s VM are all parsing the same WinMD files and then they project the APIs using the Windows Runtime type system as if they were implemented using the C/C++ type system, the CLR’s type system, or the JavaScript type system, respectively. This way, the developer consuming the WinRT APIs has a familiar and natural experience when working with the APIs. Let’s look at an example. Here is some C# code that calls WinRT APIs to open a file and read its contents:

using System;          // .NET Framework Class Library
using Windows.Storage; // Most Windows.* namespaces are for WinRT APIs
using Windows.UI.Popups;
private async void ReadText() {
   var filename = "MyFile.txt";
   StorageFolder folder = ApplicationData.Current.LocalFolder;
   StorageFile file = await folder.GetFileAsync(filename);
   String text = await FileIO.ReadTextAsync(file);
   MessageDialog dialog = new MessageDialog(text, "File's Text");
   await dialog.ShowAsync();
}

You don’t need to understand what this code actually does. What is important to understand is that this code uses lots of WinRT APIs (StorageFolder, StorageFile, ApplicationData, FileIO, and MessageDialog) but the code looks like you’re just consuming ordinary .NET types.

Here’s the same function written in native C++:

using namespace Windows::Storage;
using namespace Windows::UI::Popups;
void SimpleSampleCx::MainPage::ReadText() {
   auto filename = "MyFile.txt";
   create_task(ApplicationData::Current->LocalFolder->GetFileAsync(filename))
      .then([this](StorageFile^ file)  {
         create_task(FileIO::ReadTextAsync(file)).then([this](String^ txt) {
            MessageDialog^ dialog = ref new MessageDialog(txt, "File's Text");
            dialog->ShowAsync();
         });
      });
}

Readers familiar with C++/CLI might think this is actually managed code because it is using ref new and ^. It is not. The syntax used is called C++ Component eXtensions, or C++/CX. It is a set of extensions to the C++ language, making it syntactically easy to invoke WinRT APIs.^[11]

And here’s the same function written in JavaScript:

function readText() {
   var filename = 'MyText.txt';
   var localFolder = Windows.Storage.ApplicationData.current.localFolder;
   localFolder.getFileAsync(filename).then( function(file){
      Windows.Storage.FileIO.readTextAsync(file).then( function(txt){
         var dialog = new Windows.UI.Popups.MessageDialog(txt, "File's Text");
            dialog.showAsync();
      })
   });
}

Notice that in JavaScript the first letter of the WinRT methods start with a lowercase letter (like getFileAsync). This is how the Internet Explorer VM projects the WinRT API methods to the JavaScript developer. This gives the developer a natural experience because initial lowercase letters is a standard convention in JavaScript. For .NET developers, there are two kinds of projections:

When a thread performs an I/O operation synchronously, the thread can block for an indefinite amount of time. When a GUI thread blocks for an I/O operation to complete, the application’s user interface stops responding to user input—such as touch, mouse, and stylus events—causing the user to get frustrated with the application. To keep apps responsive, WinRT components that perform I/O operations expose the functionality via asynchronous APIs exclusively. In fact, WinRT components that perform compute operations also expose this functionality via asynchronous APIs exclusively if the CPU operation could take greater than 50 milliseconds. For more information about building responsive applications, see Part V, “Threading,” of CLR via C#, Fourth Edition by Jeffrey Richter.

Because the WinRT APIs are mostly about abstracting hardware, many APIs perform I/O operations; therefore, many WinRT APIs are asynchronous. So, for you to be productive with them requires that you understand how to work with them from C#. To understand it, examine the following code:

public static void WinRTAsyncIntro() {
   IAsyncOperation<StorageFile> asyncOp = KnownFolders.MusicLibrary.GetFileAsync("Song.mp3");
   asyncOp.Completed = OpCompleted;
   // Optional: call asyncOp.Cancel() sometime later
}
// NOTE: Callback method executes via GUI or thread pool thread:
private static void OpCompleted(IAsyncOperation<StorageFile> asyncOp, AsyncStatus status) {
   if (status == AsyncStatus.Canceled) {
      // Process cancellation...
   } else {
      try {
         StorageFile file = asyncOp.GetResults();  // Throws if operation failed
         // Process result (do something with file)...
      }
      catch (Exception ex) {
         // Process exception...
      }
   }
   asyncOp.Close();
}

The WinRTAsyncIntro method invokes the WinRT GetFileAsync method to find a file in the user’s music library. All WinRT APIs that perform asynchronous operations are named with the Async suffix, and they all return an object whose type implements a WinRT IAsyncXxx interface—in this example, an IAsyncOperation<TResult> interface where TResult is the WinRT StorageFile type. This object, whose reference I put in an asyncOp variable, represents the pending asynchronous operation. Your code must somehow receive notification when the pending operation completes. To do this, you must implement a callback method (OpCompleted in my example), create a delegate to it, and assign the delegate to the asyncOp’s Completed property. Now, when the operation completes, the callback method is invoked via some thread (not necessarily the GUI thread). If the operation completed before assigning the delegate to the OnCompleted property, the system invokes the callback as soon as possible. In other words, there is a race condition here, but the object implementing the IAsyncXxx interface resolves the race for you, ensuring that your code works correctly.

As noted at the end of the WinRTAsyncIntro method, you can optionally call a Cancel method offered by all IAsyncXxx interfaces if you want to cancel the pending operation. All asynchronous operations complete for one of three possible reasons: the operation runs to completion successfully, the operation is explicitly canceled, or the operation results in a failure. When the operation completes due to any of these reasons, the system invokes the callback method, passing it a reference to the same object that the original XxxAsync method returned and an AsyncStatus. In my OnCompleted method, I examine the status parameter and either process the result due to the successful completion, handle the explicit cancellation, or handle the failure.^[13] Also, note that after processing the operation’s completion, the IAsyncXxx interface object should be cleaned up by calling its Close method.

Figure 1-2 shows the various WinRT IAsyncXxx interfaces. The four main interfaces all derive from the IAsyncInfo interface. The two IAsyncAction interfaces expose a GetResults method with a void return type. If the operation failed, this method throws an exception that you can catch, allowing your error-recovery code to execute. The two IAsyncOperation interfaces expose a GetResults method with a non-void return type. Calling this method returns the result of the operation or throws an exception if the operation failed.

The two IAsyncXxxWithProgress interfaces allow your code to receive periodic progress updates as the asynchronous operation is progressing through its work. Most asynchronous operations do not offer progress updates, but some do (like background downloading and uploading, which are discussed in Chapter 7). To receive periodic progress updates, you define another callback method in your code, create a delegate that refers to it, and assign the delegate to the IAsyncXxxWithProgress object’s Progress property. When your callback method is invoked, it is passed an argument whose type matches the generic TProgress type. We’ll show an example of this in the Cancellation and progress section.

Figure 1-2. WinRT’s interfaces related to performing asynchronous I/O and compute operations.

using System;   // Required for framework projection extension methods defined
                // by the WindowsRuntimeSystemExtensions class
...
// NOTE: If invoked by a GUI thread, all code executes via that GUI thread:
public async static void WinRTAsyncIntro() {
   try {
      StorageFile file = await KnownFolders.MusicLibrary.GetFileAsync("Song.mp3");
      // TODO: Completed code
   }
   catch (SomeOtherException ex) {
      // Error code
   }
}

namespace System {
   public static class WindowsRuntimeSystemExtensions {
      public static TaskAwaiter GetAwaiter(
         this IAsyncAction source);
      public static TaskAwaiter GetAwaiter<TProgress>(
         this IAsyncActionWithProgress<TProgress> source);
      public static TaskAwaiter<TResult> GetAwaiter<TResult>(
         this IAsyncOperation<TResult> source);
      public static TaskAwaiter<TResult> GetAwaiter<TResult, TProgress>(
         this IAsyncOperationWithProgress<TResult, TProgress> source);
   }
}

namespace System {
   public static class WindowsRuntimeSystemExtensions {
      public static Task AsTask<TProgress>(this IAsyncActionWithProgress<TProgress> source,
         CancellationToken cancellationToken, IProgress<TProgress> progress);
      public static Task<TResult> AsTask<TResult, TProgress>(
         this IAsyncOperationWithProgress<TResult, TProgress> source,
         CancellationToken cancellationToken, IProgress<TProgress> progress);
      // Simpler overloads not shown here
   }
}

using System;        // For WindowsRuntimeSystemExtensions's AsTask
using System.Threading;    // For CancellationTokenSource
internal sealed class MyClass {
   private CancellationTokenSource m_cts = new CancellationTokenSource();
   // NOTE: If invoked by a GUI thread, all code executes via that GUI thread:
   private async void MappingWinRTAsyncToDotNet(WinRTType someWinRTObj) {
      try {
         // Assume XxxAsync returns IAsyncOperationWithProgress<IBuffer, UInt32>
         IBuffer result = await someWinRTObj.XxxAsync(...)
            .AsTask(m_cts.Token, new Progress<UInt32>(ProgressReport));
         // TODO: Completed code
      }
      catch (TaskCanceledException) { // Derived from OperationCanceledException
         // TODO: Cancel code
      }
      catch (SomeOtherException) {
         // TODO: Error code
      }
   }
   private void ProgressReport(UInt32 progress) {
      // Update progress code
   }
   public void Cancel() { m_cts.Cancel(); } // Called sometime later to cancel
}

StorageFile file = KnownFolders.MusicLibrary.GetFileAsync("Song.mp3")
   .AsTask().GetAwaiter().GetResult();

StorageFile file = KnownFolders.MusicLibrary.GetFileAsync("Song.mp3").AsTask().Result;

private async void OnSuspending(object sender, SuspendingEventArgs e) {
   // A deferral tells Windows the thread may return but the work is not done
   var deferral = e.SuspendingOperation.GetDeferral();
   // TODO: perform async operation(s) here...
   var result = await XxxAsync();  // Thread returns but app is NOT suspended
   deferral.Complete(); // Now, tell Windows we're done (app is suspended)
}

Windows.ApplicationModel.SuspendingDeferral
Windows.ApplicationModel.Background.BackgroundTaskDeferral
Windows.ApplicationModel.Calls.LockScreenCallEndCallDeferral
Windows.ApplicationModel.DataTransfer.DataProviderDeferral
Windows.ApplicationModel.DataTransfer.DataRequestDeferral
Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestDeferral
Windows.ApplicationModel.Search.SearchSuggestionsRequestDeferral
Windows.Devices.Printers.Extensions.PrintTaskConfigurationSaveRequestedDeferral
Windows.Devices.SmartCards.SmartCardPinResetDeferral
Windows.Graphics.Printing.PrintTaskRequestedDeferral
Windows.Graphics.Printing.PrintTaskSourceRequestedDeferral
Windows.Media.PlayTo.PlayToSourceDeferral
Windows.Storage.SetVersionDeferral
Windows.Storage.Pickers.Provider.PickerClosingDeferral
Windows.Storage.Pickers.Provider.TargetFileRequestDeferral
Windows.Storage.Provider.FileUpdateRequestDeferral
Windows.UI.StartScreen.VisualElementsRequestDeferral

private void OnSuspending(object sender, SuspendingEventArgs e) {
   // TODO: perform blocking async operation(s) here...
   var result = XxxAsync().AsTask.GetAwaiter().GetResult();
}  // App is suspended