In this blog post, we talk about what you need to know to build your own Windows Runtime components.

The basics

The Windows Runtime is at the heart of empowering language choice. It exposes so that you can call them from JavaScript, C++, C# and Visual Basic in a way that’s natural and familiar. This same foundation is available to you when building your own APIs too.

A Windows Runtime component that you build and package in your app is typically referred to as a 3^rd party Windows Runtime component. This differs from 1^st party components that are already part of the Windows 8 platform. You can write these 3^rd party Windows Runtime components in C++, C# or Visual Basic. You can call into the APIs they expose from anywhere, including other Windows Runtime components packaged into your app. You can also call into the APIs exposed via Windows Runtime components from any language.

The Windows Runtime components that you write for your app can use Windows Runtime APIs, Win32, COM, .NET APIs or 3^rd party libraries as long as they are supported for Metro style app development. Note that the Windows Runtime components that you build are different from what you traditionally know as C++ DLLs or .NET assemblies that expose APIs. Creating a class library in .Net or a standalone DLL in C++ is not the same as building a Windows Runtime component. Windows Runtime components are declared in .wnmd files that expose Windows Runtime metadata and enable languages such as JavaScript to naturally consume Windows Runtime APIs (for example, pascalCasedNames support for APIs exposed to JavaScript). The Windows Runtime metadata also enables Visual Studio to provide great tooling capabilities such as IntelliSense support.

Why build your own Windows Runtime components

Creating Windows Runtime components can help you architect for reusability and language interoperability. Let’s take a look at some app scenarios that showcase how you can use 3^rd party Windows Runtime components to build better experiences.

Figure1: Xbox 360 Controller

Using Win32 and COM APIs in your Metro style app

The platform provided by Internet Explorer 10 enables you to create great Metro style app experiences using HTML, CSS and JavaScript. But what if you have built a game using HTML5 canvas and want to integrate with the Xbox 360 controller for Windows? The XInput API, which allows apps to receive input from the controller, exposes Win32 APIs that are not available directly to JavaScript.

This is a great example of where creating a Windows Runtime component can solve this problem and give you the ability to use the XInput APIs in your HTML based Metro style app. The XInput and JavaScript controller sketch sample showcases exactly that. The sample app contains a game controller Windows Runtime component written in C++ which wraps the functionality exposed by the XInput APIs. The controller sketch HTML-based app uses the game controller C++ Windows Runtime component to enable the interaction with the Xbox 360 controller.

This scenario, impossible to accomplish using HTML and JavaScript alone, is a perfect example of where creating a 3^rd party Windows Runtime component allows you to complete a complex scenario that you otherwise wouldn’t be able to.

Computationally Intensive Operations

Apps created for fields like science, engineering, and maps/geography often have computationally intensive operations. These intensive operations typically require powerful parallel processing and are well suited for C++ to achieve optimal performance. In Developing Bing Maps Trip Optimizer, a Metro style app in JavaScript and C++ , we see another scenario where creating a Windows Runtime component in C++ allows us to create the best experience in our app.

You wonder why anyone would want to calculate a trip route on local data at all when we could run this computationally intensive task in the cloud on Bing servers. Bing Maps exposes JavaScript APIs to do this, but sometimes an app must run offline. And we also want the user to drag and change the route in real time with touch. If we can run these intense operations locally, we create an even better experience.

By writing our compute-intensive operation in C++ using the parallel task library, we can harness the power of the client to create a great experience for users. Windows Runtime is a great fit for this scenario, allowing us to create our rich client User Interface (UI) in HTML and JavaScript with the Bing Maps AJAX control while running all of our intensive route operations using C++ code that calculates quickly using parallelization.

Libraries

The community is filled with great libraries that developers put together and shared for everyone to use. In the past, you may have found it challenging to reuse some of these libraries if they didn’t match the programming language your app was implemented in. For example, you built a great .NET app, but couldn’t use a library written in C++ without going through painful interop hoops like PInvoke.

Windows Runtime bridges the language gap in Windows 8, making it possible for a single Windows Runtime component library with a single code base to reach a broader set of developers irrespective of the component’s language or your app’s primary programming language.

You can now create a single Windows Runtime-exposed XAML library of custom controls that both C++ and C# app developers can consume. And you can use various data storage Windows Runtime libraries shared out by developers in your XAML or HTML based Metro style apps. All of these scenarios are possible without the burden of writing any interop code.

We think Windows Runtime will be a boon to the libraries that developers create and share broadly for the community of Metro style app developers. Let’s now take a look at two concrete examples showing the basics of building a 3^rd party Windows Runtime component in C++/CX and C#.

Scenario 1: Enhancing your app with native audio

Say we are building a software synthesizer app using XAML backed by app logic written in C#. To add filter support to our music app, we would like to use XAudio to have direct control of audio buffers.

Adding the Windows Runtime component to our solution

Using Visual Studio, we add a new C++ Windows Runtime component project to our existing solution. This Windows Runtime component wraps the music processing functionality:

Figure 2: Adding a new C++ Windows Runtime Component

Visual Studio created a C++ project for us to expose APIs for which the implementation will be packaged in a DLL and the Windows Runtime metadata in a winmd file. Both are made available to our C# project.

Defining the class exposed to our XAML C# project

We use C++/CX to build the APIs that will be exposed to our C# project, but you also can use the Windows Runtime C++ Template Library (WRL). We start by defining a fairly basic class to encapsulate the XAudio functionality:

