.NET 10 LTS + WPF + CommunityToolkit.Mvvm 开发环境与流程¶

归档日期：2026-08-25
问题：开发 .NET 10 LTS + WPF + CommunityToolkit.Mvvm，并按需接入 Windows App SDK，需要准备哪些环境？开发流程是什么？

结论¶

推荐的开发基线是：

Windows 11 x64
Visual Studio 2026
  └─ .NET desktop development 工作负载
最新稳定版 .NET 10 SDK（禁止误用 Preview）
Git
NuGet.org 或企业 NuGet 源
WPF + CommunityToolkit.Mvvm
Microsoft.Extensions.Hosting（中大型项目推荐）
Windows App SDK（确认需要某项能力之后再引入）

纯 WPF 项目不需要先安装 WinUI 3，也不需要一开始就引用 Windows App SDK。正确顺序是先建立可测试的 WPF/MVVM 基线，再为通知、App Lifecycle、窗口、MRT Core 等明确需求做 Windows App SDK 技术验证。

当前机器检查结果¶

已对当前工作区所在机器做只读检查：

项目	当前状态	建议
Windows	x64，系统 Build 26200	满足 WPF 和 Windows App SDK 开发要求
.NET 10 SDK	已安装稳定版 `10.0.102`，同时安装了 `10.0.200-preview`	更新到当前最新稳定版 .NET 10 SDK；创建 `global.json` 禁止误选 Preview
当前实际选中的 SDK	`10.0.200-preview.0.26103.119`	不应作为正式项目默认 SDK
.NET 10 Runtime	当前列出的稳定运行时为 `10.0.2`	官方当前补丁已更新，应通过 Visual Studio Installer 或 .NET 下载页更新安全与服务补丁
Visual Studio	Visual Studio 2022 Community 17.14	安装 Visual Studio 2026，以获得完整 .NET 10 / C# 14 IDE 支持
.NET 桌面工作负载	VS 2022 中已安装	在 VS 2026 中也勾选 `.NET desktop development`
Windows SDK	Windows 11 SDK 26100 组件已安装	可继续使用；让 VS Installer 保持最新受支持版本
Git	`2.51.0.windows.1`	已满足要求
Windows App Runtime	本机已存在多个 1.x/2.x Runtime	本机开发基本具备条件，但发布时仍必须部署项目实际依赖的匹配版本

没有 global.json 时，.NET CLI 会选择机器上最高版本的 SDK，并可能在命令行环境中选择预览版。这正是本机当前使用 Preview SDK 的原因。

一、安装和配置开发环境¶

1. 操作系统¶

推荐 Windows 11 最新稳定版本。Windows App SDK 支持 Windows 10 1809 及更高版本，但开发机使用 Windows 11 更容易覆盖当前工具链、SDK 和系统 API。

需要根据目标客户环境确定最低支持版本，不要等到发布时才决定。最低版本会影响 Windows API、Windows App SDK、安装方式以及测试矩阵。

2. Visual Studio¶

安装 Visual Studio 2026 Community、Professional 或 Enterprise，在 Visual Studio Installer 中勾选：

.NET desktop development：WPF 必需。
当前稳定的 .NET 10 SDK / Runtime。
当前受支持的 Windows 11 SDK。
Windows application development / Windows App SDK 相关组件：只有接入 Windows App SDK、MSIX 或 WinUI 相关工具时才需要补充。
Git for Windows：如果机器没有单独安装。

纯 WPF 不需要 C++ 工作负载。只有使用原生 C++ 项目、特殊 Win32 SDK、非打包 Windows App SDK 的特定部署依赖或原生库编译时，才安装 Desktop development with C++。

Visual Studio 2026 对 .NET 10 和 C# 14 提供完整支持。Visual Studio 2022 可以继续维护其支持范围内的项目，但不应作为新建 .NET 10 WPF 项目的标准 IDE。

3. .NET 10 LTS SDK¶

安装最新稳定的 .NET 10 SDK，然后检查：

dotnet --info
dotnet --list-sdks
dotnet --list-runtimes

正式项目应提交 global.json，避免不同开发机或 CI 误用 .NET 11 Preview、.NET 10 Preview 或不一致的 feature band。

更新稳定 SDK 后，将实际安装的稳定版本写入文件。例如当前机器临时可以使用：

{
  "sdk": {
    "version": "10.0.102",
    "rollForward": "latestPatch",
    "allowPrerelease": false
  }
}

更合理的做法是先更新到当前最新稳定版 SDK，再用该版本替换 10.0.102。团队希望允许整个 .NET 10 范围内的更新时，可以采用 latestFeature；严格可重复构建时使用 latestPatch 或精确版本，并让 CI 安装同一 SDK。

创建命令示例：

dotnet new globaljson --sdk-version 10.0.102 --roll-forward latestPatch

