GitHub Copilot 定制 C# 开发指南从编码规范到 ASP.NET Core 全栈实践【免费下载链接】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 仓库中的 csharp.instructions.md 定制指令系统讲解如何让 GitHub Copilot 生成符合现代 C# 最佳实践的代码。该指令文件以 frontmatter 的applyTo: **/*.cs声明作用范围即只要 Copilot 处理 C# 源码文件就会自动套用这些规则。读完本文你将掌握 C# 语言版本策略、命名与格式化约定、可空引用类型、EF Core 数据访问、JWT/OIDC 认证授权、RFC 9457 错误处理、API 版本化与 OpenAPI 文档、Serilog 日志、测试、性能优化以及基于 .NET 内置容器发布的完整 DevOps 流程并能在自己的仓库中直接复刻这套指令体系。在仓库中安装与使用这份 C# 指令awesome-copilot 是一个社区贡献的 instructions、agents、skills 与配置集合csharp.instructions.md正是其中面向 C# 开发的团队级定制指令。根据 README.instructions.md 的说明这类指令文件的安装与生效方式有三种全局指令将文件内容复制到工作区的.github/copilot-instructions.mdCopilot 会在整个工作区范围内始终遵循这些规则任务级指令在工作区的.github/instructions/目录下创建任务专属的*.instructions.md文件例如.github/instructions/my-csharp-rules.instructions.mdCopilot 会在相关任务上下文中自动应用VS Code 一键安装通过 VS Code 或 VS Code Insiders 的安装按钮vscode:chat-instructions/install协议直接安装到本地指令集合。值得强调的是这份 C# 指令与仓库中配套的 CSharpExpert.agent.mdC# Expert Agent以及 aspnet-rest-apis.instructions.mdASP.NET REST API 指令是互补的指令负责约束生成的代码长什么样Agent 负责定义专家角色的行为方式而本文聚焦前者。C# 语言版本策略始终使用最新特性指令文件的开篇明确了一条硬性规则始终使用最新版本的 C#当前为 C# 14 特性。这并非盲目追新而是有现实依据——C# 14 随 .NET 10 一起发布。CSharpExpert Agent 中给出了与之匹配的现代特性清单可作为最新特性的具体落点扩展成员extension members为现有类型扩展成员而无需继承field关键字访问器在属性中直接引用后台字段简化属性定义隐式SpanT转换提升高性能场景下的内存安全与分配效率?.空合并赋值简化若为 null 则赋值的惯用写法nameof配合未绑定泛型在泛型上下文中更安全地引用成员名Lambda 参数修饰符无需显式类型ref、in、out修饰符可直接用于无类型 lambda 参数分部构造函数与分部事件进一步细化自动生成代码与手写代码的协作边界用户自定义复合赋值允许为用户定义类型提供复合赋值运算。不过 Agent 也给出了使用前提不要设置高于目标框架TFM默认值的 C# 版本例如面向 .NET Framework 的项目就不能直接套用 C# 14。在动手前先确认global.json指定的 SDK 版本、项目 TFM 以及LangVersion配置是避免生成了编译不过的代码的关键习惯。通用编码指南高置信度、可维护性与边界处理指令的 General Instructions 部分提出了三条贯穿始终的代码质量底线只做高置信度的建议在审查代码变更时不提供模棱两可或投机性的修改意见宁可少建议也不误导以可维护性为先代码要写好为什么这样做的设计决策注释而非解释做了什么——这正是 CSharpExpert Agent 中 Comments explain why, not what 原则的呼应处理边界情况与清晰的异常处理不吞异常、不静默失败对每个函数编写清晰简洁的注释外部依赖要说明用途对库或第三方依赖在注释中交代其使用场景与目的。命名约定与代码格式化命名约定指令对命名做出了明确、可机械检查的约束对象规范示例组件名、方法名、公共成员PascalCaseCreateUser、UserService私有字段、局部变量camelCaseuserService、userCount接口名前缀IIUserService格式化规则遵循.editorconfig项目内的代码格式风格由.editorconfig统一约束Copilot 生成代码前应读取该文件仓库中的 editorconfig skill 提供了更细的编辑器配置指引文件级命名空间优先使用 file-scoped namespace 声明namespace MyApp;并偏好单行 using 指令using System.Linq;而非块状写法大括号另起一行if、for、while、foreach、using、try等代码块的开括号前必须换行Allman 风格return 语句独立成行方法的最终 return 必须独占一行保证可读性与断点调试体验优先模式匹配与 switch 表达式能用is模式匹配或switch表达式表达的逻辑就不要写冗长的if/else链——仓库中 copilot-sdk-csharp.instructions.md 的事件处理示例是极佳示范session.On(evt { switch (evt) { case UserMessageEvent userMsg: // 处理用户消息 break; case AssistantMessageEvent assistantMsg: Console.WriteLine(assistantMsg.Data.Content); break; case ToolExecutionStartEvent toolStart: break; case SessionIdleEvent idle: done.SetResult(); break; case SessionErrorEvent error: Console.WriteLine($Error: {error.Data.Message}); break; } });使用nameof而非字符串字面量凡涉及成员名引用的场景如抛异常、绑定配置键、反射一律用nameof(SomeMember)这样重命名时编译器会同步修正避免字符串失效公共 API 必须带 XML 文档注释并尽可能包含example与code块让 IDE 悬浮提示与生成的 API 文档对消费者友好。项目设置与结构指令要求 Copilot 在新建项目时扮演讲解者而非单纯的生成器引导使用合适的 .NET 项目模板例如dotnet new webapi、dotnet new console、dotnet new xunit等解释每个模板生成的意图解释每个生成文件与文件夹的用途帮助用户建立对项目结构的整体认知Program.cs、appsettings.json、Controllers/、Properties/launchSettings.json等演示 feature folders 或领域驱动设计DDD组织方式按业务功能而非技术类型组织代码展示关注点分离模型Models、服务Services、数据访问层Data Access各司其职讲解Program.cs与 ASP.NET Core 10 的配置系统包括环境专属配置appsettings.Development.json、appsettings.Production.json与IConfiguration的加载优先级。以 Minimal API 为例一个关注点分离的典型结构是MyApi/ ├── Program.cs # 应用入口与请求管道组装 ├── appsettings.json # 基础配置 ├── appsettings.Development.json ├── Models/ # DTO 与实体 ├── Services/ # 业务逻辑 └── Data/ # EF Core DbContext 与仓储可空引用类型把 null 检查交给类型系统指令在 Nullable Reference Types 一节给出了三条极易执行又极易被违反的规则变量声明为非可空并在入口点检查 null方法边界公共 API 参数、外部数据反序列化结果是 null 检查的唯一合理位置始终使用is null/is not null禁止 null/! null这是模式匹配风格的延伸同时规避了运算符重载的坑信任 C# 可空注解当类型系统明确声明某值不可为 null 时例如string而非string?不要再画蛇添足地加 null 检查——冗余检查既降低可读性也会误导后续维护者。CSharpExpert Agent 对入口点检查给出了更具体的手段ArgumentNullException.ThrowIfNull(x)与string.IsNullOrWhiteSpace(x)并建议尽早防御、避免滥用!空值断言运算符。数据访问模式Entity Framework Core 实战指令要求 Copilot 引导实现基于 EF Core 的数据访问层覆盖以下核心议题数据库选型开发与生产环境采用不同 Provider——SQL Server生产、SQLite本地开发、In-Memory单元测试并解释各自的适用场景与限制Repository 模式演示何时引入仓储抽象真正有益如需要统一缓存、审计日志、或为了测试替换数据源同时避免为了抽象而抽象——CSharpExpert Agent 明确告诫不要为不必要的外部依赖或测试以外的场景添加接口/抽象层数据库迁移与数据种子dotnet ef migrations add Name生成迁移、Database.Migrate()应用迁移、HasData()或EnsureSeedData()完成种子数据填充高效查询模式避免 N1 查询用Include/ThenInclude显式加载导航属性、避免在内存中过滤大数据集用Where下推 SQL、对只读场景考虑AsNoTracking()。认证与授权在安全方面指令要求 Copilot 覆盖完整链路JWT Bearer 令牌认证配置AddAuthentication().AddJwtBearer()校验Issuer、Audience、SigningKeyOAuth 2.0 与 OpenID Connect 概念解释授权码流、id_token与access_token的区别以及它们与 ASP.NET Core 中间件的关系角色与策略授权[Authorize(Roles Admin)]之外推荐基于 Policy 的声明式授权RequireClaim、RequireAssertion便于集中管理复杂规则Microsoft Entra ID 集成AddMicrosoftIdentityWebApi()与AzureAd配置节将企业身份体系接入 APIController 与 Minimal API 安全策略一致Minimal API 中通过builder.RequireAuthorization()、app.MapGet(...).RequireAuthorization(PolicyName)达到与[Authorize]属性同等的效果。验证与错误处理从 DataAnnotations 到 RFC 9457模型验证Data Annotations[Required]、[StringLength]、[Range]等特性声明式验证FluentValidation对复杂、跨属性规则更友好可通过AddValidatorsFromAssembly自动注册验证管道[ApiController]特性会启用自动 400 响应Minimal API 中可用IEndpointFilter或手动调用Validate实现同等校验自定义验证响应通过InvalidModelStateResponseFactory统一改写 400 响应的形状。全局异常处理与 Problem Details全局异常中间件注册自定义中间件或UseExceptionHandler集中捕获未处理异常避免在每个 Action 里重复 try/catch一致的错误响应所有错误返回同一 JSON 结构客户端只需解析一种格式RFC 9457 Problem Details使用ProblemDetailsMicrosoft.AspNetCore.Mvc标准化错误负载——包含type、title、status、detail、instance字段这是当前 HTTP API 错误格式的官方标准取代了早期自定义错误体。在异常类型选择上CSharpExpert Agent 的补充同样重要选择精确的异常类型ArgumentException、InvalidOperationException不抛也不捕获基类Exception绝不静默吞错——要么记录日志后重新抛出要么让其自然冒泡。API 版本化与文档版本化策略URL 路径版本/api/v1/...、查询字符串版本、Header 版本以及Microsoft.AspNetCore.Mvc.Versioning的配置方式Swagger/OpenAPIAddEndpointsApiExplorer()AddSwaggerGen()生成文档Minimal API 同样支持文档内容为端点、参数、响应与认证方式补充说明——XML 文档注释指令格式化章节要求的example/code会直接流入 OpenAPI 描述实现注释即文档Controller 与 Minimal API 的版本化一致性控制器用[ApiVersion(1.0)]Minimal API 用MapToApiVersion()两者共享同一版本化配置。日志与监控结构化日志默认ILogger即可满足追求更丰富语义时引入 Serilog配置WriteTo.Console()、WriteTo.File()、Enrich.With...等日志级别语义Trace/Debug排障、Information业务事件、Warning可恢复异常、Error需告警的异常、Critical灾难性故障按场景选用而非一律LogErrorApplication Insights 集成AddApplicationInsightsTelemetry()接入遥测采集自定义遥测与关联 ID在管道中注入ActivityOpenTelemetry或用中间件生成/透传X-Correlation-ID实现跨服务的请求追踪监控 API 性能、错误与用量结合 Application Insights 的请求依赖、异常、指标三类遥测观察 P95 延迟、错误率与端点热度。测试为关键路径保驾护航指令的 Testing 章节要求关键路径必有测试核心业务逻辑、认证授权、数据访问都应有测试覆盖引导创建单元测试优先使用解决方案内已存在的测试框架xUnit/NUnit/MSTest保持风格一致禁止输出 Arrange / Act / Assert 注释三阶段结构靠空行与命名体现不靠注释噪音沿用邻近文件的命名风格测试方法命名参考现有代码习惯如WhenCatMeowsThenCatDoorOpens这样的行为式命名集成测试针对 API 端点用WebApplicationFactoryProgram启动真实管道进行测试Mock 依赖只 mock 外部依赖绝不 mock 被测方案内部的实现代码CSharpExpert Agent 的明确规则测试认证授权逻辑构造带/不带声明的令牌验证[Authorize]行为TDD 原则先写失败测试red再实现让其通过green最后重构refactor——仓库中 tdd-red.agent.md、tdd-green.agent.md、tdd-refactor.agent.md 三个 Agent 分别承载了这一流程的不同阶段。CSharpExpert Agent 还补充了测试工程化细节独立的[ProjectName].Tests工程、按类镜像命名CatDoor→CatDoorTests、单行为单测试、避免多断言、用参数化测试覆盖多种输入、测试可并行任意顺序运行、避免磁盘 I/O以及dotnet-coverage收集覆盖率dotnet tool install -g dotnet-coverage dotnet-coverage collect -f cobertura -o coverage.cobertura.xml dotnet test性能优化缓存策略内存缓存IMemoryCache、分布式缓存Redis、响应缓存ResponseCachingMiddleware按数据易变性与一致性要求选型异步编程模式async/await 端到端贯穿杜绝 sync-over-async.Result/.Wait()阻塞调用。CSharpExpert Agent 给出完整纪律异步方法以Async后缀命名、始终 await、CancellationToken端到端传递、超时用链接的CancellationTokenSourceCancelAfter、库代码用ConfigureAwait(false)、大数据流用ReadAsStreamAsync而非ReadAsStringAsync分页、过滤、排序大数据集端点提供page/pageSize/filter/sort参数避免全量返回压缩AddResponseCompression()启用 Gzip/Brotli按需对响应启用压缩基准测量用 BenchmarkDotNet 对热路径做基准测试遵循先简单实现再依据测量优化的原则。部署与 DevOps.NET 内置容器发布指令明确要求优先使用 .NET 的内置容器支持而非常规手写 Dockerfiledotnet publish --os linux --arch x64 -p:PublishProfileDefaultContainer该命令直接产出 OCI 兼容镜像无需 DockerfileSDK 容器会自动选择合适的运行时镜像、设置入口点并注入健康检查支持。若仍需手写 Dockerfile如需要多阶段构建、定制基础镜像、注入非托管依赖则使用经典的多阶段模式sdk镜像编译 →aspnet/runtime镜像运行。CI/CD 与托管CI/CD 管道GitHub Actions 中执行dotnet restore→dotnet build→dotnet test→dotnet publish仓库中的 github-actions-ci-cd-best-practices.instructions.md 提供了管道加固的完整指引托管目标Azure App ServicePaaS 快速托管、Azure Container Apps容器原生、支持自动扩缩、或其他容器平台健康检查与就绪探针AddHealthChecks()MapHealthChecks()暴露/health端点配合容器平台的 liveness/readiness probeAzure Container Apps 的探针配置可直接指向该端点环境专属配置通过ASPNETCORE_ENVIRONMENT与各环境的appsettings.{Environment}.json管理不同部署阶段的差异化配置敏感信息一律走环境变量或 Key Vault绝不硬编码。从指令到代码仓库中的 C# 实践样本上述规则并非停留在纸面——仓库的 cookbook 中提供了可运行、可复制的 C# 样本可用来对照验证指令的实际落地效果。以 error-handling.cs 为例它同时体现了本文的多条规则// The GitHub.Copilot.SDK package exposes the GitHub.Copilot namespace. using GitHub.Copilot; var client new CopilotClient(); try { await client.StartAsync(); var session await client.CreateSessionAsync(new SessionConfig { Model gpt-5, OnPermissionRequest PermissionHandler.ApproveAll }); var done new TaskCompletionSourcestring(); session.On(evt { if (evt is AssistantMessageEvent msg) { done.SetResult(msg.Data.Content); } }); await session.SendAsync(new MessageOptions { Prompt Hello! }); var response await done.Task; Console.WriteLine(response); await session.DisposeAsync(); } catch (Exception ex) { Console.WriteLine($Error: {ex.Message}); } finally { await client.StopAsync(); }对照清单逐条验证// The GitHub.Copilot.SDK package...是对库/依赖说明用途的注释evt is AssistantMessageEvent msg是模式匹配TaskCompletionSource是等待异步事件的标准手法await using/DisposeAsync/finally { await client.StopAsync(); }是清晰的资源清理与异常处理。同目录下的 multiple-sessions.cs、persisting-sessions.cs 等样本可继续用于学习而配套的 .NET SDK 指令 copilot-sdk-csharp.instructions.md 则给出了完整的配置参数CopilotClientOptions的CliPath、Port、UseStdio、AutoRestart等与最佳实践清单。结语把这份指南变成你自己的 Copilot 约束csharp.instructions.md的价值不在于条文本身而在于它提供了一套可落地的行为约束模板语言版本、命名、格式化、类型安全、数据访问、安全、错误处理、文档、日志、测试、性能、部署十二个维度覆盖了现代 C# 应用从诞生到上线的完整生命周期。你可以原样安装它也可以按团队实际裁剪——例如将applyTo扩展为**/*.cs, **/*.csproj以覆盖项目文件或与 aspnet-rest-apis.instructions.md聚焦 REST API 设计、csharp-mcp-server.instructions.md聚焦 MCP Server 开发组合使用构建分层定制的 C# 开发底座。安装后每一次 Copilot 建议、每一段生成的代码都会自动带上这些经过验证的工程约束。【免费下载链接】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），仅供参考