企业官网建设流程全解析

GitHub Copilot 指令实战：用 MVVM 模式构建高质量 .NET WPF 桌面应用

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

instructions/dotnet-wpf.instructions.md是 awesome-copilot 仓库为 WPF 开发场景定制的 Copilot 指令集：当你在.xaml与.cs文件中工作时，它引导 GitHub Copilot 按照 MVVM 模式生成可维护、可测试、性能良好的桌面应用代码。读完本文，你将掌握如何利用这套指令驱动 Copilot 完成 ViewModel 生成、命令重构、异步加载与 UI 响应性优化，并能结合仓库中 CommunityToolkit.Mvvm 的完整技能体系把模式落地到真实项目。

指令文件的作用机制与生效范围

这份指令文件以 YAML frontmatter 声明了两个关键元数据：

--- description: '.NET WPF component and application patterns' applyTo: '**/*.xaml, **/*.cs' ---

• description：用一句话描述指令的用途（".NET WPF 组件与应用模式"），供 Copilot 在匹配场景时快速判断该指令是否相关；
• applyTo：声明生效范围，即所有 XAML 文件与 C# 文件。只要你在这些文件类型中请求 Copilot 生成或修改代码，这套指令就会参与引导。

这与仓库中其他指令的写法保持一致，例如 mvvm-toolkit.instructions.md 通过applyTo: '**/*.cs, **/*.xaml, **/*.csproj'在项目引用CommunityToolkit.Mvvm时强制生效。两者可以协同工作：前者负责 WPF 应用的总体模式，后者负责 MVVM Toolkit 的具体编码约定。

适用场景：什么样的项目适合这套指令

原文档明确了五类理想项目类型，它们构成了这套指令的设计前提：

• 使用C# 与 WPF构建的桌面应用；
• 遵循MVVM（Model-View-ViewModel）设计模式的应用；
• 使用.NET 8.0 或更高版本的项目；
• 以XAML构建 UI 组件的项目；
• 强调性能与响应性的解决方案。

其中 ".NET 8.0+" 是关键前提：现代 WPF 项目默认开启可空引用类型、支持nameof全场景使用，并且可以无缝接入Microsoft.Extensions.DependencyInjection与 .NET Generic Host。如果你正在维护老式 .NET Framework WPF 工程，指令中的部分建议（如源生成器、DI 容器）需要相应降级适配。

指令的核心目标：Copilot 应该帮你做什么

原文档把 WPF 开发的"正确姿势"归纳为六条目标，也是你向 Copilot 提需求时的验收标准：

1. 生成INotifyPropertyChanged与RelayCommand的样板代码；
2. 建议 ViewModel 与 View 逻辑的清晰分离；
3. 鼓励使用ObservableCollection<T>、ICommand与正确的绑定方式；
4. 推荐性能实践（如 UI 虚拟化、异步加载）；
5. 避免过度耦合的代码后置（code-behind）逻辑；
6. 产出可单元测试的 ViewModel。

简而言之：业务逻辑进 ViewModel，View 只负责展示与交互映射。这也是后续所有模式与示例的评判标准。

引导 Copilot：好的提示与要避免的行为

原文档分别给出了"✅ 好的建议"与"❌ 应避免"两类提示行为，这是驱动 Copilot 的关键——指令再好，也需要你以正确的姿势提问。

推荐的提示方式（Good Suggestions）：

• "Generate a ViewModel for a login screen with properties for username and password, and a LoginCommand"——让 Copilot 生成带属性与命令的登录页 ViewModel；
• "Write a XAML snippet for a ListView that uses UI virtualization and binds to an ObservableCollection"——要求 XAML 片段启用虚拟化并绑定到ObservableCollection；
• "Refactor this code-behind click handler into a RelayCommand in the ViewModel"——把代码后置的点击处理器重构为 ViewModel 中的RelayCommand；
• "Add a loading spinner while fetching data asynchronously in WPF"——在异步取数过程中增加加载指示器。

应避免的行为（Avoid）：

• 在代码后置中建议业务逻辑；
• 不加上下文地使用静态事件处理器；
• 生成无绑定的紧耦合 XAML；
• 建议 WinForms 或 UWP 的实现方式（它们与 WPF 的线程模型、绑定机制、控件体系均有差异，混用会产生误导性代码）。

推荐技术栈：指令默认你使用什么

• C# with .NET 8.0+；
• XAML with MVVM 结构；
• CommunityToolkit.Mvvm或自定义RelayCommand实现；
• async/await实现非阻塞 UI；
• ObservableCollection、ICommand、INotifyPropertyChanged。