然后手动加入：

"allowPrerelease": false

4. NuGet 与网络¶

至少需要访问：

NuGet.org，或者包含所需包的企业镜像源。
Microsoft 包和 Windows App SDK 下载源。
代码仓库和 CI 服务。

企业环境应提交 NuGet.config，明确包源和源映射，避免开发机各自使用不同镜像。不要把账号密码或令牌提交到仓库。

5. 可选工具¶

GitHub Desktop、Azure DevOps 或其他仓库客户端。
Windows Terminal、PowerShell 7。
WPF Gallery：查看现代 Fluent Theme 控件效果。
Windows App SDK / WinUI Gallery：接入相关功能时查看官方示例。
Sysinternals、PerfView、Visual Studio Profiler：诊断启动、内存和 UI 卡顿。
数据库管理工具：仅在项目确实使用 SQL Server、SQLite 等数据库时安装。

二、创建解决方案¶

以下以 DesktopProduct 为例。对于小型应用，不需要建立很多空项目；建议从“应用 + 核心 + 测试”开始：

DesktopProduct/
├─ global.json
├─ DesktopProduct.sln
├─ src/
│  ├─ DesktopProduct.App/       # WPF、View、ViewModel、启动与平台适配
│  └─ DesktopProduct.Core/      # 领域模型、用例和不依赖 WPF 的接口
└─ tests/
   └─ DesktopProduct.Core.Tests/

创建命令：

New-Item -ItemType Directory -Path DesktopProduct
Set-Location DesktopProduct

dotnet new globaljson --sdk-version 10.0.102 --roll-forward latestPatch
dotnet new sln -n DesktopProduct --format sln

dotnet new wpf -n DesktopProduct.App -o src/DesktopProduct.App -f net10.0
dotnet new classlib -n DesktopProduct.Core -o src/DesktopProduct.Core -f net10.0
dotnet new xunit -n DesktopProduct.Core.Tests -o tests/DesktopProduct.Core.Tests -f net10.0

dotnet sln DesktopProduct.sln add src/DesktopProduct.App/DesktopProduct.App.csproj
dotnet sln DesktopProduct.sln add src/DesktopProduct.Core/DesktopProduct.Core.csproj
dotnet sln DesktopProduct.sln add tests/DesktopProduct.Core.Tests/DesktopProduct.Core.Tests.csproj

dotnet add src/DesktopProduct.App/DesktopProduct.App.csproj reference src/DesktopProduct.Core/DesktopProduct.Core.csproj
dotnet add tests/DesktopProduct.Core.Tests/DesktopProduct.Core.Tests.csproj reference src/DesktopProduct.Core/DesktopProduct.Core.csproj

说明：dotnet new wpf -f net10.0 会生成 Windows 专用的 WPF 目标框架；不必在命令参数里写 net10.0-windows。

安装 MVVM 和宿主基础设施：

dotnet add src/DesktopProduct.App/DesktopProduct.App.csproj package CommunityToolkit.Mvvm
dotnet add src/DesktopProduct.App/DesktopProduct.App.csproj package Microsoft.Extensions.Hosting

小型工具如果不需要配置、日志、依赖注入和后台服务，可以暂时只安装 CommunityToolkit.Mvvm。中大型项目推荐 Generic Host，因为它统一提供 DI、Configuration、Logging 和应用服务生命周期，而且微软已有 WPF 官方接入指南。

首次验收：

dotnet restore
dotnet build DesktopProduct.sln -c Debug
dotnet test DesktopProduct.sln -c Debug --no-build
dotnet run --project src/DesktopProduct.App/DesktopProduct.App.csproj

三、建立 MVVM 基线¶

1. ViewModel¶

使用 MVVM Toolkit 的源生成器减少模板代码：

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace DesktopProduct.App.ViewModels;

public partial class MainViewModel : ObservableObject
{
    [ObservableProperty]
    private string title = "DesktopProduct";

    [RelayCommand]
    private void ChangeTitle()
    {
        Title = "已更新";
    }
}

View：

<StackPanel Margin="24">
    <TextBlock Text="{Binding Title}" FontSize="24" />
    <Button Content="更新" Command="{Binding ChangeTitleCommand}" />
</StackPanel>

2. 使用 Generic Host¶

采用 Microsoft.Extensions.Hosting 时：

从 App.xaml 删除 StartupUri="MainWindow.xaml"。
在 App.xaml.cs 创建和启动 IHost。
注册窗口、ViewModel、业务服务、配置和日志。
从 DI 容器获得 MainWindow 并显示。
应用退出时停止并释放 Host。

注册关系示例：

services.AddSingleton<MainWindow>();
services.AddSingleton<MainViewModel>();
services.AddSingleton<IClock, SystemClock>();

窗口使用构造函数注入：

