Type system overview (C++/CX)
To enable support for the Windows Runtime in a modern C++ idiom, Microsoft created the C++/CX language extension. C++/CX provides built-in base types and implementations of fundamental Windows Runtime types. These types let C++ apps and components communicate across the ABI with apps written in other languages. C++/CX apps can consume any Windows Runtime type. They may also create classes, structs, interfaces, and other user-defined types that other UWP apps and components can consume. A UWP app that's written in C++/CX can also use regular C++ classes and structs, as long as they don't have public accessibility.
For an in-depth discussion of the C++/CX language projection and how it works under the covers, see these blog posts:
While C++/CX is still supported, we recommend you use C++/WinRT for new Windows Runtime apps and components instead. It's designed to provide you with first-class access to the modern Windows API. Despite the name, C++/WinRT uses only standard C++17 with no extensions. It uses a header-only library to implement a C++ language projection for Windows Runtime APIs. C++/WinRT is available in the Windows SDK from version 1803 (10.0.17134.0) onward.
Windows metadata (.winmd) files
When you compile a UWP 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 is in a separate file. The Windows Runtime components included with Windows use this arrangement. A
.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
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-
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|
You can use the Object Browser to view the contents of
.winmd files. The Windows Runtime components included with Windows are found in the
Windows.winmd file. The
default.winmd file contains the fundamental types that are used in C++/CX, and
platform.winmd contains types from the
Platform namespace. By default, these three
.winmd files are included in every C++ project for UWP apps.
The types in the
Platform::Collections namespace don't appear in the
.winmd file because they're not public. They're private C++-specific implementations of the interfaces that are defined in
Platform::Collections::Vector class is, but it can consume a
Platform::Collections types are defined in
Windows Runtime type system in C++/CX
The following sections describe the major features of the Windows Runtime type system and how they're supported in C++/CX.
All Windows Runtime types must be declared within a namespace; the Windows API itself is organized by namespace. 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.B.C.winmd. The name of the DLL isn't 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
For more information, see Namespaces and type visibility.
The Windows Runtime defines the following fundamental types:
String. C++/CX supports the fundamental numeric types in its default namespace as
String are also defined in the
C++/CX also defines
uint8, equivalent to
unsigned char, which isn't supported in the Windows Runtime and can't be used in public APIs.
For more information about fundamental types, see Fundamental types
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
For more information, see Strings.
The Windows Runtime supports one-dimensional arrays of any type. Arrays of arrays aren't supported. In C++/CX, Windows Runtime arrays are projected as the
For more information, see
ref class and
ref struct types
A Windows Runtime class is projected in C++/CX as a
ref class or
ref struct type, because it's copied by reference. Memory management for
ref class and
ref struct objects is handled transparently through reference counting. When the last reference to an object goes out of scope, the object is destroyed. A
ref class or
ref struct type can:
Contain as members constructors, methods, properties, and events. These members can have
Can contain private nested
Can directly inherit from one base class and can implement any number of interfaces. All
ref classobjects are implicitly convertible to the
Platform::Objectclass and can override its virtual methods—for example,
ref class that has a public constructor must be declared as
sealed, to prevent further derivation.
For more information, see Ref classes and structs
value class and
value struct types
value class or
value struct represents a basic data structure and contains only fields, which may be
value class types,
value struct types, or type
value struct and
value class objects are copied by value.
value struct can be made nullable by wrapping it in an
For more information, see Value classes and structs.
The partial class feature enables one class to be defined over multiple files. It lets code-generation tools such as the XAML editor modify one file without touching another file that you edit.
For more information, see Partial classes
A property is a public data member of any Windows Runtime type. It's declared and defined by using the
property keyword. A property is implemented as a
set method pair. Client code accesses a property as if it were a public field. A property that requires no custom
set code is known as a trivial property and can be declared without explicit
For more information, see Properties.
Windows Runtime collections in 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::Map class, and other related concrete collection types, which are compatible with their C++ Standard Library counterparts.
For more information, see Collections.
ref class types
ref class types can be templated and specialized.
For more information, see Template ref classes.
A Windows Runtime interface defines a set of public properties, methods, and events that a
ref class or
ref struct type must implement if it inherits from the interface.
For more information, see Interfaces.
enum class type in the 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
For more information, see Enums.
A delegate in the Windows Runtime is analogous to a
std::function object in C++. It's a special
ref class type 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.
For more information, see Exceptions.
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 event handler functions, which are invoked when the owning class fires the event.
For more information, see Events.
For more information, see Casting.
A boxed variable is a value type that's wrapped in a reference type. Use boxed variables in situations where reference semantics are required.
For more information, see Boxing.
An attribute is a metadata value that can be applied to any Windows Runtime type or type member. Attributes 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.
You can 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.
Submit and view feedback for