Microsoft.UI.Xaml.Core.Direct Namespace

Edit

Provides a way for middleware authors to access low-level, high-performance XAML APIs and achieve better CPU and working set performance.

Note

This namespace requires the Microsoft.UI.Xaml.Core.Direct NuGet package, a part of the Microsoft Windows UI Library.

Classes

XamlDirect

Represents the base class for all XamlDirect APIs. All of the XamlDirect APIs are instance methods of this class.

XamlDirect is an API for accessing Xaml at a more primitive level for better CPU and working set performance.

Structs

XamlDirectContract

Interfaces

IXamlDirect

Represents the base class for all XamlDirect APIs. All of the XamlDirect APIs are instance methods of this class.

XamlDirect is an API for accessing Xaml at a more primitive level for better CPU and working set performance.

IXamlDirectObject

Represents the primary object type that participates in the XamlDirect set of APIs.

Enums

XamlEventIndex	Enum that lists all the supported events in XamlDirect.
XamlPropertyIndex	Enum that lists all the supported properties in XamlDirect.
XamlTypeIndex	Enum that lists all the supported types in XamlDirect.

Examples

See the XAML Controls Gallery sample app for examples of WinUI features and controls.

If you have the XAML Controls Gallery app installed, open the app to see the controls in action.

If you don't have the XAML Controls Gallery app installed, get the WinUI 2.x version from the Microsoft Store.

You can also view, clone, and build the XAML Controls Gallery source code from GitHub (switch to the WinUI 3 Preview branch for WinUI 3 Preview controls and features).

The following example shows how to add a value to a collection using XamlDirect APIs.

XamlDirect xd = XamlDirect.GetDefault();

IXamlDirect relativePanel = xd.CreateInstance(XamlTypeIndex.RelativePanel);

IXamlDirect childrenCollection = xd.GetXamlDirectObjectProperty(relativePanel, XamlPropertyIndex.Panel_Children);

IXamlDirect button = xd.CreateInstance(XamlTypeIndex.Button);
xd.AddToCollection(childrenCollection, button);

XamlDirect^ xd = XamlDirect::GetDefault();

IXamlDirect^ relativePanel = xd->CreateInstance(XamlTypeIndex::RelativePanel);

IXamlDirect^ childrenCollection = xd->GetXamlDirectObjectProperty(relativePanel, XamlPropertyIndex::Panel_Children);

IXamlDirect^ button = xd->CreateInstance(XamlTypeIndex::Button);
xd->AddToCollection(childrenCollection, button);

Remarks

XamlDirect is **purpose built for middleware*- that predominantly use imperative APIs to create UI instead of markup. With XamlDirect APIs, you can achieve performance parity with the XAML parser even when creating UI imperatively in code.

XamlDirect APIs can be used side-by-side with traditional APIs and take advantage of the pay for play performance improvements.

Not all Xaml APIs are available with XamlDirect. The XamlTypeIndex enum lists all supported types, the XamlPropertyIndex enum lists all supported properties, and the XamlEventIndex enum lists all supported events.

Supported functions

You can perform the following functions using XamlDirect APIs:

Create an instance of an internal Xaml object for a regular Xaml type, like Button, using Microsoft.UI.Xaml.Core.Direct.IXamlDirect.CreateInstance.
Set property values using one of the appropriate variants of the XamlDirect.Set-Property method based on the type of the property. For example, use SetColorProperty(System.Object,Microsoft.UI.Xaml.Core.Direct.XamlPropertyIndex,Windows.UI.Color) to access the SolidColorBrush.Color property. Similarly use Get-Property methods to access specific properties.
Add an item to a collection, like Panel.Children, using AddToCollection(System.Object,System.Object) and remove items from collections using RemoveFromCollection(System.Object,System.Object) or RemoveFromCollectionAt(System.Object,System.UInt32). XamlDirect supports a variety of such collection operations including GetCollectionCount(System.Object), ClearCollection(System.Object), InsertIntoCollectionAt(System.Object,System.UInt32,System.Object), RemoveFromCollectionAt(System.Object,System.UInt32), and GetXamlDirectObjectFromCollectionAt(System.Object,System.UInt32).
Add an event handler, like Button.Click using AddEventHandler(System.Object,Microsoft.UI.Xaml.Core.Direct.XamlEventIndex,System.Object) and similarly remove event handlers using Microsoft.UI.Xaml.Core.Direct.IXamlDirect.RemoveEventHandler(System.Object,Microsoft.UI.Xaml.Core.Direct.XamlEventIndex,System.Object).

All objects returned by CreateInstance are of type IXamlDirect. All other APIs, such as the Set*Property APIs, take an IXamlDirect as their first parameter.

To convert an IXamlDirect to its full APINDEX, for example a Button, use the GetObject(System.Object) method. Similarly, you can use GetXamlDirectObject to convert from a full Object/DependencyObject to its XamlDirect equivalent instance.