public MainWindow(MainViewModel viewModel)
{
    InitializeComponent();
    DataContext = viewModel;
}

避免在各处调用静态 ServiceLocator。窗口、ViewModel 和服务由组合根统一创建，单元测试直接构造 ViewModel 并注入假服务。

3. 分层原则¶

View：只处理 XAML、视觉状态以及无法合理绑定的纯 UI 行为。
ViewModel：页面状态、命令、验证和用例协调。
Core/Application：业务规则和用例，不引用 WPF。
Infrastructure：数据库、HTTP、文件系统和外部设备实现；项目变大后再拆出独立项目。
Platform：通知、注册表、系统托盘、窗口句柄等 Windows 专用实现。

不要在 ViewModel 中直接暴露 Brush、Visibility、Window、Dispatcher、MessageBox 或其他 System.Windows.* 类型。它们会降低测试性，也会增加未来迁移成本。

四、日常功能开发流程¶

每项功能建议采用下面的纵向流程：

定义需求和验收条件：输入、输出、异常、权限、离线行为和性能目标。
先建领域/服务接口：把文件、网络、数据库、系统 API 隔离在接口后面。
实现并测试业务逻辑：Core 层不启动 UI 也能测试。
实现 ViewModel：使用 ObservableObject、ObservableProperty、RelayCommand 或 AsyncRelayCommand。
编写 XAML View：绑定 ViewModel，不在 code-behind 堆业务逻辑。
运行与 Hot Reload：验证布局、DPI、亮暗主题、键盘操作和窗口缩放。
补充异常与日志：区分用户可恢复错误、程序错误和外部系统错误。
执行质量检查：格式化、静态分析、构建、单元测试和关键 UI 冒烟测试。
在干净环境验证发布物：目标电脑不应依赖开发机已经安装的 SDK 或 Runtime。

常用命令：

dotnet format DesktopProduct.sln
dotnet build DesktopProduct.sln -c Release
dotnet test DesktopProduct.sln -c Release --no-build
dotnet run --project src/DesktopProduct.App/DesktopProduct.App.csproj

异步开发规则：

I/O 使用 async/await 和 AsyncRelayCommand。
不在 UI 线程调用 .Result、.Wait() 或执行大计算。
可取消的长操作传递 CancellationToken。
只在更新 UI 对象时切回 Dispatcher。
命令执行期间通过 CanExecute 或状态属性防止重复提交。

五、按需接入 Windows App SDK¶

什么时候才接入¶

先明确具体能力，例如：

App Lifecycle、激活和单实例协调。
AppWindow 或较新的窗口能力。
Windows App SDK 通知、资源或文本能力。
必须依赖包标识的 Windows 功能。

如果只是 WPF 窗口、文件对话框、普通托盘、WebView2 或基础 Win32 API，不一定需要整个 Windows App SDK。先检查 .NET、WPF、WinRT 或小型专用包能否直接完成需求。

接入步骤¶

在独立分支或最小原型中验证目标 API。
从官方 Stable channel 选择 Windows App SDK，不在生产项目使用 Preview/Experimental。
添加 NuGet 包：

dotnet add src/DesktopProduct.App/DesktopProduct.App.csproj package Microsoft.WindowsAppSDK

根据要调用的 WinRT API 和客户系统基线设置目标 Windows 版本。
决定应用是 MSIX packaged、packaged with external location，还是 unpackaged。
完成 Runtime 初始化、部署和干净机器验证。

非打包 WPF 应用¶

普通 WPF 应用默认是 unpackaged。使用 Windows App SDK 时，可在应用项目的 PropertyGroup 中配置自动初始化：

<WindowsPackageType>None</WindowsPackageType>

这会让生成的 auto-initializer 在应用启动时寻找并加载合适的 Windows App SDK Runtime。高级场景如果需要自定义错误处理或精确选择 Runtime，再改用 Bootstrapper API。

注意：

<WindowsPackageType>None</WindowsPackageType> 适用于非打包路线；采用 MSIX 时不要机械照搬。
开发机装有 Runtime 不代表客户机也有。
framework-dependent 发布必须安装匹配的 Windows App SDK Runtime。
self-contained Windows App SDK 发布会携带更多依赖，但仍需验证包体、架构和单文件限制。
非打包应用还可能需要 Visual C++ Redistributable。
WPF 不能直接把 WinUI XAML 当作 WPF XAML 使用；需要 WinUI 控件时要单独评估 XAML Islands，而不是混用命名空间。

六、配置、日志与敏感信息¶

Generic Host 可以统一读取 appsettings.json、环境变量和命令行参数，并提供 ILogger<T>。

建议：

可提交的默认设置放 appsettings.json。
用户设置和缓存放 %LocalAppData%\公司名\产品名。
需要漫游的非敏感设置才考虑 %AppData%。
密码、客户端密钥和长期令牌不能硬编码或放入公开配置。
桌面客户端无法安全保存可代表整个系统的服务端秘密；这类秘密必须留在后端。
用户凭据按场景使用 Windows Credential Manager、DPAPI 或系统身份方案。

