Type System (C++/CX)

By using the Windows Runtime architecture, you can use C++/CX, Visual Basic, Visual C# and JavaScript to write apps and components that directly access the Windows API and interoperate with other Windows Runtime apps and components. Windows Store apps that are written in C++ compile to native code that executes directly in the CPU. Windows Store apps that are written in C# or Visual Basic compile to Microsoft intermediate language (MSIL) and execute in the common language runtime (CLR). Windows Store apps that are written in JavaScript execute in a run-time environment. The Windows Runtime operating system components themselves are written in C++ and run as native code. All of these components and Windows Store apps communicate directly through the Windows Runtime application binary interface (ABI).

To enable support for the Windows Runtime in a modern C++ idiom, Microsoft created the Visual C++ component extensions (C++/CX). C++/CX provides built-in base types and implementations of fundamental Windows Runtime types that enable C++ apps and components to communicate across the ABI with apps that are written in other languages. You can consume any Windows Runtime type, or create classes, structs, interfaces, and other user-defined types that can be consumed by other Windows Store apps and components. A Windows Store app that's written in C++/CX can also use regular C++ classes and structs as long as they don't have public accessibility.

When you compile a Windows Store app that's written in C++, the compiler generates the executable in native machine code, and also generates a separate Windows metadata (.winmd) file that contains descriptions of the public Windows Runtime types, which include classes, structs, enumerations, interfaces, parameterized interfaces, and delegates. The format of the metadata resembles the format that's used in .NET Framework assemblies. In a C++ component, the .winmd file contains only metadata; the executable code resides in a separate file. This is the case for the Windows Runtime components that are included with Windows. The WinMD file name must match or be a prefix of the root namespace in the source code. (For .NET Framework languages, the .winmd file contains both the code and the metadata, just like a .NET Framework assembly.)

The metadata in the .winmd file represents the published surface of your code. Published types are visible to other Windows Stores no matter what language those other apps are written in. Therefore, the metadata, or your published code, can only contain types specified by the Windows Runtime type system. Language constructs that are specific to C++, such as regular classes, arrays, templates or STL containers, cannot be published in metadata because a Javascript or C# client app would not know what to do with them.

Whether a type or method is visible in metadata depends on what accessibility modifiers are applied to it. To be visible, a type must be declared in a namespace and must be declared as public. A non-public ref class is permitted as an internal helper type in your code; it just isn't visible in the metadata. Even in a public ref class, not all members are necessarily visible. The following table lists the relationship between C++ access specifiers in a public ref class, and Windows Runtime metadata visibility:

Published in metadata

Not published in metadata





public protected

private protected

You can use the Object Browser to view the contents of .winmd files. The Windows Runtime components that are included with Windows are in the Windows.winmd file. The default.winmd file contains the fundamental types that are used in C++/CX, and platform.winmd contains additional types from the Platform namespace. By default, these three .winmd files are included in every C++ project for Windows Store apps.

Tip Tip

The types in the Platform::Collections Namespace don't appear in the .winmd file because they are not public. They are private C++-specific implementations of the interfaces that are defined in Windows::Foundation::Collections. A Windows Runtime app that's written in JavaScript or C# doesn't know what a Platform::Collections::Vector Class is, but it can consume a Windows::Foundation::Collections::IVector. The Platform::Collections types are defined in collection.h.

The following sections describe the major features of the Windows Runtime type system and how they are supported in C++/CX.

All Windows Runtime types must be declared within a namespace; the Windows API itself is organized by namespaces. A .winmd file must have the same name that the root namespace has. 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.

The Windows API itself has been reinvented as a well-factored class library that's organized by namespaces. All Windows Runtime components are declared in the Windows.* namespaces.

For more information, see Namespaces and Type Visibility (C++/CX ).

The Windows Runtime defines the following fundamental types, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double, Char16, Boolean, and String. C++/CX supports the fundamental numeric types in its default namespace as uint16, uint32, uint64, int16, int32, int64, float32, float64, and char16. Boolean and String are also defined in the Platform namespace.

C++/CX also defines uint8, equivalent to unsigned char, which is not supported in the Windows Runtime and cannot be used in public APIs.

