Microsoft.UI.Xaml.Core.Direct Namespace
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.
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.
This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
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. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces). |
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. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces). |
Enums
| XamlEventIndex |
Enum that lists all the supported events in XamlDirect. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces). |
| XamlPropertyIndex |
Enum that lists all the supported properties in XamlDirect. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces). |
| XamlTypeIndex |
Enum that lists all the supported types in XamlDirect. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces). |
Examples
Tip
The WinUI 3 Gallery and WinUI 2 Gallery apps include interactive examples of most WinUI 3 and WinUI 2 controls, features, and functionality.
If installed already, open them by clicking the following links: WinUI 3 Gallery or WinUI 2 Gallery.
If they are not installed, you can download the WinUI 3 Gallery and the WinUI 2 Gallery from the Microsoft Store.
You can also get the source code for both from GitHub (use the main branch for WinUI 3 and the winui2 branch for WinUI 2).
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.