XAudioWrapper.h

#pragma once

#include "mmreg.h"
#include <vector>
#include <memory>

namespace XAudioWrapper
{
    public ref class XAudio2SoundPlayer sealed
    {
    public:
        XAudio2SoundPlayer(uint32 sampleRate);
        virtual ~XAudio2SoundPlayer();

        void Initialize();

        bool   PlaySound(size_t index);
        bool   StopSound(size_t index);
        bool   IsSoundPlaying(size_t index);
        size_t GetSoundCount();

        void Suspend();
        void Resume();

    private:
        interface IXAudio2*                     m_audioEngine;
        interface IXAudio2MasteringVoice*       m_masteringVoice;
        std::vector<std::shared_ptr<ImplData>>  m_soundList;
    };
}

You will first notice the usage of the public, ref and sealed keywords in the class declaration. For a class to be instantiated from another language such as JavaScript or C# in a Metro style app, the class must be declared as public ref class sealed.

The public functionality (methods, properties …) of the class are limited to C++ built-in types or Windows Runtime types. Those are the only types allowed for crossing the language boundary in Windows Runtime components. That being said, you can use the regular C++ library (i.e.: Standard Template Library collections) for the private data members of your class as shown in this code snippet. Those private data members don’t have to follow the rules associated with crossing the language boundary. The Visual Studio compiler emits error messages and provides guidance if you use unsupported constructs.

Implementing the class exposed in our Windows Runtime component

Now that we have defined the basic interface for our class, let’s take a look at some of the implemented methods:

XAudioWrapper.cpp

XAudio2SoundPlayer::XAudio2SoundPlayer(uint32 sampleRate) :
    m_soundList()
{
    // Create the XAudio2 engine
    UINT32 flags = 0;

    XAudio2Create(&m_audioEngine, flags);

    // Create the mastering voice
    m_audioEngine->CreateMasteringVoice(
        &m_masteringVoice,
        XAUDIO2_DEFAULT_CHANNELS,
        sampleRate
        );
}

void XAudio2SoundPlayer::Resume()
{
    m_audioEngine->StartEngine();
}

bool XAudio2SoundPlayer::PlaySound(size_t index)
{
    //
    // Setup buffer
    //
    XAUDIO2_BUFFER playBuffer = { 0 };
    std::shared_ptr<ImplData> soundData = m_soundList[index];
    playBuffer.AudioBytes = soundData->playData->Length;
    playBuffer.pAudioData = soundData->playData->Data;
    playBuffer.Flags = XAUDIO2_END_OF_STREAM;

    HRESULT hr = soundData->sourceVoice->Stop();
    if (SUCCEEDED(hr))
    {
        hr = soundData->sourceVoice->FlushSourceBuffers();
    }

    //
    // Submit the sound buffer and (re)start (ignore any 'stop' failures)
    //
    hr = soundData->sourceVoice->SubmitSourceBuffer(&playBuffer);
    if (SUCCEEDED(hr))
    {
        hr = soundData->sourceVoice->Start(0, XAUDIO2_COMMIT_NOW);
    }

    return SUCCEEDED(hr);
}

In this code snippet, we are just using the XAudio2 COM APIs available for Metro style app development to wire up our audio engine, play sound and resume the engine. Additionally, we can use C++ constructs and types beyond just the Windows Runtime types to implement the necessary functionality.

Adding and consuming the Windows Runtime component

After we define and implement our basic class, we use Visual Studio to add the XAudioWrapper Windows Runtime component to our C++ project from our C# project:

Figure 3: Adding the XAudioWrapper Windows Runtime Component to our music app

As a result, the class that we expose from our C++ project becomes available to our C# project:

MainPage.cs

using XAudioWrapper;

namespace BasicSoundApp
{    
    public sealed partial class MainPage : Page
    {
        XAudio2SoundPlayer _audioPlayer = new XAudio2SoundPlayer(48000);
        public MainPage()
        {
            this.InitializeComponent();
        }

        protected override void OnNavigatedTo(NavigationEventArgs e)
        {
            _audioPlayer.Initialize();
        }

        private void Button_Click_1(object sender, RoutedEventArgs e)
        {
            _audioPlayer.PlaySound(0);
        }
    }
}

As shown in the code snippet, we can interact with our XAudio wrapper from C# just as if it were a regular .NET component. We reference its namespace, instantiate the component and start invoking the various methods it exposes. All of this without requiring any DllImports to call into the native code!

Scenario 2: Using built-in APIs to open a zip file from your app

Say we are also building a file viewer app using HTML and want to add functionality to allow users of this app to pick zip files. We want to use the APIs already built-into Windows and exposed in the .NET platform for handling zip files.

Adding the Windows Runtime component to our solution

This is the same step as we have described for our music app, but we now pick the C# Windows Runtime component to wrap the zip processing functionality:

Figure 4: Adding a new C# Windows Runtime Component 

Visual Studio has created a C# project for us to expose the APIs for which both the implementation and Windows Runtime metadata are packaged in a .winmd file and made available to our web project.

Implementing the class exposed in our Windows Runtime component

We use C# to build the APIs that will be exposed to our web project, but you can also use Visual Basic. We start by defining a simple C# class to encapsulate the zip functionality:

ZipWrapper.cs

