.NET编码规范06-CSharpier与dotnet-format
.NET编码规范第 6 篇CSharpier 与dotnet format—— 让代码格式化自动化前言分析器能告诉你哪里不对但手动修复 100 条警告是低效的。自动格式化工具就是来解放你的——一条命令所有代码瞬间统一。.NET 生态有两款主流自动格式化工具微软官方的dotnet format和社区派的CSharpier。本文深入对比两者的优劣帮你做出正确的选择。一、dotnet format微软官方的格式化武器1.1 是什么dotnet format是 .NET SDK 自带的工具.NET 6它基于.editorconfig和 Roslyn 分析器的规则自动修正代码格式。1.2 基本用法# 格式化整个解决方案dotnetformat# 格式化特定项目dotnetformat./src/MyProject/MyProject.csproj# 仅分析不实际修改生成报告dotnetformat--verify-no-changes# 包含代码分析器修复dotnetformatstyle--severityinfo# 格式化指定文件dotnetformat--include./src/**/*.cs# 排除特定文件dotnetformat--exclude./**/Migrations/**1.3 它能做什么功能说明空白规范缩进、空格、行尾空白、空行命名修正根据.editorconfig中的命名规则自动重命名分析器修复自动修复部分 Roslyn 分析器的suggestion级别问题using 排序按配置排序 using 指令移除未使用的文件编码/换行符按配置统一1.4dotnet format的局限国际化配置受.editorconfig规则限制有些格式化效果取决于配置的完整性不可配置的部分某些格式决策如switch表达式换行位置不由你决定分析器自动修复有限只能修复提供了Code Fix的规则二、CSharpier基于 Prettier 哲学的 Opinionated Formatter2.1 核心理念CSharpier 的思想来源是前端世界的 Prettier ——“Opinionated Code Formatter”。它的设计哲学是“Stop debating code style. Just format it.”不给太多配置选项一个风格走天下。这听起来霸道但恰恰消灭了团队中关于格式的无尽争论。2.2 安装命令行安装# 作为全局工具安装dotnet toolinstall-gcsharpier# 作为项目本地工具推荐dotnet new tool-manifest dotnet toolinstallcsharpier可以在扩展中搜索“csharpier”进行安装2.3 基本用法# 格式化整个解决方案dotnet csharpier.# 格式化特定文件/目录dotnet csharpier ./src/ dotnet csharpier Program.cs# 仅检查不修改CI 场景dotnet csharpier--check.# 指定多个目录dotnet csharpier ./src/ ./tests/简单配置可以在选项中csharpier页进行设置2.4 配置文件.csharpierrc在项目根目录创建.csharpierrc.json或.csharpierrc.yaml{printWidth:120,useTabs:false,indentSize:4,endOfLine:auto,overrides:[{files:*.xaml,options:{parser:xml,indentSize:2}},{files:*.cshtml,options:{indentSize:2}}]}配置项速查选项默认值说明printWidth100期望最大行宽非硬限制useTabsfalse是否使用制表符缩进indentSizeC#: 4, XML: 2每个缩进级别的空格数endOfLineauto换行符风格auto/lf/crlfoverrides[]针对特定文件类型的覆盖规则2.5 与.editorconfig的关系CSharpier 会读取.editorconfig的部分设置作为回退CSharpier 选项对应的.editorconfig选项useTabsindent_styleindentSizeindent_sizeprintWidthmax_line_lengthendOfLineend_of_line优先级.csharpierrc.editorconfig。2.6 忽略文件创建.csharpierignore文件# 忽略生成的文件 **/Migrations/ **/obj/ **/bin/ # 忽略特定文件 GeneratedCode.cs三、dotnet formatvs CSharpier —— 终极对比维度dotnet formatCSharpier出品方微软官方社区安装.NET 6 SDK 自带需安装 dotnet tool可配置性高通过 .editorconfig低Opinionated少配置格式化范围空白、命名、分析器修复空白、换行、整体排版命名规范修正✅ 支持❌ 不支持分析器联动✅ 自动修复❌ 不涉及XAML 支持有限✅ 支持CSHTML/Razor有限✅ 通过 overrides 支持类型服从规则的 Formatter主张风格的 Formatter适用场景需要精细控制的团队不想争论格式的团队四、选型建议推荐方案两者结合使用统一排版命名分析器修复CSharpier格式化后的代码dotnet format最终代码用 CSharpier 做排版格式化—— 换行、缩进、空格一键统一用dotnet format做分析与修复—— 命名修正、代码分析器自动修复配置文件共存示例仓库根目录/ ├── .editorconfig ← dotnet format 读取 ├── .csharpierrc.json ← CSharpier 读取 └── .csharpierignore ← CSharpier 忽略列表工作流整合# 提交前完整格式化流程dotnet csharpier.# 第一步排版格式化dotnetformatstyle--severityinfo# 第二步风格修复dotnet build# 第三步验证分析器规则五、CI/CD 中集成格式化检查GitHub Actions 示例name:Format Checkon:[pull_request]jobs:format:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Setup .NETuses:actions/setup-dotnetv4with:dotnet-version:9.0.x-name:Restore toolsrun:dotnet tool restore-name:Check CSharpier formattingrun:dotnet csharpier--check .-name:Check dotnet formatrun:dotnet format style--verify-no-changes--severity info-name:Build with analysisrun:dotnet build--configuration Release-warnaserrorGit Pre-commit HookHusky.NET 方式// .husky/task-runner.json{tasks:[{name:format,command:dotnet,args:[csharpier,.]},{name:analyze,command:dotnet,args:[format,style,--severity,info,--include,--verbosity,detailed]}]}六、常见问题Q1: CSharpier 把代码改得我不喜欢怎么办这就是 Opinionated Formatter 的设计理念——放弃个人偏好接受社区一致风格。如果你真的无法接受某些格式可以考虑用.csharpierignore排除特定文件然后用dotnet format单独处理。Q2: 能不能只格式化变更的文件# 利用 Git 获取变更文件列表gitdiff--name-only HEAD|grep\.cs$|xargsdotnet csharpier
)
