Windows.UI.Xaml.Core.Direct Namespace

Reference

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Provides XamlDirect APIs that allow middleware to access most of Xaml at a more primitive level, achieving better CPU and working set performance.

Classes

XamlDirect

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

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

Equivalent WinUI 2 API for UWP: Microsoft.UI.Xaml.Core.Direct.XamlDirect (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Interfaces

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.

Equivalent WinUI 2 API for UWP: Microsoft.UI.Xaml.Core.Direct.XamlEventIndex (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

XamlPropertyIndex

Enum that lists all the supported properties in XamlDirect.

Equivalent WinUI 2 API for UWP: Microsoft.UI.Xaml.Core.Direct.XamlPropertyIndex (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

XamlTypeIndex

Enum that lists all the supported types in XamlDirect.

Equivalent WinUI 2 API for UWP: Microsoft.UI.Xaml.Core.Direct.XamlTypeIndex (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Examples

This example demonstrates how to create objects, set properties, and interface with standard UIElements in 3 ways: using XAML markup, using regular XAML types in C# and the new way using XamlDirect APIs.

In this example, we create a Border element and a Rectangle element and set a few properties on each. Then we add them to the tree of UI elements.

Using XAML markup:

<Grid x:Name="RootGrid">
    <Border BorderBrush="Black" BorderThickness="5">
        <Rectangle Height="100" Width="100" Fill="Red" />
    </Border>
</Grid>

Using regular imperative code, with full XAML types:

Border border = new Border();
border.BorderBrush = new SolidColorBrush(Colors.Black);
border.BorderThickness = new Thickness(5);

Rectangle rectangle = new Rectangle();
rectangle.Height = 100;
rectangle.Width = 100;
SolidColorBrush rectBrush = new SolidColorBrush(Colors.Red);
rectangle.Fill = rectBrush;

border.Child = rectangle;

RootGrid.Children.Add(border);

Using XamlDirect code:

The following code will have higher performance than using full XAML types since all operations like instantiation and setting of properties on various elements are accomplished through IXamlDirectObjects instead of the full XAML types.

XamlDirect xamlDirect = XamlDirect.GetDefault();

IXamlDirectObject border = XamlDirect.CreateInstance(XamlTypeIndex.Border);
xamlDirect.SetThicknessProperty(border, XamlPropertyIndex.Border_BorderThickness, new Thickness(5));

IXamlDirectObject borderBrush = XamlDirect.CreateInstance(XamlTypeIndex.SolidColorBrush);
xamlDirect.SetColorProperty(borderBrush, XamlPropertyIndex.SolidColorBrush_Color, Colors.Black);
xamlDirect.SetXamlDirectObjectProperty(border, XamlPropertyIndex.Border_BorderBrush, borderBrush);

IXamlDirectObject rectangle = XamlDirect.CreateInstance(XamlTypeIndex.Rectangle);
xamlDirect.SetDoubleProperty(rectangle, XamlPropertyIndex.FrameworkElement_Width, 100);
xamlDirect.SetDoubleProperty(rectangle, XamlPropertyIndex.FrameworkElement_Height, 100);

IXamlDirectObject rectBrush = XamlDirect.CreateInstance(XamlTypeIndex.SolidColorBrush);
xamlDirect.SetColorProperty(rectBrush, XamlPropertyIndex.SolidColorBrush_Color, Colors.Red);
xamlDirect.SetXamlDirectObjectProperty(rectangle, XamlPropertyIndex.Shape_Fill, rectangleBrush);

xamlDirect.SetXamlDirectObjectProperty(border, XamlPropertyIndex.Border_Child, rectangle);

RootGrid.Children.Add((UIElement) XamlDirect.GetObject(border));

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 XamlDirect.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 XamlDirect.SetColorProperty to the SolidColorBrush.Color property. Similarly use Get-Property methods to access specific properties.
Add an item to a collection, like Panel.Children, using XamlDirect.AddToCollection and remove items from collections using XamlDirect.RemoveFromCollection. XamlDirect supports a variety of such collection operations including GetCollectionCount, ClearCollection, InsertIntoCollectionAt, RemoveFromCollectionAt and GetXamlDirectObjectFromCollectionAt.
Add an event handler, like Button.Click using XamlDirect.AddEventHandler and similarly remove event handlers using XamlDirect.RemoveEventHandler.

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

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