using System;
using System.Collections.Generic;
using System.IO;
using System.IO.Compression;
using System.Runtime.InteropServices.WindowsRuntime;
using System.Threading.Tasks;
using Windows.Foundation;
using Windows.Storage;

public sealed class ZipWrapper
{
public static IAsyncOperationWithProgress<IList<string>, double> EnumerateZipFileAsync(StorageFile file)
        {
            return AsyncInfo.Run(async delegate(
                System.Threading.CancellationToken cancellationToken, IProgress<double> progress)
            {
                IList<string> fileList = new List<string>();
                progress.Report(0);

                using (var stream = await file.OpenStreamForReadAsync())
                {
                    using (var archive = new ZipArchive(stream))
                    {
                        for (int i = 0; i < archive.Entries.Count; i++)
                        {
                            // add code for processing/analysis on the file 
 // content here

                            // add to our list and report progress
                            fileList.Add(archive.Entries[i].FullName);
                            double progressUpdate = ((i + 1) / ((double)archive.Entries.Count)) * 100; // percentage
                            progress.Report(progressUpdate);
                        }
                    }
                }

                progress.Report(100.0);
                return fileList;
            });
        }
}

This class is public and sealed. Similarly to building C++ Windows Runtime components, this is necessary for other languages to instantiate the class. The static method exposed in the class uses a mixture of Windows Runtime types (such as StorageFile) and as .NET types (such as IList) in the method signature. The rule of thumb is to use Windows Runtime types for defining the public fields, parameters and return types that will be exposed to the other languages. That being said, you can use certain .NET fundamental types (i.e.: DateTimeOffset and Uri) and primitives (i.e.: IList) as is.

You will also notice that the method above leverages the Windows Runtime infrastructure for async and progress support that you can (and should) use when defining your Windows Runtime components. As far as the implementation for the Windows Runtime component or any private functionality in the class, you are not limited to only using Windows Runtime types and APIs; you are free to use any of the .NET API surface exposed for Metro app development as shown in the code snippet ZipArchive APIs.

Adding and consuming the Windows Runtime component

Now that we have implemented our zip tool wrapper, we use Visual Studio to add a reference to our C# project from our JavaScript project:

Figure 5: Adding the ZipUtil Windows Runtime component to our file viewer app

As a result, the class that we have exposed from our C# project becomes available to our web project:

program.js

function pickSinglePhoto() {

    // Create the picker object for picking zip files
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
    openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
    openPicker.fileTypeFilter.replaceAll([".zip"]);

    // Open the picker for the user to pick a file 
    openPicker.pickSingleFileAsync().then(function (file) {
        if (file) {
            ZipUtil.ZipWrapper.enumerateZipFileAsync(file).then(
        function (fileList) {
            for (var i = 0; i < fileList.length; i++)
                document.getElementById('output').innerHTML += " " + fileList[i];
        },
        function (prog) {
            document.getElementById('zipProgress').value = prog;
        }
    );
        } else {
            document.getElementById('output').innerHTML = "an error occurred";
        }
    });
};

As you can see, we can interact with our zip tool wrapper from JavaScript just as if it were a regular JavaScript object. We can call into the static method exposed in our Windows Runtime component, and we can do so using JavaScript’s async language constructs such as .then().

General guidance

Not every API you write for your Metro style app should be exposed as a 3^rd party Windows Runtime component. In general, use Windows Runtime types when you are communicating between programming languages and use types and constructs that are built into the language that you are using for functionality that is not publicly exposed via a Windows Runtime component. Additionally, there are various language-specific features and rules around crossing the language boundary that you need to take into consideration when building your Windows Runtime component. This includes delegates and events, asynchronous operations, method overloading, handling specific data types such as collections, exception handling and debugging tips. You can dive into those topics further by visiting the section on building Windows Runtime components for your development language.

In closing

With Windows Runtime components, you can now mix programming languages and API technologies to build the apps you envision. Windows 8 is about no compromises. There are even no compromises during development, allowing you to mix and match the programming languages that best fit your scenario. We hope this allows you to spend more time thinking about innovation and less time being forced to learn a completely new programming language.

Happy app building!

– Ines Khelifi, Program Manager, Windows

References

In this post, we have merely scratched the surface of what’s possible with building Windows Runtime components. Here are additional resources to help you dive into this further for your app development:

Windows 8 app developer blog

Fast and fluid apps must be responsive

How many times have you been using a Windows app that stops responding, and you are presented with a greyed version of the app and the spinning donut? Without fail, it always seems to come at the worst possible time. Worse yet, you might end up losing a lot of hard work when this happens.

Users expect apps to be responsive to all interactions. When they use their favorite news reading app, they want to add news feeds, read news articles, save news articles, etc. They should be able to do all of these things even when the app is retrieving the latest articles from the Internet.

This becomes especially important when a user is interacting with your app using touch. Users notice when the app doesn’t “stick to your finger.” Even minor performance problems can degrade the user experience and break the fast and fluid feeling.

An app isn’t fast and fluid if it stops responding to user input. So why do apps stop responding? One major cause is that the app is synchronous; it is waiting for something else to finish (like getting data from the Internet) and can’t respond to your input.

Many modern apps connect to social websites, store data in the cloud, work with files on the hard disk, communicate with other gadgets and devices, etc. Some of these sources have unpredictable latencies, which makes creating fast and fluid apps challenging. Unless built correctly, apps spend more time waiting for the outside environment and less time responding to the user’s needs.