仓库对此有更细化的约定（见 mvvm-toolkit.instructions.md）：优先引用CommunityToolkit.Mvvm8.x，不要为新项目安装旧的Microsoft.Toolkit.Mvvm7.x；ViewModel 默认继承ObservableObject，只有需要表单校验时才改用ObservableValidator，只有需要收发消息时才改用ObservableRecipient；除非类型无法继承 Toolkit 基类（如自定义控件），否则永远不要手写INotifyPropertyChanged——这既冗长又容易出错。

通用模式：指令贯穿始终的编码约定

原文档列出四项必须遵循的通用模式，它们不限于某个示例，而是 WPF + MVVM 项目的全局纪律：

1. ViewModel-first 绑定：XAML 优先通过绑定指向 ViewModel 的属性与命令，而不是在代码后置中组装数据。View 的DataContext（或 WinUI 场景下的{x:Bind ViewModel.xxx}）直接对接 VM 暴露的成员。
2. 依赖注入（DI）：使用 .NET 自带容器或第三方容器（如 Autofac、SimpleInjector）组织依赖。仓库的 mvvm-toolkit-di/SKILL.md 进一步明确：优先使用 .NET Generic Host（Host.CreateDefaultBuilder()）搭建组合根，让配置、日志与作用域校验自动就绪。
3. XAML 命名约定：控件名用 PascalCase，绑定路径用 camelCase。例如x:Name="PasswordBox"、{Binding UserName}。
4. 绑定中避免魔法字符串：能用nameof的地方绝不用硬编码字符串。nameof(FullName)在重构属性名时会同步报错，而"FullName"会静默失效。

完整示例：登录界面的 ViewModel 与 XAML

原文档提供了一个可复制的完整登录示例，这里保留并逐行说明。

ViewModel（C#）：

