Avalonia预览器类型解析失败：无效标记问题求助

阿华AIGC实验室

2026-6-12

问题描述

将WPF应用移植到Avalonia以实现在Linux上运行，创建了两个项目：AvaUIBase（类库项目）和CrossApp（主应用项目）。类库中存放所有资源字典、样式及自定义控件（如SearchBox、Expanders等），其他控件均正常工作，但创建用于Datagrid的CustomDataGrid用户控件（为Datagrid添加带不同背景的边框和表格标题）时，预览器持续抛出无法解析类型的XamlX.XamlTypeSystemException错误。

错误信息

[Error] [PreviewerProcess (#46378660)] XamlX.XamlTypeSystemException: Unable to resolve type AvaUIBase.Controls.DataGridTable.CustomDataGrid
   at XamlX.TypeSystem.XamlTypeSystemExtensions.GetType(IXamlTypeSystem sys, String type)
   at Avalonia.Markup.Xaml.XamlIl.CompilerExtensions.AvaloniaXamlIlCompiler.Parse(String xaml, IXamlType overrideRootType)
   at Avalonia.Markup.Xaml.XamlIl.AvaloniaXamlIlRuntimeCompiler.LoadGroupSreCore(IReadOnlyCollection`1 documents, RuntimeXamlLoaderConfiguration configuration)
   at Avalonia.Markup.Xaml.XamlIl.AvaloniaXamlIlRuntimeCompiler.LoadSreCore(RuntimeXamlLoaderDocument document, RuntimeXamlLoaderConfiguration configuration)
   at Avalonia.Markup.Xaml.XamlIl.AvaloniaXamlIlRuntimeCompiler.LoadSre(RuntimeXamlLoaderDocument document, RuntimeXamlLoaderConfiguration configuration)
   at Avalonia.Markup.Xaml.XamlIl.AvaloniaXamlIlRuntimeCompiler.Load(RuntimeXamlLoaderDocument document, RuntimeXamlLoaderConfiguration configuration)
   at Avalonia.Markup.Xaml.AvaloniaRuntimeXamlLoader.Load(RuntimeXamlLoaderDocument document, RuntimeXamlLoaderConfiguration configuration)
   at AvaloniaUI.Previewer.DesignerSupport.Design.DesignWindowLoader.LoadDesignerWindow(String xaml, Assembly assembly, String xamlFileProjectPath)
   at AvaloniaUI.Previewer.DesignerSupport.Design.WindowSlot.ApplyXaml(String xaml, Assembly assembly, String projectPath)
   at AvaloniaUI.Previewer.DesignerSupport.Remote.RemoteDesignWindowManager.<>c__DisplayClass19_1.<OnTransportMessage>b__9()

相关代码

AXAML文件

<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:local="clr-namespace:AvaUIBase.Controls.DataGridTable.CustomDataGrid"
             mc:Ignorable="d"
             Background="Transparent"
             x:Class="AvaUIBase.Controls.DataGridTable.CustomDataGrid"
             Name="CustomDataGrid">

  Welcome to Avalonia!
</UserControl>

代码后台

using Avalonia;
using Avalonia.Controls;
using Avalonia.Markup.Xaml;

namespace AvaUIBase.Controls.DataGridTable;

public partial class CustomDataGrid : UserControl
{
    public CustomDataGrid()
    {
        InitializeComponent();
    }
}

项目文件（Update 1）

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
        <AssemblyName>AvaUIBase</AssemblyName>
    </PropertyGroup>

    <ItemGroup>
      <AvaloniaResource Include="Assets\Images\Remove.png" />
      <AvaloniaResource Include="Assets\Images\Search.png" />
      <AvaloniaResource Include="Themes\CalendarTime\UITimePicker.axaml" />
      <AvaloniaResource Include="Themes\Calendar\CalendarDateSelector.axaml" />
    </ItemGroup>

    <ItemGroup>
        <PackageReference Include="Avalonia" Version="12.0.4" />
        <PackageReference Include="Avalonia.Markup.Xaml.Loader" Version="12.0.4" />
        <PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.2" />
        <PackageReference Include="Material.Icons.Avalonia" Version="3.0.2" />
    </ItemGroup>

    <ItemGroup>
        <Folder Include="MVVM\Models\Event\" />
    </ItemGroup>

    <ItemGroup>
      <Compile Update="Controls\DateTimeSelect\DateTimeSelector.axaml.cs">
        <DependentUpon>DateTimeSelector.axaml</DependentUpon>
      </Compile>
    </ItemGroup>
    
    <ItemGroup>
      <Compile Update="Controls\DataGridTable\CustomDataGrid.axaml.cs">
        <DependentUpon>CustomDataGrid.axaml</DependentUpon>
      </Compile>
    </ItemGroup>
</Project>

解决方案

问题根源及修复步骤：

命名空间声明错误：AXAML中xmlns:local的取值错误地包含了类名CustomDataGrid，正确的命名空间应与后台代码的namespace一致。
修正AXAML的命名空间声明：
```
xmlns:local="clr-namespace:AvaUIBase.Controls.DataGridTable"
```
缺少资源注册：项目文件未将CustomDataGrid.axaml注册为Avalonia资源，预览器无法加载该文件。在项目的<AvaloniaResource>节点中添加：
```
<AvaloniaResource Include="Controls\DataGridTable\CustomDataGrid.axaml" />
```
清理解决方案，重新生成项目后再打开预览器即可解决类型解析错误。