Addressing this connected world was a core principle when we started to design APIs for the Windows Runtime (WinRT). We felt it was important to provide an API surface that was powerful and led to fast and fluid apps by default.

To achieve those goals, we made many potentially I/O-bound APIs asynchronous in the Windows Runtime. These are the most likely candidates to visibly degrade performance if written synchronously (e.g. could likely take longer than 50 milliseconds to execute). This asynchronous approach to APIs sets you up to write code that is fast and fluid by default and promotes the importance of app responsiveness in Metro style app development.

For those of you unfamiliar with asynchronous patterns, think of asynchrony in WinRT as providing a callback number to somebody over the phone. You give the person the number to call you back, you hang up, and then you continue doing any other work you need to. When the person is ready to talk to you, they can call you back at the number you provided. This is the essence of how asynchrony works in WinRT.

To understand more about the asynchronous nature of WinRT, we will first look at how you can use these asynchronous APIs in a straightforward way. Then we will take an under the hood look at what async primitives WinRT has introduced (that the new language features build upon), and how they work.

How to use it: new developer enhancements for asynchrony

In the past, writing asynchronous code was difficult. Our teams building tools for Windows 8 Metro style apps made significant advancements in solving this problem in recent releases. In the .NET Framework 4.0, we introduced the Task Parallel Library. Then the await keyword was introduced into C# and Visual Basic. C++ invested in technologies like the Parallel Patterns Library (PPL). And JavaScript has great tools like Promises.

Each one of these technologies presents you with a straightforward way to write asynchronous code. By introducing a standard async pattern under the hood that all of these technologies use, we allow you to use these technologies when building Metro style apps regardless of which programming language you use.

In the case of your favorite news app, the code that remains responsive while retrieving news articles is quite simple using the Windows.Web.Syndication.SyndicationClient API. The call to RetrieveFeedAsync returns immediately. This is a great thing because the results might take a long time to come back from the Internet. In the meantime, the UI continues to interact with the user.

The code highlighted in yellow runs after the call to RetrieveFeedAsync is completed. You don’t need to think about all the “start again where you left off” plumbing. And the code is written in a straightforward way as if it was synchronous.

C# code to retrieve RSS feed asynchronously:

There is no mention of threads, context switching, dispatchers, etc. These new developer enhancements for writing asynchronous code will handle that for you. Code following the async API call is automatically called back in the same context that the original call was made. This means you can go ahead and update the UI with the results without worrying about getting back to the UI thread.

How to use it: error handling

Of course, API calls can fail (like losing network connectivity while retrieving RSS feeds). To be truly robust, we need to be resilient in the presence of errors. Using the async functionality in the languages makes handling errors more straightforward. The mechanism to do this varies based on the language.

For JavaScript, we recommend that you always end your Promise chains with done. This ensures that any exceptions captured in the promise chain are visible to the developer (i.e. reported in the error handler, or thrown). Done has the same signature as then. So to handle errors, you simply pass an error delegate into done():

To handle the exception in C# or Visual Basic, you use a try/catch block just as you do with synchronous code today:

The most common method to use in C++ to handle async errors is to use another task-based continuation that throws the exceptions (you can find other methods for error handling in C++ in the topic Asynchronous Programming in C++ on Dev Center):

For more details on how to use these asynchronous improvements (including more scenarios like support cancellation and progress) see:

• Asynchronous Programming in the Windows Runtime on the Windows Dev Center
• Asynchronous Programming in JavaScript on the Windows Dev Center
• Asynchronous Programming in C++ on the Windows Dev Center
• Asynchronous Programming in .NET on the Windows Dev Center
• How to Handle Errors when using Promises in JavaScript on the Windows Dev Center

How it works: WinRT async primitives

Async is very powerful, but it can appear that there is a lot of magic that happens here on your behalf. To demystify what is happening, let’s take a look at how asynchrony in WinRT works in a little more detail. Our first step is to investigate the primitives the model is built upon. Most of you won’t have to use these primitives at all (if you find a scenario where you have to do this, we would love to hear the feedback).

Starting with our C# code, let’s look at the actual return type of RetrieveFeedAsync (shown here in C# Intellisense):

 
 Figure 1. Intellisense displayed for RetrieveFeedAsync method

RetrieveFeedAsync returns an IAsyncOperationWithProgress interface. IAsyncOperationWithProgress is one of 5 interfaces that define the core asynchronous programming surface for WinRT: IAsyncInfo, IAsyncAction, IAsyncActionWithProgress, IAsyncOperation, and IAsyncOperationWithProgress.

The core interface that the WinRT async model is built on is IAsyncInfo. This core interface defines properties of an async operation like current status, the ability to cancel the operation, the error of a failed operation, etc.

As we mentioned earlier, async operations can return results. Async operations in WinRT can also report progress as they are running. The other 4 async interfaces above (IAsyncAction, IAsyncActionWithProgress, IAsyncOperation, and IAsyncOperationWithProgress) define different combinations of results and progress.

   
Figure 2. Different combinations of results and progress

Providing core async primitives in the Windows Runtime enables C#, Visual Basic, C++, and JavaScript to project WinRT async operations in a familiar way to you.

Note: The move from cold start to hot start

In the Windows 8 Developer Preview released at //build, all async operations in WinRT were started cold. They didn’t start running immediately. They had to be explicitly started by the developer or implicitly started using the async features in C#, Visual Basic, JavaScript, or C++. We received feedback from several sources that this wasn’t intuitive and could cause pain and confusion.

In the Windows 8 Consumer Preview release, you will notice that we removed the Start() method from the WinRT async primitives. Now, our async operations are all started hot. So, the async method launched the operation before returning it to the caller.

This is just one of many changes that you’ll find in the Consumer Preview where we’ve fine-tuned the developer platform based on all the great feedback you have given us.

How it works: results, cancellation, and errors with async primitives

An async operation starts in the Started state and can progress to one of three other states: Canceled, Completed, and Error. The current state of an async operation is reflected in the Status property of the async operation (represented by the AsyncStatus enum type).

The first thing we do with an async operation is wire up a completed handler. From within the completed handler, we can get the results and use them.

Sometimes you may want to cancel an operation. You can do this by calling the Cancel method on the async operation.

The Completed handler is always called for an async operation regardless of whether it was completed, canceled, or resulted in an error. Call GetResults only when the async operation was completed (e.g. not when the operation is canceled or ends in an error). You can determine this by inspecting the status parameter.

This code still isn’t robust if the operation failed. Just like cancellation, error reporting is supported through the same async operation. As well as using AsyncStatus to differentiate between Completed and Canceled, we also use it to determine failure of an async operation (i.e. AsyncStatus.Error). You can find the specific failure code in the ErrorCode property of the async operation.

How it works: reporting progress with async primitives

Some WinRT async operations provide progress notifications while they are running. You can use these notifications to report the current progress of the async operation to the user.

In WinRT, progress reporting is handled through the IAsyncActionWithProgress<TProgress> and IAsyncOperationWithProgress<TResult, TProgress> interfaces. Each interface contains a Progress event that you can use to get progress reports from the async operation.

The programming model to consume this is nearly identical to consuming the Completed event. In our example of retrieving syndication feeds, we can report how many bytes of the total amount have been retrieved:

In this case, the second parameter (progress) is of type RetrievalProgress. This type contains two parameters (bytesRetrieved and totalBytesToRetrieve) that are used to report our ongoing progress.

For deeper material (involving asynchronous programming in WinRT, or asynchrony in general), you can check out:

• “Async Everywhere” talk from the //Build conference
• Asynchronous Programming in JavaScript with “Promises”
• Task-Based Asynchronous Pattern
• Asynchrony in .NET

In closing

What’s interesting about asynchrony being so prevalent in WinRT is how it impacts the way you structure your code and architect your app. You start thinking about your app in a more loosely-connected way. If you have any feedback in this area, we would love to hear from you! Let us know by leaving a comment here or on the Dev Center forums.

We want your customers to love your Windows 8 apps. We want those apps to start alive with activity, and remain alive with activity. And we want you to more easily create those apps. We want you to be able to easily connect to social websites, store data in the cloud, work with files on the hard disk, communicate with other gadgets and devices, etc., while providing your customers with a great user experience.

–Jason Olson

Program Manager, Windows

Windows 8 app developer blog

Fast and fluid apps must be responsive

How many times have you been using a Windows app that stops responding, and you are presented with a greyed version of the app and the spinning donut? Without fail, it always seems to come at the worst possible time. Worse yet, you might end up losing a lot of hard work when this happens.

Users expect apps to be responsive to all interactions. When they use their favorite news reading app, they want to add news feeds, read news articles, save news articles, etc. They should be able to do all of these things even when the app is retrieving the latest articles from the Internet.

This becomes especially important when a user is interacting with your app using touch. Users notice when the app doesn’t “stick to your finger.” Even minor performance problems can degrade the user experience and break the fast and fluid feeling.

An app isn’t fast and fluid if it stops responding to user input. So why do apps stop responding? One major cause is that the app is synchronous; it is waiting for something else to finish (like getting data from the Internet) and can’t respond to your input.

Many modern apps connect to social websites, store data in the cloud, work with files on the hard disk, communicate with other gadgets and devices, etc. Some of these sources have unpredictable latencies, which makes creating fast and fluid apps challenging. Unless built correctly, apps spend more time waiting for the outside environment and less time responding to the user’s needs.

Addressing this connected world was a core principle when we started to design APIs for the Windows Runtime (WinRT). We felt it was important to provide an API surface that was powerful and led to fast and fluid apps by default.

To achieve those goals, we made many potentially I/O-bound APIs asynchronous in the Windows Runtime. These are the most likely candidates to visibly degrade performance if written synchronously (e.g. could likely take longer than 50 milliseconds to execute). This asynchronous approach to APIs sets you up to write code that is fast and fluid by default and promotes the importance of app responsiveness in Metro style app development.

For those of you unfamiliar with asynchronous patterns, think of asynchrony in WinRT as providing a callback number to somebody over the phone. You give the person the number to call you back, you hang up, and then you continue doing any other work you need to. When the person is ready to talk to you, they can call you back at the number you provided. This is the essence of how asynchrony works in WinRT.

To understand more about the asynchronous nature of WinRT, we will first look at how you can use these asynchronous APIs in a straightforward way. Then we will take an under the hood look at what async primitives WinRT has introduced (that the new language features build upon), and how they work.

How to use it: new developer enhancements for asynchrony