日志至少应覆盖：

应用版本、系统版本和架构。
启动、配置加载和依赖初始化。
未处理异常及外部服务失败。
Windows App SDK Runtime 初始化失败。
更新、迁移和数据库版本。

不要记录密码、令牌、完整身份证号或其他敏感数据。

七、测试策略¶

单元测试¶

重点测试：

Core 业务规则。
ViewModel 状态变化和命令。
验证、取消、重试和异常分支。
服务接口的组合逻辑。

ViewModel 不依赖 WPF 类型，测试时就不需要启动 Dispatcher 或窗口。

集成测试¶

数据库迁移和仓储。
HTTP API 合约。
文件读写与权限。
Windows API 和设备接口。
Windows App SDK Runtime 与激活路径。

UI 和人工验收¶

100%、125%、150%、200% DPI。
多显示器和不同缩放比例。
亮色、暗色、高对比度。
纯键盘操作、Tab 顺序和屏幕阅读器基础检查。
最低支持 Windows 版本和当前 Windows 11。
x64；需要时单独测试 ARM64。
中文、英文、长文本和不同字体回退。

八、CI 流程¶

使用 Windows 构建代理，例如 GitHub Actions Windows runner 或 Azure Pipelines：

checkout
→ 安装 global.json 指定的稳定 .NET 10 SDK
→ dotnet restore
→ dotnet format --verify-no-changes
→ dotnet build -c Release --no-restore
→ dotnet test -c Release --no-build
→ dotnet publish
→ 签名与打包
→ 上传构件

建议提交：

global.json。
Directory.Build.props，统一 Nullable、分析级别和警告规则。
Directory.Packages.props，项目较多时集中管理 NuGet 版本。
包锁定文件或等效的可重复还原策略。
CI 配置和发布说明。

不要依赖构建代理预装的“最新版”SDK；CI 必须从仓库配置决定 SDK 和包版本。

九、发布流程¶

1. 先选部署模型¶

Microsoft Store / 普通商业应用：优先评估 MSIX。
企业内部分发：MSIX + Intune/Configuration Manager，或现有企业部署系统。
已有内网自动更新：WPF 可继续使用 ClickOnce。
复杂驱动、服务、注册和传统安装要求：MSI/EXE。
简单内部工具：可以自包含文件夹发布，但要自行处理更新和签名。

2. 选择运行时模式¶

框架依赖发布：

dotnet publish src/DesktopProduct.App/DesktopProduct.App.csproj `
  -c Release -r win-x64 --self-contained false `
  -o artifacts/publish/win-x64

自包含发布：

dotnet publish src/DesktopProduct.App/DesktopProduct.App.csproj `
  -c Release -r win-x64 --self-contained true `
  -o artifacts/publish/win-x64-self-contained

dotnet publish 产生的是发布文件，不等同于完整安装器。MSIX、MSI/EXE、签名和自动更新仍需单独配置。

3. 发布门禁¶

Release 构建和全部测试通过。
版本号、更新通道、回滚策略确定。
EXE、DLL、安装包按分发要求签名。
在没有 Visual Studio、SDK 和预装目标 Runtime 的干净虚拟机测试。
验证安装、首次启动、升级、降级限制和卸载。
验证离线、代理、防火墙和无管理员权限场景。
如果接入 Windows App SDK，验证匹配 Runtime 缺失时的处理。

十、推荐的完整开发节奏¶

准备稳定工具链并用 global.json 锁定
→ 创建 WPF + Core + Tests
→ 接入 MVVM Toolkit 和 Generic Host
→ 建立日志、配置、异常处理和主题基线
→ 按纵向功能开发 ViewModel + View + Tests
→ 仅为明确能力引入 Windows App SDK
→ 每次提交执行格式化、构建和测试
→ CI 在 Windows 干净环境生成 Release 构件
→ 签名、打包、更新和干净机器验收
→ 分阶段发布并监控崩溃与更新结果

当前机器的下一步清单¶

安装 Visual Studio 2026，并选择 .NET desktop development。
更新到最新稳定的 .NET 10 SDK/Runtime 补丁。
在仓库根目录创建 global.json，设置 allowPrerelease: false，避免继续选中本机的 10.0.200-preview。
用 dotnet --info 确认实际选中稳定 SDK。
创建 WPF 解决方案并添加 CommunityToolkit.Mvvm。
项目达到中等规模时添加 Microsoft.Extensions.Hosting。
暂不添加 Microsoft.WindowsAppSDK；出现明确功能需求后再做最小原型。
在第一个可运行版本之前确定 MSIX、ClickOnce 或 MSI/EXE 发布路线。