A fundamental type may be made nullable by wrapping it in a Platform::IBox Interface interface. For more information, see Value classes and structs (C++/CX).

For more information about fundamental types, see Fundamental types (C++/CX)

A Windows Runtime string is an immutable sequence of 16-bit UNICODE characters. A Windows Runtime string is projected as Platform::String^. This class provides methods for string construction, manipulation, and conversion to and from wchar_t.

For more information, see Strings (C++/CX).

The Windows Runtime supports 1-dimensional arrays of any type. Arrays of arrays are not supported. In C++/CX, Windows Runtime arrays are projected as the Platform::Array Class.

For more information, see Array and WriteOnlyArray (C++/CX)

A Windows Runtime class is projected in C++/CX as a ref class or ref struct, because they are copied by reference. Memory management for ref classes and ref structs is handled transparently by means of reference counting. When the last reference to an object goes out of scope, the object is destroyed. A ref class or ref struct can:

  • Contain as members constructors, methods, properties, and events. These members can have public, private, protected, or internal accessibility.

  • Can contain private nested enum, struct, or class definitions.

  • Can directly inherit from one base class and can implement any number of interfaces. All ref classes are implicitly convertible to the Platform::Object Class and can override its virtual methods—for example, Object::ToString.

A ref class that has a public constructor must be declared as sealed, to prevent further derivation.

For more information, see Ref classes and structs (C++/CX)

A value class or value struct represents a basic data structure and contains only fields, which may be value classes, value structs, or type Platform::String^. Value structs and value classes are copied by value.

A value struct can be made nullable by wrapping in an IBox interface.

For more information, see Value classes and structs (C++/CX).

The partial class feature enables one class to be defined over multiple files. It's used primarily to enable code-generation tools such as the XAML editor to modify one file without touching the file that you edit.

For more information, see Partial classes (C++/CX)

A property is a public data member of any Windows Runtime type and is implemented as a get/set method pair. Client code accesses a property as if it were a public field. A property that requires no custom get or set code is known as a trivial property and can be declared without explicit get or set methods.

For more information, see Properties (C++/CX).

The Windows Runtime defines a set of interfaces for collection types that each language implements in its own way. C++/CX provides implementations in the Platform::Collections::Vector Class, Platform::Collections::Map Class, and other related concrete collection types, which are compatible with their Standard Template Library (STL) counterparts.

For more information, see Collections (C++/CX).

Private and internal ref classes can be templated and specialized.

For more information, see Template ref classes (C++/CX).

A Windows Runtime interface defines a set of public properties, methods, and events that a ref class or ref struct must implement if it inherits from the interface.

For more information, see Interfaces (C++/CX).

An enum class in Windows Runtime resembles a scoped enum in C++. The underlying type is int32, unless the [Flags] attribute is applied—in that case, the underlying type is uint32.

For more information, see Enums (C++/CX).

A delegate in the Windows Runtime is analogous to a std::function object in C++. It's a special kind of ref class that's used to invoke client-provided functions that have compatible signatures. Delegates are most commonly used in the Windows Runtime as the type of an event.

For more information, see Delegates (C++/CX).

In C++/CX, you can catch custom exception types, std::exception types, and Platform::Exception types.

For more information, see Exceptions (C++/CX).

An event is a public member in a ref class or ref struct whose type is a delegate type. An event can only be invoked—that is, fired—by the owning class. However, client code can provide its own functions, which are known as event handlers and are invoked when the owning class fires the event.

For more information, see Events (C++/CX).

C++/CX supports the standard C++ cast operators static_cast, dynamic_cast, and reinterpret_cast, and also the safe_cast operator that's specific to C++/CX.

For more information, see Casting (C++/CX).

A boxed variable is a value type that's wrapped in a reference type in situations where reference semantics are required.

For more information, see Boxing (C++/CX).

An attribute is a metadata value that can be applied to any Windows Runtime type or type member and can be inspected at run time. The Windows Runtime defines a set of common attributes in the Windows::Foundation::Metadata namespace. User-defined attributes on public interfaces are not supported by Windows Runtime in this release.

Describes how to mark public APIs as deprecated by using the same attribute that's used by the Windows Runtime system types.

For more information, see Deprecating types and members (C++/CX).

© 2014 Microsoft. All rights reserved.