In the past, writing asynchronous code was difficult. Our teams building tools for Windows 8 Metro style apps made significant advancements in solving this problem in recent releases. In the .NET Framework 4.0, we introduced the Task Parallel Library. Then the await keyword was introduced into C# and Visual Basic. C++ invested in technologies like the Parallel Patterns Library (PPL). And JavaScript has great tools like Promises.

Each one of these technologies presents you with a straightforward way to write asynchronous code. By introducing a standard async pattern under the hood that all of these technologies use, we allow you to use these technologies when building Metro style apps regardless of which programming language you use.

In the case of your favorite news app, the code that remains responsive while retrieving news articles is quite simple using the Windows.Web.Syndication.SyndicationClient API. The call to RetrieveFeedAsync returns immediately. This is a great thing because the results might take a long time to come back from the Internet. In the meantime, the UI continues to interact with the user.

The code highlighted in yellow runs after the call to RetrieveFeedAsync is completed. You don’t need to think about all the “start again where you left off” plumbing. And the code is written in a straightforward way as if it was synchronous.

C# code to retrieve RSS feed asynchronously:

There is no mention of threads, context switching, dispatchers, etc. These new developer enhancements for writing asynchronous code will handle that for you. Code following the async API call is automatically called back in the same context that the original call was made. This means you can go ahead and update the UI with the results without worrying about getting back to the UI thread.

How to use it: error handling

Of course, API calls can fail (like losing network connectivity while retrieving RSS feeds). To be truly robust, we need to be resilient in the presence of errors. Using the async functionality in the languages makes handling errors more straightforward. The mechanism to do this varies based on the language.

For JavaScript, we recommend that you always end your Promise chains with done. This ensures that any exceptions captured in the promise chain are visible to the developer (i.e. reported in the error handler, or thrown). Done has the same signature as then. So to handle errors, you simply pass an error delegate into done():

To handle the exception in C# or Visual Basic, you use a try/catch block just as you do with synchronous code today:

The most common method to use in C++ to handle async errors is to use another task-based continuation that throws the exceptions (you can find other methods for error handling in C++ in the topic Asynchronous Programming in C++ on Dev Center):

For more details on how to use these asynchronous improvements (including more scenarios like support cancellation and progress) see:

• Asynchronous Programming in the Windows Runtime on the Windows Dev Center
• Asynchronous Programming in JavaScript on the Windows Dev Center
• Asynchronous Programming in C++ on the Windows Dev Center
• Asynchronous Programming in .NET on the Windows Dev Center
• How to Handle Errors when using Promises in JavaScript on the Windows Dev Center

How it works: WinRT async primitives

Async is very powerful, but it can appear that there is a lot of magic that happens here on your behalf. To demystify what is happening, let’s take a look at how asynchrony in WinRT works in a little more detail. Our first step is to investigate the primitives the model is built upon. Most of you won’t have to use these primitives at all (if you find a scenario where you have to do this, we would love to hear the feedback).

Starting with our C# code, let’s look at the actual return type of RetrieveFeedAsync (shown here in C# Intellisense):

 
 Figure 1. Intellisense displayed for RetrieveFeedAsync method

RetrieveFeedAsync returns an IAsyncOperationWithProgress interface. IAsyncOperationWithProgress is one of 5 interfaces that define the core asynchronous programming surface for WinRT: IAsyncInfo, IAsyncAction, IAsyncActionWithProgress, IAsyncOperation, and IAsyncOperationWithProgress.

The core interface that the WinRT async model is built on is IAsyncInfo. This core interface defines properties of an async operation like current status, the ability to cancel the operation, the error of a failed operation, etc.

As we mentioned earlier, async operations can return results. Async operations in WinRT can also report progress as they are running. The other 4 async interfaces above (IAsyncAction, IAsyncActionWithProgress, IAsyncOperation, and IAsyncOperationWithProgress) define different combinations of results and progress.

   
Figure 2. Different combinations of results and progress

Providing core async primitives in the Windows Runtime enables C#, Visual Basic, C++, and JavaScript to project WinRT async operations in a familiar way to you.

Note: The move from cold start to hot start

In the Windows 8 Developer Preview released at //build, all async operations in WinRT were started cold. They didn’t start running immediately. They had to be explicitly started by the developer or implicitly started using the async features in C#, Visual Basic, JavaScript, or C++. We received feedback from several sources that this wasn’t intuitive and could cause pain and confusion.

In the Windows 8 Consumer Preview release, you will notice that we removed the Start() method from the WinRT async primitives. Now, our async operations are all started hot. So, the async method launched the operation before returning it to the caller.

This is just one of many changes that you’ll find in the Consumer Preview where we’ve fine-tuned the developer platform based on all the great feedback you have given us.

How it works: results, cancellation, and errors with async primitives

An async operation starts in the Started state and can progress to one of three other states: Canceled, Completed, and Error. The current state of an async operation is reflected in the Status property of the async operation (represented by the AsyncStatus enum type).

The first thing we do with an async operation is wire up a completed handler. From within the completed handler, we can get the results and use them.

Sometimes you may want to cancel an operation. You can do this by calling the Cancel method on the async operation.

The Completed handler is always called for an async operation regardless of whether it was completed, canceled, or resulted in an error. Call GetResults only when the async operation was completed (e.g. not when the operation is canceled or ends in an error). You can determine this by inspecting the status parameter.

