WinForms Islands中无法实例化含NavigationView的WinUI类库页面/控件

问题场景 #

WinForms应用通过WinUI Island加载WinUI 3类库中的页面/用户控件时，遇到以下异常：

• 控件包含NavigationView时，构造函数抛出Microsoft.UI.Xaml.Markup.XamlParseException，提示“XAML parsing failed”
• 运行时创建带NavigationView的Grid并设置为DesktopWindowXamlSource.Content时，无提示抛出COMException
• 控件包含ListBox、Button等其他元素时加载正常；直接在XAML中嵌入NavigationView也可正常运行

加载代码示例：

var c = new MyWinUILibrary.MyFabulousPage();
gridHost.Children.Add(c);

解决步骤 #

1. 同步SDK版本 #

检查WinForms应用与WinUI 3类库的Microsoft.WindowsAppSDK NuGet包版本是否完全一致。版本不匹配会导致NavigationView这类依赖SDK特性的控件初始化失败，建议统一升级到最新正式版。

2. 初始化WinUI应用环境 #

WinForms中托管WinUI Island时，需提前完成WinUI应用环境初始化，NavigationView依赖此环境运行。在WinForms应用入口（如Program.cs）添加以下代码：

using Microsoft.UI.Xaml;

// 在Application.Run之前执行
WinRT.ComWrappersSupport.InitializeComWrappers();
var winuiApp = new Application();
winuiApp.InitializeComponent();

3. 调整控件托管方式 #

避免直接将类库中的控件添加到GridHost，改用DesktopWindowXamlSource托管：

var xamlSource = new DesktopWindowXamlSource();
var navPage = new MyWinUILibrary.MyFabulousPage();
xamlSource.Content = navPage;

// 将DesktopWindowXamlSource附加到WinForms容器
var hwndHost = new WindowsFormsHost();
hwndHost.Child = xamlSource;
yourWinFormsPanel.Controls.Add(hwndHost);

4. 排查NavigationView的XAML配置 #

简化类库中NavigationView的XAML代码，排除语法或配置错误：

<NavigationView>
    <NavigationView.MenuItems>
        <NavigationViewItem Content="首页"/>
    </NavigationView.MenuItems>
</NavigationView>

确认无未正确绑定的属性、缺失的资源引用等问题，这类问题在类库中可能不暴露，仅跨环境加载时触发解析异常。

5. 启用调试日志定位细节 #

在WinForms应用的App.config中添加日志配置，获取XAML解析的详细错误信息：

<configuration>
    <system.diagnostics>
        <sources>
            <source name="Microsoft.UI.Xaml" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch">
                <listeners>
                    <add name="console" type="System.Diagnostics.ConsoleTraceListener"/>
                </listeners>
            </source>
        </sources>
        <switches>
            <add name="SourceSwitch" value="Verbose"/>
        </switches>
    </system.diagnostics>
</configuration>

运行应用后查看控制台输出，定位具体的解析失败原因（如资源缺失、属性错误等）。

内容的提问来源于stack exchange，提问作者Nick