Windows Runtime base data types

This table lists the base data types that are supported by the Windows Runtime, and indicates the corresponding type in C#, Visual Basic, and C++.

Data type	JavaScript	C#	VB	C++
Boolean	Boolean	bool	Boolean	bool
Byte	Number	byte	Byte	unsigned char
Char	String	char	Char	unsigned char
Char16	String	char	Char	wchar_t
DateTime	Date	DateTimeOffset	DateTimeOffset	DateTime
Double	Number	double	Double	double
Guid	String	Guid	Guid	Guid
Int16	Number	short	Short	short
Int32	Number	int	Integer	int
Int64	Number	long	Long	__int64
Object	Object	object	Object	Object^
Point	Point	Point	Point	Point
Rect	Rect	Rect	Rect	Rect
Single	Number	float	Single	float
Size	Size	Size	Size	Size
String	String	string	String	String^
TimeSpan	Number	TimeSpan	TimeSpan	TimeSpan
UInt8	Number	byte	Byte	unsigned char
UInt16	Number	ushort	UShort	unsigned short
UInt32	Number	uint	UInteger	unsigned int
UInt64	Number	ulong	ULong	unsigned __int64
Uri	Uri	Uri	Uri	Uri^
Void	Undefined	void	Void	void

The following table indicates the .NET types that correspond to the Windows Runtime data types.

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.