Windows Runtime components with C++/CX

This topic exists to help you maintain your C++/CX application. But we recommend that you use C++/WinRT for new applications. C++/WinRT is an entirely standard modern C++17 language projection for Windows Runtime (WinRT) APIs, implemented as a header-file-based library, and designed to provide you with first-class access to the modern Windows API. To learn how to create a Windows Runtime component using C++/WinRT, see Windows Runtime components with C++/WinRT.

This topic shows how to use C++/CX to create a Windows Runtime component—a component that’s callable from a Universal Windows app built using any Windows Runtime language (C#, Visual Basic, C++, or Javascript).

There are several reasons for building a Windows Runtime component in C++.

• To get the performance advantage of C++ in complex or computationally intensive operations.
• To reuse code that’s already written and tested.

When you build a solution that contains a JavaScript or .NET project, and a Windows Runtime component project, the JavaScript project files and the compiled DLL are merged into one package, which you can debug locally in the simulator or remotely on a tethered device. You can also distribute just the component project as an Extension SDK. For more information, see Creating a Software Development Kit.

In general, when you code your C++/CX component, use the regular C++ library and built-in types, except at the abstract binary interface (ABI) boundary where you are passing data to and from code in another .winmd package. There, use Windows Runtime types and the special syntax that C++/CX supports for creating and manipulating those types. In addition, in your C++/CX code, use types such as delegate and event to implement events that can be raised from your component and handled in JavaScript, Visual Basic, C++, or C#. For more information about the C++/CX syntax, see Visual C++ Language Reference (C++/CX).

Casing and naming rules

JavaScript

JavaScript is case-sensitive. Therefore, you must follow these casing conventions:

• When you reference C++ namespaces and classes, use the same casing that’s used on the C++ side.
• When you call methods, use camel casing even if the method name is capitalized on the C++ side. For example, a C++ method GetDate() must be called from JavaScript as getDate().
• An activatable class name and namespace name can’t contain UNICODE characters.

The .NET languages follow their normal casing rules.

Instantiating the object

Only Windows Runtime types can be passed across the ABI boundary. The compiler will raise an error if the component has a type like std::wstring as a return type or parameter in a public method. The Visual C++ component extensions (C++/CX) built-in types include the usual scalars such as int and double, and also their typedef equivalents int32, float64, and so on. For more information, see Type System (C++/CX).

C++/CX built-in types, library types, and Windows Runtime types

An activatable class (also known as a ref class) is one that can be instantiated from another language such as JavaScript, C# or Visual Basic. To be consumable from another language, a component must contain at least one activatable class.

A Windows Runtime component can contain multiple public activatable classes as well as additional classes that are known only internally to the component. Apply the WebHostHidden attribute to C++/CX types that are not intended to be visible to JavaScript.

All public classes must reside in the same root namespace which has the same name as the component metadata file. For example, a class that’s named A.B.C.MyClass can be instantiated only if it’s defined in a metadata file that’s named A.winmd or A.B.winmd or A.B.C.winmd. The name of the DLL is not required to match the .winmd file name.

Client code creates an instance of the component by using the new (New in Visual Basic) keyword just as for any class.

An activatable class must be declared as public ref class sealed. The ref class keyword tells the compiler to create the class as a Windows Runtime compatible type, and the sealed keyword specifies that the class cannot be inherited. The Windows Runtime does not currently support a generalized inheritance model; a limited inheritance model supports creation of custom XAML controls. For more information, see Ref classes and structs (C++/CX).

For C++/CX, all the numeric primitives are defined in the default namespace. The Platform namespace contains C++/CX classes that are specific to the Windows Runtime type system. These include Platform::String class and Platform::Object class. The concrete collection types such as Platform::Collections::Map class and Platform::Collections::Vector class are defined in the Platform::Collections namespace. The public interfaces that these types implement are defined in Windows::Foundation::Collections Namespace (C++/CX). It is these interface types that are consumed by JavaScript, C# and Visual Basic. For more information, see Type System (C++/CX).

Method that returns a value of built-in type

Method that returns a custom value struct

To pass user-defined value structs across the ABI, define a JavaScript object that has the same members as the value struct that’s defined in C++/CX. You can then pass that object as an argument to a C++/CX method so that the object is implicitly converted to the C++/CX type.

Another approach is to define a class that implements IPropertySet (not shown).

In the .NET languages, you just create a variable of the type that’s defined in the C++/CX component.

Overloaded Methods

A C++/CX public ref class can contain overloaded methods, but JavaScript has limited ability to differentiate overloaded methods. For example, it can tell the difference between these signatures:

But it can’t tell the difference between these:

In ambiguous cases, you can ensure that JavaScript always calls a specific overload by applying the Windows::Foundation::Metadata::DefaultOverload attribute to the method signature in the header file.

This JavaScript always calls the attributed overload:

The .NET languages recognize overloads in a C++/CX ref class just as in any .NET class.

DateTime

In the Windows Runtime, a Windows::Foundation::DateTime object is just a 64-bit signed integer that represents the number of 100-nanosecond intervals either before or after January 1, 1601. There are no methods on a Windows:Foundation::DateTime object. Instead, each language projects the DateTime in the way that is native to that language: the Date object in JavaScript and the System.DateTime and System.DateTimeOffset types in .NET.

When you pass a DateTime value from C++/CX to JavaScript, JavaScript accepts it as a Date object and displays it by default as a long-form date string.

When a .NET language passes a System.DateTime to a C++/CX component, the method accepts it as a Windows::Foundation::DateTime. When the component passes a Windows::Foundation::DateTime to a .NET method, the Framework method accepts it as a DateTimeOffset.

Collections and arrays

Collections are always passed across the ABI boundary as handles to Windows Runtime types such as Windows::Foundation::Collections::IVector^ and Windows::Foundation::Collections::IMap^. For example, if you return a handle to a Platform::Collections::Map, it implicitly converts to a Windows::Foundation::Collections::IMap^. The collection interfaces are defined in a namespace that’s separate from the C++/CX classes that provide the concrete implementations. JavaScript and .NET languages consume the interfaces. For more information, see Collections (C++/CX) and Array and WriteOnlyArray (C++/CX).

Passing IVector

The .NET languages see IVector as IList .

Passing IMap

The .NET languages see IMap and IDictionary .

Properties

A public ref class in C++/CX component extensions exposes public data members as properties, by using the property keyword. The concept is identical to .NET properties. A trivial property resembles a data member because its functionality is implicit. A non-trivial property has explicit get and set accessors and a named private variable that’s the «backing store» for the value. In this example, the private member variable _propertyAValue is the backing store for PropertyA. A property can fire an event when its value changes, and a client app can register to receive that event.

The .NET languages access properties on a native C++/CX object just as they would on a .NET object.

Delegates and events

A delegate is a Windows Runtime type that represents a function object. You can use delegates in connection with events, callbacks, and asynchronous method calls to specify an action to be performed later. Like a function object, the delegate provides type-safety by enabling the compiler to verify the return type and parameter types of the function. The declaration of a delegate resembles a function signature, the implementation resembles a class definition, and the invocation resembles a function invocation.

Adding an event listener

You can use the event keyword to declare a public member of a specified delegate type. Client code subscribes to the event by using the standard mechanisms that are provided in the particular language.

This example uses the same C++ code as for the previous properties section.

In the .NET languages, subscribing to an event in a C++ component is the same as subscribing to an event in a .NET class:

Adding multiple event listeners for one event

JavaScript has an addEventListener method that enables multiple handlers to subscribe to a single event.

In C#, any number of event handlers can subscribe to the event by using the += operator as shown in the previous example.

Enums

A Windows Runtime enum in C++/CX is declared by using public class enum; it resembles a scoped enum in standard C++.

Enum values are passed between C++/CX and JavaScript as integers. You can optionally declare a JavaScript object that contains the same named values as the C++/CX enum and use it as follows.

Both C# and Visual Basic have language support for enums. These languages see a C++ public enum class just as they would see a .NET enum.

Asynchronous methods

To consume asynchronous methods that are exposed by other Windows Runtime objects, use the task Class (Concurrency Runtime). For more information, see and Task Parallelism (Concurrency Runtime).

To implement asynchronous methods in C++/CX, use the create_async function that’s defined in ppltasks.h. For more information, see Creating Asynchronous Operations in C++/CX for UWP apps. For an example, see Walkthrough of creating a C++/CX Windows Runtime component, and calling it from JavaScript or C#. The .NET languages consume C++/CX asynchronous methods just as they would any asynchronous method that’s defined in .NET.

Exceptions

You can throw any exception type that’s defined by the Windows Runtime. You cannot derive custom types from any Windows Runtime exception type. However, you can throw COMException and provide a custom HRESULT that can be accessed by the code that catches the exception. There’s no way to specify a custom Message in a COMException.

Debugging tips

When you debug a JavaScript solution that has a component DLL, you can set the debugger to enable either stepping through script, or stepping through native code in the component, but not both at the same time. To change the setting, select the JavaScript project node in Solution Explorer and then choose Properties, Debugging, Debugger Type.

Be sure to select appropriate capabilities in the package designer. For example, if you are attempting to open an image file in the user’s Pictures library by using the Windows Runtime APIs, be sure to select the Pictures Library check box in the Capabilities pane of the manifest designer.

If your JavaScript code doesn’t seem to be recognizing the public properties or methods in the component, make sure that in JavaScript you are using camel casing. For example, the LogCalc C++/CX method must be referenced as logCalc in JavaScript.

If you remove a C++/CX Windows Runtime component project from a solution, you must also manually remove the project reference from the JavaScript project. Failure to do so prevents subsequent debug or build operations. If necessary, you can then add an assembly reference to the DLL.

Windows Runtime via C#

English | 2013 | ISBN: 978-0-7356-7927-6 | 320 Pages | PDF | 12 MB

Delve inside the Windows Runtime – and learn best ways to design and build Windows Store apps. Guided by Jeffrey Richter, a recognized expert in Windows and .NET programming, along with principal Windows consultant Maarten van de Bospoort, you’ll master essential concepts. And you’ll gain practical insights and tips for how to architect, design, optimize, and debug your apps.
With this book, you will:
Learn how to consume Windows Runtime APIs from C#
Understand the principles of architecting Windows Store apps
See how to build, deploy, and secure app packages
Understand how apps are activated and the process model controlling their execution
Study the rich features available when working with files and folders
Explore how to transfer, compress, and encrypt data via streams
Design apps that give the illusion of running using live tiles, background transfers, and background tasks
Share data between apps using the clipboard and the Share charm
Get advice for monetizing your apps through the Windows Store
About This Book:
Requires working knowledge of Microsoft .NET Framework, C#, and the Visual Studio IDE
Targeted to programmers building Windows Store apps
Some chapters also useful to those building desktop apps
Technologies Covered:
Windows 8.1
Microsoft Visual Studio 2013

Windows Runtime C++ Template Library (WRL)

The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

WRL is now superseded by C++/WinRT, a standard C++17 language projection for Windows Runtime APIs. C++/WinRT is available in the Windows 10 SDK from version 1803 onward. C++/WinRT is implemented entirely in header files, and designed to provide you with first-class access to the modern Windows API.

With C++/WinRT, you can both consume and author Windows Runtime APIs using any standards-compliant C++17 compiler. C++/WinRT typically performs better and produces smaller binaries than any other language option for the Windows Runtime. We will continue to support C++/CX and WRL, but highly recommend that new applications use C++/WinRT. For more information, see C++/WinRT.

Benefits

The Windows Runtime C++ Template Library enables you to more easily implement and consume Component Object Model (COM) components. It provides housekeeping techniques like reference-counting to manage the lifetime of objects and testing HRESULT values to determine whether an operation succeeded or failed. To successfully use the Windows Runtime C++ Template Library, you must carefully follow these rules and techniques.

The C++/CX is a high-level, language-based way to use Windows Runtime components. Both the Windows Runtime C++ Template Library and C++/CX simplify the writing of code for the Windows Runtime by automatically performing housekeeping tasks on your behalf.

The Windows Runtime C++ Template Library and C++/CX provide different benefits. Here are some reasons you might want to use the Windows Runtime C++ Template Library instead of C++/CX:

Windows Runtime C++ Template Library adds little abstraction over the Windows Runtime Application Binary Interface (ABI), giving you the ability to control the underlying code to better create or consume Windows Runtime APIs.

C++/CX represents COM HRESULT values as exceptions. If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don’t have to use exceptions.

The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. In addition, the Windows Runtime C++ Template Library uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. For more info about smart pointers and RAII, see Smart Pointers and Objects Own Resources (RAII).

The purpose and design of the Windows Runtime C++ Template Library is inspired by the Active Template Library (ATL), which is a set of template-based C++ classes that simplify the programming of COM objects. Because Windows Runtime C++ Template Library uses standard C++ to wrap the Windows Runtime, you can more easily port and interact with many existing COM components written in ATL to the Windows Runtime. If you already know ATL, you might find that Windows Runtime C++ Template Library programming is easier.

Getting Started

Here are some resources that can help you get working with the Windows Runtime C++ Template Library right away.

The Windows Runtime Library (WRL)
In this Channel 9 video, learn more about how the Windows Runtime C++ Template Library helps you write Universal Windows Platform (UWP) apps and how to author and consume Windows Runtime components.

How to: Activate and Use a Windows Runtime Component
Shows how to use the Windows Runtime C++ Template Library to initialize the Windows Runtime and activate and use a Windows Runtime component.

How to: Complete Asynchronous Operations
Shows how to use the Windows Runtime C++ Template Library to start asynchronous operations and perform work when the operations complete.

How to: Handle Events
Shows how to use the Windows Runtime C++ Template Library to subscribe to and handle the events of a Windows Runtime object.

How to: Create a Classic COM Component
Shows how to use the Windows Runtime C++ Template Library to create a basic COM component and a basic way to register and consume the COM component from a desktop app.

How to: Instantiate WRL Components Directly
Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

How to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

Walkthrough: Connecting Using Tasks and XML HTTP Requests
Shows how to use the IXMLHTTPRequest2 and IXMLHTTPRequest2Callback interfaces together with tasks to send HTTP GET and POST requests to a web service in a UWP app.

Bing Maps Trip Optimizer sample
Uses the HttpRequest class that’s defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete UWP app.

Creating a Windows Runtime DLL component with C++ sample
Shows how to use the Windows Runtime C++ Template Library to create an in-process DLL component and consume it from C++/CX, JavaScript, and C#.

DirectX marble maze game sample
Demonstrates how to use the Windows Runtime C++ Template Library to manage the lifetime of COM components such as DirectX and Media Foundation in the context of a complete 3-D game.

Toast notifications from desktop apps
Demonstrates how to send toast notifications from a desktop app.

Windows Runtime C++ Template Library Compared to ATL

Windows Runtime C++ Template Library resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. Windows Runtime C++ Template Library and ATL also share concepts such as definition of objects in modules, explicit registration of interfaces, and open creation of objects by using factories. You might be comfortable with Windows Runtime C++ Template Library if you’re familiar with ATL.

Windows Runtime C++ Template Library supports the COM functionality that is required for UWP apps. Therefore, it differs from the ATL because it omits direct support for COM features such as: