.NET/C 最佳实践技能指南：基于 GitHub Copilot Agents 的代码质量保障方案

.NET/C# 最佳实践技能指南基于 GitHub Copilot Agents 的代码质量保障方案【免费下载链接】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本文围绕 awesome-copilot 仓库中面向 .NET/C# 的 Copilot Agent 技能skills/dotnet-best-practices/SKILL.md展开系统梳理其在解决方案/项目级代码中强制执行的十类最佳实践——从文档结构与命名空间、设计模式、依赖注入到资源本地化、异步编程、测试标准、配置校验、Semantic Kernel AI 集成、错误处理与安全性能。读完本文你将掌握该技能在 Copilot 会话中的完整应用方式并理解每一条规则背后的仓库级佐证设计模式审查、C# 指令、DDD 架构指南、Copilot SDK 食谱等可直接将其作为团队 .NET 代码评审与生成的自动化检查基线。技能定位让 Copilot 成为 .NET 代码质量的守门人dotnet-best-practices是一个标准的 GitHub Copilot Agent 技能文件其元数据声明了它的触发方式与职责--- name: dotnet-best-practices description: Ensure .NET/C# code meets best practices for the solution/project. ---技能本体给出明确任务边界确保 ${selection} 中的 .NET/C# 代码符合该解决方案/项目的特定最佳实践。其中${selection}是 Copilot 会话中用户选中的代码片段或文件范围意味着该技能以对选中代码进行合规审查与纠正为核心工作方式而非泛泛的编码建议。这与仓库中 skills/dotnet-design-pattern-review/SKILL.md 形成互补后者是只评审不改动的设计模式审查员前者则是确保代码满足最佳实践的主动执行者。技能覆盖十个维度下文按原文档骨架逐一展开并结合仓库内相关的 instructions 与 cookbook 佐证其底层要求。文档与结构XML 注释与命名空间规范技能要求对所有公开类、接口、方法、属性编写完整的 XML 文档注释且注释必须包含参数说明与返回值说明。这一要求在 instructions/csharp.instructions.md 中有更细化的落地规则公共 API 必须编写 XML doc 注释并在适用时加入example与code块让文档具备可运行的示例价值使用nameof替代字符串字面量引用成员名保证重构时注释不腐化。命名空间必须遵循{Core|Console|App|Service}.{Feature}的层级约定即按项目类型Core 库、Console 应用、App、Service加业务功能域组织。这与 instructions/dotnet-architecture-good-practices.instructions.md 强调的 DDD 分层Domain/Application/Infrastructure以及 skills/dotnet-design-pattern-review/SKILL.md 审查清单中是否遵循{Core|Console|App|Service}.{Feature}命名空间约定是否保持了 Core/Console 项目之间的正确分离完全一致说明命名空间规范是贯穿整个技能族的架构红线。设计模式与架构主构造函数、命令处理器与接口隔离技能在该节提出了四条硬性要求每一条都能在仓库的设计模式审查技能中找到对应审查点1. 主构造函数Primary Constructor注入依赖。要求使用public class MyClass(IDependency dependency)语法。这是 C# 12 引入的语法糖与仓库 instructions/csharp.instructions.md 中始终使用最新版 C#的指导相呼应。2. Command Handler 模式 泛型基类。要求实现CommandHandlerTOptions这类泛型基类。该模式在 skills/dotnet-design-pattern-review/SKILL.md 中被细化为一整套契约泛型基类CommandHandlerTOptionsICommandHandlerTOptions接口CommandHandlerOptions继承体系静态SetupCommand(IHost host)方法用于在 Host 上注册命令同时审查改进重点明确指出校验逻辑应放在基类、错误处理保持一致、资源管理得当——这正是泛型基类带来的收益把横切关注点收敛到基类子类只写业务。3. 接口隔离与命名。接口统一以I前缀命名如IUserService与 instructions/csharp.instructions.md 的命名约定完全一致。4. 工厂模式。复杂对象创建使用工厂模式配合服务提供者集成。设计模式审查技能补充了其关注点依赖配置、IServiceProvider集成与释放Disposal模式。依赖注入与服务构造函数注入与生命周期管理技能要求使用构造函数注入并通过ArgumentNullException做空值校验服务按 Singleton、Scoped、Transient 三种生命周期注册遵循Microsoft.Extensions.DependencyInjection模式为可测试性实现服务接口。实现要点示例public class WeatherService : IWeatherService { private readonly IHttpClientFactory _httpClientFactory; public WeatherService(IHttpClientFactory httpClientFactory) { _httpClientFactory httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory)); } }在 instructions/dotnet-architecture-good-practices.instructions.md 的 DDD 应用层规范中使用构造函数注入获取依赖是强制项而为可测试性实现服务接口则直接服务于该文档定义的测试标准依赖通过接口抽象、可 mock、与 AAA 模式兼容。注册生命周期时应注意Singleton 适合无状态或全局共享服务Scoped 适合每个请求/作用域一个实例如 DbContextTransient 适合轻量无状态服务选错生命周期是并发缺陷与内存泄漏的常见根源。资源管理与本地化ResourceManager 与资源文件拆分技能要求使用ResourceManager提供本地化消息与错误字符串将LogMessages与ErrorMessages拆分到独立资源文件通过_resourceManager.GetString(MessageKey)访问资源。这一资源模式同样出现在 skills/dotnet-design-pattern-review/SKILL.md 的 Required Design Patterns 清单中审查点包括是否为本地化消息使用 ResourceManager、是否拆分独立的 .resx 文件LogMessages、ErrorMessages。将日志消息与错误消息分文件管理的好处是日志字符串可以随日志系统集中审计错误消息则与 UI 展示/用户反馈绑定二者的维护节奏与本地化要求不同拆分后互不干扰。异步/等待模式全链路 async/await技能对异步编程的要求非常明确所有 I/O 操作与长时间运行任务使用 async/await异步方法返回Task或TaskT在适当位置使用ConfigureAwait(false)正确处理异步异常。这份要求在仓库的 Copilot SDK C# 指令instructions/copilot-sdk-csharp.instructions.md中体现得淋漓尽致——SDK 本身全程使用 async/await 模式且通过IAsyncDisposable实现资源清理。其推荐的客户端与会话管理范式如下await using var client new CopilotClient(); await client.StartAsync(); await using var session await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest PermissionHandler.ApproveAll, Model gpt-5, Streaming true }); var done new TaskCompletionSource(); session.On(evt { if (evt is AssistantMessageEvent msg) { Console.WriteLine(msg.Data.Content); } else if (evt is SessionIdleEvent) { done.SetResult(); } }); await session.SendAsync(new MessageOptions { Prompt What is 22? }); await done.Task;注意其中的await usingIAsyncDisposable与TaskCompletionSource等待事件这两个模式正是正确处理异步资源与异常的最佳实践样例可作为技能该节的实证参考完整可运行示例见 cookbook/copilot-sdk/dotnet/README.md 与 cookbook/copilot-sdk/dotnet/error-handling.md。测试标准MSTest FluentAssertions Moq 的 AAA 三件套技能规定的测试栈为MSTest 框架 FluentAssertions 断言 Moq 模拟依赖遵循 Arrange/Act/Assert 三阶段模式并明确要求覆盖成功、失败与空参数校验三类场景。instructions/dotnet-architecture-good-practices.instructions.md 对测试的补充约束同样值得并入团队规范测试命名采用MethodName_Condition_ExpectedResult()模式例如PlaceOrder_WithInvalidStock_ThrowsException()单元测试聚焦领域逻辑与业务规则的隔离验证集成测试覆盖聚合边界、持久化与服务集成领域与应用层测试覆盖率目标不低于 85%。而 instructions/csharp.instructions.md 提醒测试代码中不要输出 Arrange/Act/Assert 注释并保持与既有测试文件一致的命名与大小写风格。空参数校验测试在依赖注入一节中已埋下伏笔——构造函数里的ArgumentNullException检查正是为这类测试准备的挂载点。配置与设置强类型配置类 数据注解技能要求配置层做到强类型配置类 数据注解使用校验特性Required、NotEmptyOrWhitespace通过IConfiguration绑定设置支持appsettings.json。典型实现public sealed class AiOptions { public const string SectionName AI; [Required] public string ModelName { get; set; } string.Empty; [Required, NotEmptyOrWhitespace] public string ApiKey { get; set; } string.Empty; }{ AI: { ModelName: gpt-5, ApiKey: *** } }builder.Services.ConfigureAiOptions(builder.Configuration.GetSection(AiOptions.SectionName));强类型配置把魔法字符串收敛为编译期可检查的属性数据注解则把校验前移到绑定期配合OptionsBuilder.ValidateDataAnnotations()可在启动阶段即失败fail-fast避免配置缺失在运行时才暴露。设计模式审查技能在改进重点中也点名配置数据注解、校验特性、敏感值的安全处理提示敏感配置不应硬编码进配置文件。Semantic Kernel 与 AI 集成技能要求 AI 集成遵循使用Microsoft.SemanticKernel正确的内核配置与服务注册处理 AI 模型设置ChatCompletion、Embedding 等使用结构化输出模式保证 AI 响应可靠。仓库中 skills/semantic-kernel/SKILL.md 是专门的配套技能其 .NET 工作流skills/semantic-kernel/references/dotnet.md要求内核操作使用异步模式、遵循官方插件与函数调用模式、实现显式错误处理与日志、优先使用 Azure AI Foundry 连接器、适当场景使用默认的DefaultAzureCredential认证。配置 AI 服务时结构化输出是保证响应可解析的关键——无论是要求 JSON schema 输出还是使用强类型结果绑定都能显著降低模型输出不稳定的风险。在 AI/ML 集成场景中还应同时执行技能性能与安全一节的要求见下文。错误处理与日志结构化日志与精确异常技能要求使用Microsoft.Extensions.Logging结构化日志作用域日志携带有意义的上下文抛出携带描述性消息的具体异常对预期失败场景使用 try-catch。结构化日志的落地形态Serilog 或其他提供者在 instructions/csharp.instructions.md 有展开包括日志级别选择、Application Insights 遥测、关联 ID 追踪等。作用域日志的典型用法using var scope _logger.BeginScope(new { OperationId operationId, UserId userId }); _logger.LogInformation(Processing order {OrderId}, orderId);try-catch 的正确姿势是只捕获预期的、可恢复的失败并配合 when 过滤与不同异常类型分级处理。这一点在 cookbook/copilot-sdk/dotnet/error-handling.md 中有完整的实战示例比如区分FileNotFoundExceptionCLI 未安装、HttpRequestException无法连接 CLI 服务与兜底的Exception以及用CancellationTokenSource实现 30 秒超时、用AbortAsync()中断长请求、在Console.CancelKeyPress中优雅关闭try { await client.StartAsync(); } catch (FileNotFoundException) { Console.WriteLine(Copilot CLI not found. Please install it first.); } catch (HttpRequestException ex) when (ex.Message.Contains(connection)) { Console.WriteLine(Could not connect to Copilot CLI server.); } catch (Exception ex) { Console.WriteLine($Unexpected error: {ex.Message}); }性能与安全C# 12、输入校验与参数化查询技能的性能与安全要求包括优先使用 C# 12 特性与 .NET 8 优化实现输入校验与净化sanitization数据库操作使用参数化查询AI/ML 操作遵循安全编码实践。instructions/csharp.instructions.md 进一步给出格式与语言级细则优先文件级命名空间与单行 using、代码块前换行、方法末尾 return 独立成行、多用模式匹配与 switch 表达式、入口点用is null/is not null检查空值。数据库访问层面该指令要求基于 Entity Framework Core 实现数据访问层说明 SQL Server/SQLite/In-Memory 等选项的取舍并演示仓储模式与高效查询模式——参数化查询或 EF Core 的 LINQ 参数化是防 SQL 注入的根本手段。AI/ML 安全编码则指敏感数据脱敏、提示注入防护、以及上文 AI 技能中提到的安全认证方式如DefaultAzureCredential而非硬编码密钥。代码质量SOLID 与可维护性最后一节要求遵循 SOLID 原则通过基类与工具类避免重复使用反映领域概念的命名保持方法聚焦内聚为资源实现正确的释放模式。instructions/dotnet-architecture-good-practices.instructions.md 是这节的完整论据来源它定义了 DDD 五大要素通用语言、限界上下文、聚合、领域事件、富领域模型与 SOLID 五原则的对应关系并给出强制性的实现前思考流程——任何实现前必须说明应用的 DDD/SOLID 模式、受影响的分层、聚合边界、领域事件等否则停止并请求澄清。资源释放模式在 Copilot SDK 指令中同样被强调客户端与会话始终用await using自动释放StopAsync()在 1.0 版本中清理出错会抛异常需包 try/catch必要时用ForceStopAsync()强制停止。结语将技能嵌入团队 .NET 工程基线dotnet-best-practices技能的价值在于把散落在 instructions/csharp.instructions.md、instructions/dotnet-architecture-good-practices.instructions.md、skills/dotnet-design-pattern-review/SKILL.md、skills/semantic-kernel/SKILL.md 与 cookbook/copilot-sdk/dotnet/README.md 等仓库资源中的零散规则收敛为一套可被 Copilot 在任意.cs选择区直接执行的一致性检查清单。团队落地时可将其与上述设计模式审查技能配合使用先由dotnet-best-practices驱动生成与整改再由dotnet-design-pattern-review做独立评审形成生成—校验—评审的闭环同时将命名空间约定、测试命名模式、资源文件拆分等硬性规则写入 .editorconfig 与 CI 校验即可把这份技能从会话内的建议升级为仓库级的工程基线。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考