.NET 8 WinUI3项目无法找到CommunityToolkit.WinUI.Controls命名空间

问题描述 #

开发WinUI 3 + .NET 8应用时，已通过NuGet安装CommunityToolkit.WinUI.Controls包，但在XAML中使用SettingsCard控件时出现以下错误：

• CS0234：命名空间'CommunityToolkit.WinUI'中不存在类型或命名空间名称'Controls'（是否缺少程序集引用?）
• XLS0429：未定义命名空间。'using' URI引用的命名空间'CommunityToolkit.WinUI.Controls'无法找到。
• XLS0414：未找到类型'controls:SettingsCard'。请验证是否缺少程序集引用，且所有引用的程序集均已生成。

已添加的XAML命名空间声明：

xmlns:controls="using:CommunityToolkit.WinUI.Controls"
xmlns:ui="using:CommunityToolkit.WinUI"

使用的XAML代码示例：

<Page
    x:Class="Easy_Minecraft_Gui_WinUI3.SettingsPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:Easy_Minecraft_Gui_WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:controls="using:CommunityToolkit.WinUI.Controls"
    xmlns:ui="using:CommunityToolkit.WinUI"
    mc:Ignorable="d"
    Background="Transparent">
    
    <Grid>
        <StackPanel Spacing="4">
            <controls:SettingsCard x:Name="settingsCard"
                                   Description="This is a default card, with the Header, HeaderIcon, Description and Content set."
                                   Header="This is the Header"
                                   HeaderIcon="{ui:FontIcon Glyph=&#xE799;}"
                                   IsEnabled="{x:Bind IsCardEnabled, Mode=OneWay}">
                <ComboBox SelectedIndex="0">
                    <ComboBoxItem>Option 1</ComboBoxItem>
                    <ComboBoxItem>Option 2</ComboBoxItem>
                    <ComboBoxItem>Option 3</ComboBoxItem>
                </ComboBox>
            </controls:SettingsCard>
        </StackPanel>
    </Grid>
</Page>

已尝试的操作：

• 通过NuGet安装CommunityToolkit.WinUI.Controls包
• 添加对应XAML命名空间声明
• 多次重建项目
• 清理解决方案后重建
• 更新Visual Studio和Community Toolkit到最新版本

解决方法 #

1. 确认NuGet包的安装范围 #

右键当前项目 → 选择「管理NuGet程序包」，在「已安装」标签下确认CommunityToolkit.WinUI.Controls包已安装到当前应用项目（而非解决方案中的其他类库项目），避免因安装位置错误导致引用失效。

2. 验证包版本与.NET 8的兼容性 #

确保安装的CommunityToolkit.WinUI.Controls版本支持.NET 8。目前v8.x及以上的稳定版已支持.NET 8，若安装的是旧版本，建议在NuGet包管理器中更新到最新稳定版。

3. 检查项目目标框架设置 #

右键项目 → 属性 → 应用，确认目标框架为.NET 8 (Windows)，且Windows App SDK版本不低于1.4（WinUI 3的最低兼容版本要求）。

4. 手动添加程序集引用 #

若NuGet自动引用失效，可手动添加：

• 右键项目 → 添加 → 引用
• 选择「浏览」，找到项目packages目录下的CommunityToolkit.WinUI.Controls.dll（路径示例：packages\CommunityToolkit.WinUI.Controls.x.x.x\lib\net8.0-windows10.0.19041.0，x.x.x为包版本号），添加该程序集引用。

5. 清理Visual Studio缓存 #

关闭Visual Studio，删除以下内容后重新打开项目重建：

• 项目目录下的bin和obj文件夹
• %LOCALAPPDATA%\Microsoft\VisualStudio\<你的VS版本号>\ComponentModelCache目录中的缓存文件

6. 验证命名空间正确性 #

在代码文件中手动添加using CommunityToolkit.WinUI.Controls;，若编辑器无法识别该命名空间，说明包未正确安装或引用，需重新安装NuGet包并检查项目引用配置。

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