From d693e80561d5b3b8285f98473f0817b5c59876f0 Mon Sep 17 00:00:00 2001 From: hoshiizumiya Date: Fri, 26 Jun 2026 00:33:37 +0800 Subject: [PATCH 1/3] Update x:Load attribute documentation Clarified restrictions and usage notes for x:Load attribute, including details on x:Bind interactions and error handling. --- hub/apps/develop/platform/xaml/x-load-attribute.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/hub/apps/develop/platform/xaml/x-load-attribute.md b/hub/apps/develop/platform/xaml/x-load-attribute.md index 065e926c2e..902fdc5a39 100644 --- a/hub/apps/develop/platform/xaml/x-load-attribute.md +++ b/hub/apps/develop/platform/xaml/x-load-attribute.md @@ -18,7 +18,8 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to > The x:Load attribute is available starting in Windows 10, version 1703 (Creators Update). The min version targeted by your Visual Studio project must be *Windows 10 Creators Update (10.0, Build 15063)* in order to use x:Load. ## XAML attribute usage - +> [!Caution] +> Regarding the 'Window' is not a DependencyObject. You can not use it in which the xaml root is the Window because the [FindName method](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) needs. Check it at https://github.com/microsoft/microsoft-ui-xaml/issues/9842. ``` syntax @@ -29,7 +30,7 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to There are several different ways to load the elements: -- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element. +- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element. The x:Name you set and the x:Bind binding name should not be the same if you use x:Bind in the x:Load or the xaml complier will report an error. - Call [**FindName**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) with the name that you defined on the element. - Call [**GetTemplateChild**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.gettemplatechild) with the name that you defined on the element. - In a [**VisualState**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.VisualState), use a [**Setter**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Setter) or **Storyboard** animation that targets the x:Load element. @@ -63,10 +64,12 @@ The restrictions for using **x:Load** are: - You must define an [x:Name](x-name-attribute.md) for the element, as there needs to be a way to find the element later. - You can only use x:Load on types that derive from [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement) or [**FlyoutBase**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Primitives.FlyoutBase). -- You cannot use x:Load on root elements in a [**Page**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page), a [**UserControl**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol), or a [**DataTemplate**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.DataTemplate). +- You cannot use x:Load on root elements in a [**Window**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.window), a [**Page**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page), a [**UserControl**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol), or a [**DataTemplate**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.DataTemplate). - You cannot use x:Load on elements in a [**ResourceDictionary**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.ResourceDictionary). - You cannot use x:Load on loose XAML loaded with [**XamlReader.Load**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.markup.xamlreader.load). - Moving a parent element will clear out any elements that have not been loaded. +- In the C++/WinRT, Compile error when using x:Load and x:Bind. Check it and workaround at https://github.com/microsoft/microsoft-ui-xaml/issues/7579. +- In the C++/WinRT, FindName wont reload an object that has been UnloadObjected. Check it at https://github.com/microsoft/microsoft-ui-xaml/issues/10179. ## Remarks From efc0661fed9b26a2db1fd80222d2045a254c8306 Mon Sep 17 00:00:00 2001 From: hoshiizumiya Date: Fri, 26 Jun 2026 11:58:54 +0800 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- hub/apps/develop/platform/xaml/x-load-attribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/apps/develop/platform/xaml/x-load-attribute.md b/hub/apps/develop/platform/xaml/x-load-attribute.md index 902fdc5a39..ae183bbaf1 100644 --- a/hub/apps/develop/platform/xaml/x-load-attribute.md +++ b/hub/apps/develop/platform/xaml/x-load-attribute.md @@ -30,7 +30,7 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to There are several different ways to load the elements: -- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element. The x:Name you set and the x:Bind binding name should not be the same if you use x:Bind in the x:Load or the xaml complier will report an error. +- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element. If you use `x:Bind` in `x:Load`, don't set `x:Name` to the same identifier as the binding path; otherwise, the XAML compiler reports an error. - Call [**FindName**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) with the name that you defined on the element. - Call [**GetTemplateChild**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.gettemplatechild) with the name that you defined on the element. - In a [**VisualState**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.VisualState), use a [**Setter**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Setter) or **Storyboard** animation that targets the x:Load element. From 8551a1217d2771920c9f76bf25b5e9f27509688e Mon Sep 17 00:00:00 2001 From: hoshiizumiya Date: Fri, 26 Jun 2026 12:05:06 +0800 Subject: [PATCH 3/3] clarify --- hub/apps/develop/platform/xaml/x-load-attribute.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/hub/apps/develop/platform/xaml/x-load-attribute.md b/hub/apps/develop/platform/xaml/x-load-attribute.md index ae183bbaf1..9e2beb833a 100644 --- a/hub/apps/develop/platform/xaml/x-load-attribute.md +++ b/hub/apps/develop/platform/xaml/x-load-attribute.md @@ -18,8 +18,10 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to > The x:Load attribute is available starting in Windows 10, version 1703 (Creators Update). The min version targeted by your Visual Studio project must be *Windows 10 Creators Update (10.0, Build 15063)* in order to use x:Load. ## XAML attribute usage -> [!Caution] -> Regarding the 'Window' is not a DependencyObject. You can not use it in which the xaml root is the Window because the [FindName method](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) needs. Check it at https://github.com/microsoft/microsoft-ui-xaml/issues/9842. + + > [!CAUTION] + > In the WinUI, [FindName](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) doesn't work when the XAML root element is a `Window`. For details, see [microsoft-ui-xaml #9842](https://github.com/microsoft/microsoft-ui-xaml/issues/9842). + ``` syntax @@ -68,8 +70,8 @@ The restrictions for using **x:Load** are: - You cannot use x:Load on elements in a [**ResourceDictionary**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.ResourceDictionary). - You cannot use x:Load on loose XAML loaded with [**XamlReader.Load**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.markup.xamlreader.load). - Moving a parent element will clear out any elements that have not been loaded. -- In the C++/WinRT, Compile error when using x:Load and x:Bind. Check it and workaround at https://github.com/microsoft/microsoft-ui-xaml/issues/7579. -- In the C++/WinRT, FindName wont reload an object that has been UnloadObjected. Check it at https://github.com/microsoft/microsoft-ui-xaml/issues/10179. +- In C++/WinRT, using `x:Load` with `x:Bind` can produce a compile error. For details and a workaround, see [microsoft-ui-xaml #7579](https://github.com/microsoft/microsoft-ui-xaml/issues/7579). +- In C++/WinRT, `FindName` doesn't reload an object that was previously unloaded using `UnloadObject`. For details, see [microsoft-ui-xaml #10179](https://github.com/microsoft/microsoft-ui-xaml/issues/10179). ## Remarks