The sample demonstrates the basics of how to create a Windows Phone Runtime component and consume it in your Windows Phone 8 app. A Windows Phone Runtime component is a Windows Runtime component that can run on the phone. The sample highlights three scenarios. The first scenario illustrates calling synchronous and asynchronous methods to perform a computation. The second scenario uses the same computation component to demonstrate progress reporting and cancelling long-running tasks. The third scenario demonstrates how to use a component to wrap logic that uses XAudio2 APIs to play a sound on the phone.

This sample shows you how to:

  • Create a Windows Runtime component.

  • Implement an asynchronous API in your component.

  • Implement progress and cancellation in your component.

  • Consume Windows Runtime components in your XAML app.

For more info about the sample, see Sample description.

Note:

The terms Windows Runtime component and Windows Phone Runtime component are used interchangeably throughout this document to refer to a Windows Runtime component that is created to use in a Windows Phone 8 app.

Build the sample

  1. Start Visual Studio Express 2012 for Windows Phone and select File > Open > Project/Solution.

  2. Go to the directory in which you unzipped the sample. Double-click the Visual Studio Express 2012 for Windows Phone solution (.sln) file.

  3. Use Build > Rebuild Solution to build the sample.

Run the sample

  • To debug the app and then run it, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

Sample description

This sample contains the following three projects.

  • PhoneApp. This is the XAML phone app written in C# that consumes the Windows Runtime components built in this sample. It consists of a Panorama page, on which each scenario is displayed using a separate PanoramaItem.

  • ComputeComponent_Phone. This is a Windows Runtime component written in C++. The component exposes methods for performing some computations – one method adds two numbers, and another finds all prime numbers in a range. The actual computations are for illustration purposes only, to demonstrate the power of using Windows Phone Runtime components. The component was created in the solution by selecting File > New Project > Visual C++ > Windows Phone > Windows Phone Runtime Component. You can create these projects only by using C++ in Windows Phone 8.

  • AudioComponent_Phone. This is a Windows Runtime component written in C++. The component exposes methods to play and stop a sound. It also has methods to suspend and resume the audio engine, which prevents unnecessary battery drain in your app when the sound isn’t needed.

Creating a Windows Runtime component for Windows Phone 

The following steps describe how to create a Windows Runtime component and then use it in your phone app. These components often are referred to as third-party Windows Runtime components, to distinguish them from the first-party Windows Runtime APIs that you get in the platform. In Windows Phone 8 we also refer to them as Windows Phone Runtime components because they are created using a project template specifically designed to use for Windows Phone 8 and can only be consumed by Windows Phone 8 apps. We’ll use these names interchangeably to refer to components written to use in your Windows Phone 8 app. Part of the output generated by these projects is a Windows metadata (.winmd) file, which has the extension .winmd. This file contains the metadata required for all supported languages to consume the functionality you expose in your component.

Remember that Windows Phone 8 only supports creating Windows Runtime components in C++, but can be consumed by phone apps and other Windows Runtime components written in C++, C#, and Visual Basic. The Visual Studio project template we use to create the Windows Phone Runtime component project sets up everything that’s required to create a .winmd file that you can consume in your app. In this example, we’ll assume the phone app that is consuming the component is a XAML app written in C#, but the steps also apply to apps written in Visual Basic or C++.

  1. Create a Windows Phone Runtime component project and add it to your solution. Right-click your solution in Solution Explorer and then select Add > New Project > Windows Phone > Windows Phone Runtime Component. This creates a new project in your solution. Make sure you select the Windows Phone Runtime Component project template from the set of Windows Phone templates and not the Windows Runtime Component template from the set of Windows Store templates. A Windows Runtime Component template is not compatible with Windows Phone 8.

  2. Define the component classes, or API, that you want to expose to your app. You need to define one or more classes to be able to use your new component in your app. Because Windows Runtime components can be consumed by multiple languages, the types visible to the consumer of the component are restricted to those that can be published in the .winmd file. For example, types must be declared in a namespace and must be declared as public. These classes, or types, must also be declared as a ref class and declared as sealed because inheritance is not allowed. To learn about the complete type system and limitations on public types your component can expose, see Visual C++ Language Reference (C++/CX).

    Implement the interface. Although there are restrictions for the types that are visible from your component, you have a lot more freedom in what you use privately inside your component. This way you can use Win32, COM, XAudio2, and Direct3D APIs inside the component to implement features and functionality that you want to use in your Windows Phone app. In this sample, we use XAudio2 APIs to play sound. We create a Windows Runtime component that implements a class with methods such as PlaySound and StopSound. Inside the component, we call in to the powerful XAudio2 APIs to do the heavy lifting. To use these APIs we need to reference the correct header files and link to xaudio2.lib. To call XAudio2 APIs, add xaudio2.lib to the list of Additional Dependencies in the Property Pages dialog of your component’s project, and include xaudio2.h in your pch.h header file. Remember to add the library to the Additional Dependencies for each project configuration – Debug, Release, etc.

  3. Reference the component from your phone app project. To use your component in your app, you’ll need to add a reference in your phone app project for that component. In Solution Explorer, right-click your main project, and then click Add Reference. In the Add Reference dialog, in the left pane click Solution. Your new Windows Runtime component now appears in the center pane of the dialog. In the Name column, select the project you want to reference. Click OK to finish adding the reference to your project. When you expand the list of references in your project you’ll now see a reference to your component. Build your solution to verify that everything compiles correctly.

  4. Build, test, validate. As you develop your component be sure you regularly build the solution and test the functionality as you proceed. You can also debug your component and step through its logic to make sure works as expected. If your phone app is written in C# or Visual Basic, you can still debug the native code of your Windows Runtime component by selecting Native Only for the Debugger Type setting in the Debug properties of your Windows Phone app. You can’t debug native code and managed code at the same time, so use this setting to toggle between native and managed code debugging.

See also