This code still isn’t robust if the operation failed. Just like cancellation, error reporting is supported through the same async operation. As well as using AsyncStatus to differentiate between Completed and Canceled, we also use it to determine failure of an async operation (i.e. AsyncStatus.Error). You can find the specific failure code in the ErrorCode property of the async operation.

How it works: reporting progress with async primitives

Some WinRT async operations provide progress notifications while they are running. You can use these notifications to report the current progress of the async operation to the user.

In WinRT, progress reporting is handled through the IAsyncActionWithProgress<TProgress> and IAsyncOperationWithProgress<TResult, TProgress> interfaces. Each interface contains a Progress event that you can use to get progress reports from the async operation.

The programming model to consume this is nearly identical to consuming the Completed event. In our example of retrieving syndication feeds, we can report how many bytes of the total amount have been retrieved:

In this case, the second parameter (progress) is of type RetrievalProgress. This type contains two parameters (bytesRetrieved and totalBytesToRetrieve) that are used to report our ongoing progress.

For deeper material (involving asynchronous programming in WinRT, or asynchrony in general), you can check out:

• “Async Everywhere” talk from the //Build conference
• Asynchronous Programming in JavaScript with “Promises”
• Task-Based Asynchronous Pattern
• Asynchrony in .NET

In closing

What’s interesting about asynchrony being so prevalent in WinRT is how it impacts the way you structure your code and architect your app. You start thinking about your app in a more loosely-connected way. If you have any feedback in this area, we would love to hear from you! Let us know by leaving a comment here or on the Dev Center forums.

We want your customers to love your Windows 8 apps. We want those apps to start alive with activity, and remain alive with activity. And we want you to more easily create those apps. We want you to be able to easily connect to social websites, store data in the cloud, work with files on the hard disk, communicate with other gadgets and devices, etc., while providing your customers with a great user experience.

–Jason Olson

Program Manager, Windows

Windows 8 app developer blog

Want to understand more about the new programming model for Windows? Windows Runtime, or Win32, is the reboot of the Win32 API for Windows. WinRT is the only way to build Metro-style apps for the Windows 8 operating system.

*** Money-back guarantee. We’ll refund you if you tell us you got no value from this book. ***

In this ebook, you’ll learn exactly what WinRT is and what impact it’s going to have on Windows developers.

This ebook is kept up-to-date when new

Price:

More Windows 8 Products

Fundamentals such as memory usage represent a key engineering tenet of Windows 8. In building Windows 8 we set out to significantly reduce the overall runtime memory requirements of the core system. This is always good for everyone and especially in a world where people want to run more and more apps at the same time or run on systems with only 1 or 2GB of memory. The laptop we talk about in this post is the exact same one we talked about at the Windows 7 PDC in 2008 – an off-the-shelf, first-generation, ATOM-based netbook with 1GB of memory. This post details our efforts around memory footprint and was authored by Bill Karagounis, the group program manager of our Performance team. –Steven

The runtime memory usage of Windows 8 is an important factor in determining the Windows 8 system requirements, as well as the broadened spectrum of devices that will host Windows 8. As you know, we’re delivering the complete Windows 8 experience on SoC-based devices characterized by low power consumption. This makes it even more important to leave lots of memory available for multiple concurrent apps and to sustain the overall responsiveness of devices.

Something that might not be obvious is that minimizing memory usage on low-power platforms can prolong battery life. Huh? In any PC, RAM is constantly consuming power. If an OS uses a lot of memory, it can force device manufacturers to include more physical RAM. The more RAM you have on board, the more power it uses, the less battery life you get. Having additional RAM on a tablet device can, in some instances, shave days off the amount of time the tablet can sit on your coffee table looking off but staying fresh and up to date.

Memory usage goals

Our goal with Windows 8 from the beginning was to ship with the same system requirements as Windows 7. We know if we do even better that there are more resources for apps, even if we keep the published requirements the same. It is fun to think about what the "low end" hardware looked like in 2009 and how you can’t even find things like 256MB memory modules anymore. We wanted to ensure that people running on Windows 7-era hardware would have the option to easily upgrade their existing machines to Windows 8 and take advantage of the functionality it has to offer. We also expect that many machines that predate the Windows 7 release will run Windows 8 based on the experiences we’ve had with older machines we intentionally keep in our performance test infrastructure.

An important task for Windows 8 was to make room for new functionality while looking for opportunities to reduce the memory consumed by existing functionality and consumed across the board. Windows 8 is tracking well towards meeting the goal we set ourselves.

Task Manager memory use comparison

The easiest way to make a ballpark comparison of Windows 8 vs. Windows 7 memory use is to install both operating systems on a 1GB RAM machine (minimum OS RAM requirement) and compare them when they’ve been rebooted multiple times, and then idled for a while.

The Windows Task Manager contains the main view of system memory through its “In Use” statistic (described in detail in this doc). The below graphics compare memory consumption on Steven’s 3+ year old netbook that he was using at the //build/ keynote recently, running Windows 7 at idle, and then with the same machine running Windows 8.

Figure 1 – Memory usage in Windows 7 SP1

Figure 2 – Memory usage in Windows 8

The specific hardware making up a machine, memory use of drivers, and even uptime can cause variability, so memory results will be different on different machines (or even the same machine at different times). As you can see though, Windows 8 is doing well relative to Windows 7.

For a bit of extra fun on a test machine, go to device manager and disable your display adapter (unload the graphics driver). You’d never run your machine this way but this does give you an even closer approximation of the memory use of Windows itself. With a disabled graphics driver, the machine above gets under 200MB after idling for a while.

NOTE: For Windows 8, a clean install also contains the extended Windows Defender technology, which, for the first time incorporates complete antimalware functionality – also optimized for memory and resource use per Jason’s blog about protecting you from malware. (This functionality does not exist on a clean install of Windows 7 where we would recommend that you add security software).

Making room in Windows 8

We made hundreds of specific changes to minimize OS memory use in Windows 8. I’m going to call out a few specific areas that resulted in substantial memory savings.

Memory combining

When assessing the contents of RAM in a typical running PC, many parts of memory have the same content. The redundant copies of data across system RAM present an opportunity to reduce the memory footprint even for services and OS components.

How can this happen? Applications will sometimes allocate memory for future use and will initialize it all to the same value. The application may never actually use the memory as it may be there in anticipation of functionality that is the user never invokes. If multiple running applications are doing this at the same time, redundant copies of memory are in the system.

Memory combining is a technique in which Windows efficiently assesses the content of system RAM during normal activity and locates duplicate content across all system memory. Windows will then free up duplicates and keep a single copy. If the application tries to write to the memory in future, Windows will give it a private copy. All of this happens under the covers in the memory manager, with no impact on applications. This approach can liberate 10s to 100s of MBs of memory (depending on how many applications are running concurrently).

Service changes and reductions

OS services configured to run all the time are a significant source of ambient memory use. When assessing the set of OS services during Windows 8 planning, we decided to remove a number of them (13), move a different set of services to “manual” start, and also made some of the “always running” services move to a “start on demand” model. This is where a “trigger” in the OS (like device arrival or the availability of a network address) causes the following to occur:

1. The service starts.
2. The service does its thing (whatever that happens to be).
3. It hangs around for a while to make sure there isn’t anything else to do, and
4. The service goes away.

You’ll notice that Plug and Play, Windows Update, and the the user mode driver framework service are all trigger-started in Windows 8, in contrast to Windows 7, where these services were always running.

Of course we have added a ton of new functionality (and new code) to Windows 8. Some of this new functionality is packaged in the form of new services. Of these new services, two are auto-started; all others are manual or trigger-started.

Doing the same job with less memory

As Windows executes applications and performs its own system housekeeping, program files and data are loaded off the disk into main memory. During Windows 7 and Windows 8 development to date, we’ve analyzed the pieces (pages) of memory during normal execution and how often they were referenced. The idea here is that if you’re going to pay the price for allocating a piece of memory, you’d better be using it (referencing it) often. If you’re not referencing that memory often but need it, consolidate it with something else.

Shortly after we shipped Windows 7, we applied a similar technique to several of the low level components of Windows dating back to the early days of NT (early 1990s). The work included re-architecture of code and changing data structures to completely separate “hot” parts of memory (frequently referenced) from “cold” parts. By densely consolidating the hot items, we brought down the overall runtime memory cost.

Given the nature of the changes (low-level OS), we wanted to get the work done as early as possible in the schedule to get ample runtime on the changes. To date, these changes have been in place on Windows 8 for almost 2 years with thousands of Microsoft employees using the product to get their daily jobs done. And we’ve seen consistent results showing memory usage reduced by tens of MB on an average machine.

Lazy initialization of the “desktop”

Back in June, you saw Steven and Julie introduce the Metro style UI for the first time. We expect many people using tablets to spend a lot of time in that environment, typically using Metro style apps. As part of that demonstration, we also showed that for Windows 8, you can also bring forward your existing applications and use them in the very familiar desktop environment.

From a memory perspective, we’ve taken advantage of the fact that there will be some set of devices on which users will stay in the immersive, Metro style UI almost all the time. In this instance, Windows 8 will only initialize OS components unique to the desktop environment when necessary. This is another source of memory savings, approximately 23MB right now. (Note that Task Manager runs in the desktop, so the memory numbers shown above include its cost).

More granular prioritization of memory

Windows 8 has a better scheme for the prioritization of memory allocations made by applications and system components. This means that Windows can make better decisions about what memory to keep around and what memory to remove sooner.

For example, antivirus programs (AV) do various checks on files when they are being opened by other programs. The memory that the AV program allocates to check virus signatures is usually a one-time allocation (it is unlikely that specific memory will be needed again). On Windows 7, the memory is treated as if it had the same priority in the system as other memory (say, memory allocated by a running instance of Microsoft Excel). If memory became scarce, Windows 7 could end up removing the memory that helps another running application (like Excel) stay responsive for the user, which wouldn’t be the best choice for system responsiveness in this case.

In Windows 8, any program has the ability to allocate memory as “low priority.” This is an important signal to Windows that if there is memory pressure, Windows can remove this low priority memory to make space, and it doesn’t affect other memory required to sustain the responsiveness of the system.

To wrap up, I’ve called out our philosophy and approach to reducing memory usage in Windows 8. You’ve seen some sample results and I’ve just scratched the surface on some of the engineering work done to date in this area. One thing I haven’t discussed at all is the Windows 8 application model, and process lifecycle changes made to make new Windows 8 apps more “memory friendly.” Look out for this in the //build/ content and in future blog posts, as it’s also a really important part of the story of reimagining Windows.

We’ve already come a long way but we’re not done.

–Bill Karagounis

Building Windows 8