public class MainViewModel : ObservableObject { [ObservableProperty] private string userName; [ObservableProperty] private string password; [RelayCommand] private void Login() { // Add login logic here } }

代码注释处的登录逻辑在真实项目中应委托给注入的服务（如IAuthService.LoginAsync(userName, password)），并配合异步命令与加载状态，详见下文"命令最佳实践"。[ObservableProperty]与[RelayCommand]都是源生成器驱动的，这意味着两点硬性要求（仓库 mvvm-toolkit/SKILL.md 明确警告）：使用它们的类必须声明为partial，否则编译报MVVMTK0008/MVVMTK0042；字段名必须是userName、_userName或m_userName这类小驼峰/下划线形式，绝不能写成 PascalCase 的UserName，否则与生成出的属性名冲突。

View（XAML）：

<StackPanel> <TextBox Text="{Binding UserName, UpdateSourceTrigger=PropertyChanged}" /> <PasswordBox x:Name="PasswordBox" /> <Button Content="Login" Command="{Binding LoginCommand}" /> </StackPanel>

几个值得注意的细节：

• UpdateSourceTrigger=PropertyChanged让UserName在用户输入的每一个字符变化时立即写回源属性，配合[NotifyCanExecuteChangedFor]可以让"登录按钮的可用性"随输入实时刷新；
• LoginCommand正是[RelayCommand]从Login()方法生成出的命令属性——方法名去Async/On前缀后加Command后缀（Login→LoginCommand，LoadAsync→LoadCommand）；
• PasswordBox因 WPF 安全策略不暴露可绑定的Password属性，示例用x:Name在代码后置获取值。若要严格遵循 MVVM，可以推断的更优做法是用附加属性将密码桥接到 ViewModel——但需要注意，这只是该场景的常见变通，原示例本身已满足"不把业务逻辑放进 code-behind"的边界。

源码级深化：CommunityToolkit.Mvvm 源生成器能力全景

原指令要求 Copilot "生成INotifyPropertyChanged和RelayCommand样板代码"，仓库的 mvvm-toolkit/SKILL.md 给出了完整的源生成器属性清单，可作为向 Copilot 提需求的"词汇表"：

这些细节的价值在于：当你在提示词中精确指定[NotifyCanExecuteChangedFor]或CanExecute时，Copilot 能生成语义正确而非仅语法正确的代码，避免出现"按钮一直禁用"这类典型的生成器陷阱。

命令最佳实践：同步、异步、可取消与错误策略

原文档强调ICommand与Async/await的配合，仓库 mvvm-toolkit/SKILL.md 给出了可直接复用的命令形态：

[RelayCommand] private void Refresh() => Items.Reset(); [RelayCommand] private async Task LoadAsync() { foreach (var item in await service.GetItemsAsync()) Items.Add(item); } [RelayCommand(IncludeCancelCommand = true)] private async Task DownloadAsync(CancellationToken token) { await using var stream = await http.GetStreamAsync(url, token); // ... } [RelayCommand(CanExecute = nameof(CanSave))] private Task SaveAsync() => repo.SaveAsync(Name!); private bool CanSave() => !string.IsNullOrWhiteSpace(Name);

配套约定（见 mvvm-toolkit.instructions.md）：

• [RelayCommand]方法必须返回void或Task（/Task<T>），绝不能用async void——异常会变成未观察异常；
• 需要可取消的异步任务时，声明CancellationToken参数，可选IncludeCancelCommand = true自动生成配对取消命令；
• CanExecute配合[NotifyCanExecuteChangedFor]保持按钮启用/禁用与输入状态同步；
• AllowConcurrentExecutions默认false，仅当并发调用明确安全时才开启；
• 默认错误策略是 await-and-rethrow；仅当 UI 绑定ExecutionTask渲染错误状态时，才设置FlowExceptionsToTaskScheduler = true。

消息传递：ViewModel 之间如何解耦

多 ViewModel 场景（登录、主题切换、保存后列表刷新）需要跨 VM 通信，仓库的 mvvm-toolkit-messenger/SKILL.md 提供了完整方案，与 WPF 指令"避免紧耦合"的目标完全一致：

• 默认使用WeakReferenceMessenger.Default，接收者被弱引用持有，即使忘记注销也可被 GC 回收；只有性能剖析证明 messenger 是热点时才换StrongReferenceMessenger（强引用下必须注销，否则泄漏）；
• 注册处理器用static (recipient, message) => recipient.OnX(message)形式，禁止捕获this——避免闭包分配与生命周期混乱；
• 在ObservableRecipient上实现IRecipient<TMessage>接口，IsActive = true时OnActivated自动调用RegisterAll(this)注册全部处理器；
• 生命周期钩子：页面OnNavigatedTo设IsActive = true，OnNavigatedFrom设IsActive = false（自动注销）；
• 用频道 token（int/string/Guid）把消息限定到某个子系统或窗口，适合多窗口桌面应用；
• 请求/应答场景使用RequestMessage<T>/AsyncRequestMessage<T>/CollectionRequestMessage<T>系列。

依赖注入：在组合根装配整个应用

原指令点名Dependency Injection为通用模式之一。仓库 mvvm-toolkit-di/SKILL.md 展示了 WPF 项目里最标准的组合根写法——App.xaml.cs中构建 Generic Host：

public partial class App : Application { public IHost Host { get; } public App() { Host = Microsoft.Extensions.Hosting.Host .CreateDefaultBuilder() .ConfigureServices((_, services) => { services.AddSingleton<IFilesService, FilesService>(); services.AddSingleton<ISettingsService, SettingsService>(); services.AddSingleton<IMessenger>(WeakReferenceMessenger.Default); services.AddSingleton<ShellViewModel>(); services.AddTransient<ContactViewModel>(); services.AddTransient<EditorViewModel>(); }) .Build(); } public static T GetService<T>() where T : class => ((App)Current).Host.Services.GetRequiredService<T>(); }

要点：

• 生命周期选择：AddSingleton用于主窗口 VM、设置、文件/HTTP 服务与共享IMessenger；AddTransient用于每页/每文档 VM（每个 resolve 都是新实例）；AddScoped在客户端应用中很少用，仅配合显式IServiceScope（如按窗口建作用域）；
• 构造函数注入：服务与子 VM 一律通过构造函数传入，禁止在 VM 内部调用Ioc.Default.GetService<T>()——服务定位器会隐藏依赖、破坏单测，且让启动期的依赖图校验失效；
• 视图侧解析：页面构造函数中App.GetService<ContactViewModel>()解析根 VM，再由它拉取自己的依赖；导航框架（如Frame.Navigate、Prism）负责解析页面，页面再解析 VM，不要手动newViewModel；
• 开发环境下 Generic Host 自动开启ValidateScopes与ValidateOnBuild，注册错误会在启动期暴露而非首次使用时才崩溃。

可测试性：ViewModel 放进无 UI 依赖的类库

原指令的目标之一是"产出可单元测试的 ViewModel"。仓库 end-to-end-walkthrough.md 推荐的工程布局是：View 留在应用项目，ViewModel 与服务放进独立的 .NET 类库，测试项目引用该类库。由于 MVVM Toolkit 只依赖netstandard2.0+，VM 可以在没有 UI 宿主的情况下直接单测：

[Fact] public async Task SaveCommand_persists_and_broadcasts() { var notes = new FakeNotesService(); var messenger = new WeakReferenceMessenger(); string? receivedFilename = null; messenger.Register<NoteSavedMessage>(new object(), (_, m) => receivedFilename = m.Filename); var vm = new NoteViewModel(notes, messenger) { Filename = "hello.txt", Text = "world" }; await vm.SaveCommand.ExecuteAsync(null); Assert.Single(notes.Saved); Assert.Equal("hello.txt", notes.Saved[0].filename); Assert.Equal("world", notes.Saved[0].text); Assert.Equal("hello.txt", receivedFilename); }

构造函数注入让FakeNotesService与独立WeakReferenceMessenger实例可以无痛替换——这正是指令要求"避免静态事件处理器""避免服务定位器"的原因：静态与全局状态都无法在测试中隔离。

数据绑定与 UI 响应性：虚拟化、异步加载与通知纪律

指令把"UI virtualization、async loading"列为重点性能实践。结合 WPF 语义与仓库约定，可以从以下三个层面落实：

1. 集合绑定与虚拟化：长列表用ListView/ListBox绑定ObservableCollection<T>，依赖 WPF 自带的VirtualizingStackPanel虚拟化容器；不要在ItemTemplate里做重计算，避免逐个构造可视元素导致的卡顿。
2. 异步加载与加载态：用AsyncRelayCommand驱动异步取数，取数期间显示加载指示器；绑定IsRunning或ExecutionTask.Status渲染进度/错误，而不是阻塞 UI 线程。原文档的提示词示例"Add a loading spinner while fetching data asynchronously in WPF"正是这一模式。
3. 通知纪律：ObservableProperty变更必须走生成器（自动触发PropertyChanged）；派生属性用[NotifyPropertyChangedFor(nameof(...))]；不要在[ObservableProperty]之外再手动调用RaisePropertyChanged(nameof(X))（会产生重复通知）；不要原地修改[ObservableProperty]字段持有的同一实例（相等比较器返回true，不会触发通知）——应替换为新实例。

常见误区清单：审查 Copilot 输出时逐条对照

汇总指令与仓库技能共同警告的高频错误（完整诊断表见 mvvm-toolkit/references/troubleshooting.md）：

1. 忘记partial——MVVMTK0008/MVVMTK0042编译错误；
2. [ObservableProperty]字段用 PascalCase——与生成属性冲突；
3. 命令方法用async void——退化为同步命令且异常无法观察；
4. 忘记[NotifyCanExecuteChangedFor]——输入合法了按钮仍是禁用态；
5. 在 ViewModel 构造函数里Ioc.Default.GetService<T>()——隐藏依赖、破坏测试；
6. 强引用 messenger 不注销——接收者被钉住泄漏；
7. messenger 回调捕获this——闭包分配与生命周期混乱；
8. 把所有 VM 都注册成 Singleton——"每文档"VM 变成全局共享状态，造成隐性数据污染；
9. 在代码后置放业务逻辑、用无绑定的静态事件处理器——违背指令核心目标。

仓库配套资源一览

想要进一步深入，可直接查阅以下仓库文件：

• instructions/dotnet-wpf.instructions.md（本指令原文）
• instructions/mvvm-toolkit.instructions.md（MVVM Toolkit 编码约定）
• skills/mvvm-toolkit/SKILL.md（源生成器、命令、校验全景）
• skills/mvvm-toolkit/references/end-to-end-walkthrough.md（完整 Notes 应用走查：VM 类库、组合根、视图接线、单测）
• skills/mvvm-toolkit-di/SKILL.md（Generic Host 组合根、生命周期、keyed services）
• skills/mvvm-toolkit-messenger/SKILL.md（消息传递、频道、生命周期）

这套"指令 + 技能"的组合，正是 awesome-copilot 仓库的工作方式：指令负责在.xaml/.cs编辑现场即时约束 Copilot 的输出，技能则在你需要深度查阅时提供完整的参考文档。把两者一起纳入工作流，Copilot 产出的 WPF 代码就能稳定地落在"MVVM 清晰、可测试、性能合格"的轨道上。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot