使用 dotnet format 格式化代碼

Intro

dotnet-format 在之前的版本是一個獨立的命令行工具，在 .NET 6 里已經(jīng)成為了 SDK 的一部分，我們可以使用，使用 dotnet format 我們可以結合 editorconfig 保持代碼風格的一致，我們也可以將 dotnet format 作為一個 CI 服務來運行，自動 format 我們的代碼或驗證代碼是否符合我們的代碼風格

Editorconfig

EditorConfig 有助于為跨各種編輯器和 IDE 處理同一項目的多個開發(fā)人員維護一致的編碼風格

Editorconfig 是用來指定文件的格式的，在 .NET 里，微軟擴充了 editorconfig 的用法，我們可以把 C# 的一些編碼風格甚至一些錯誤的級別也加入其中，從而可以通過 editorconfig 來統(tǒng)一代碼的風格。

很多編輯器和 IDE 都支持 Editorconfig，包括我們常用 VS，Rider、VS Code/Sublime 等

Sample

C# 10 開始支持了 file-scoped namespace，我們可以使用 editorconfig 來配置使用 file-scoped 風格的命名空間聲明方式，在之前的文章中，我們曾經(jīng)介紹過，可以在 editorconfig 中配置 csharp_style_namespace_declarations=file_scoped:suggestion 來使得 VS 創(chuàng)建項目的時候默認使用 file-scoped 風格，這里的 suggestion 是一個提示級別，我們也可以將此級別提高成 info/warning 甚至 error，dotnet format 默認自動 format 級別為 warning 及以上級別的規(guī)則

所以我們可以將上面的級別改成 warning，然后在項目目錄下運行 dotnet format，然后我們項目中所有類型的命名空間風格就會從傳統(tǒng)的風格變成新的 file-scoped 風格，可以參考這個 commit https://github.com/WeihanLi/WeihanLi.Npoi/commit/201427b95f2bc23e97e2be595bc103301b7898e3

下面這個變更就是由 dotnet format 更改的

一個命令遷移項目中所有文件的命名空間風格為新的 file-scoped 風格，是不是很方便呢~~

當然不僅僅是命名空間風格，我們還可以在 editorconfig 中定義其他很多的代碼風格，甚至我們也可以定義一些第三方分析器的診斷級別，具體規(guī)則可以參考微軟的這個文檔：https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/code-style-rule-options?view=vs-2019

有一些代碼格式在 VS 中也是可以配置的，但是個人更加推薦使用 editorconfig 的方式，這樣別人要修改某個項目的時候，也不需要修改 VS 的配置，只需要遵循 editorconfig 的風格就可以了，配置即代碼，在任何地方都是一樣的，也不需要關注 IDE。

CI Service

我們可以把 dotnet format 做成一個 CI 服務來保證自己的代碼風格始終是一致的，我們可以有多個選擇

第一種方式，我們只做代碼格式的驗證，我們可以使用 dotnet format --verify-no-changes 來驗證格式是否有問題，如果格式有問題，exitcode 將不會是 0，而是 2，也就意味著會 CI 失敗

Github Actions CI 配置示例如下：

name:?dotnet-format

on:?[pull_request]

jobs:
??build:
????runs-on:?ubuntu-latest
????steps:
????-?uses:?actions/checkout@v1
????-?name:?Setup?.NET?6
??????uses:?actions/setup-dotnet@v1
??????with:
????????dotnet-version:?'6.0.x'
????-?name:?build
??????run:?dotnet?build
????-?name:?check?format
??????run:?dotnet?format?--verify-no-changes

第二種，我們可以直接提交一個 commit 來修復不正確的格式，運行 dotnet format 的時候會嘗試修復項目的代碼格式，修復之后我們把這些修復后的文件變成提交成一個 commit 然后推送到我們的代碼庫就可以了，Github Actions CI 示例如下：

name:?dotnet-format

on:
??push:
????branches:?[?dev?]

jobs:
??build:
????runs-on:?ubuntu-latest
????steps:
????-?uses:?actions/checkout@v1
????-?name:?Setup?.NET?6
??????uses:?actions/setup-dotnet@v1
??????with:
????????dotnet-version:?'6.0.x'
????????include-prerelease:?true
????-?name:?build
??????run:?dotnet?build
????-?name:?format
??????run:?dotnet?format
????-?name:?check?for?changes
??????run:?|
????????if?git?diff?--exit-code;?then
??????????echo?"has_changes=false"?>>?$GITHUB_ENV
????????else
??????????echo?"has_changes=true"?>>?$GITHUB_ENV
????????fi
????-?name:?Commit?and?Push
??????if:?${{?env.has_changes?==?'true'?}}
??????shell:?bash
??????run:?|
????????git?config?--local?user.name?"github-actions[bot]"
????????git?config?--local?user.email?"[email protected]"
????????git?add?-u
????????git?commit?-m?"Automated?dotnet-format?update?from?commit?${GITHUB_SHA}?on?${GITHUB_REF}"
????????git?log?-1
????????remote_repo="https://${GITHUB_ACTOR}:${{secrets.GITHUB_TOKEN}}@github.com/${GITHUB_REPOSITORY}.git"
????????git?push?"${remote_repo}"?HEAD:${GITHUB_REF}

這里的 CI 直接運行了 dotnet format 命令，然后會通過 git 命令來檢查是否有文件變更，如果有文件變更就會生成一個 commit 并推送到代碼庫

前面的變更就是 CI 自動提交的 commit? 的一部分，當我提交代碼時就會自動跑?dotnet format 如果有變更就會提交到倉庫一個新的格式化的提交，下面兩個commit 就是?CI 自動提交的一個示例

Github actions 可以參考

https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/dotnet-format.yml
https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/dotnet-format-pr-validation.yml

除了上面的這些基本用法，dotnet format 還有更多的選項，可以通過 --severity 指定嚴重等級，默認是 warning，也可以手動指定為 info 或者 error，另外可以只 format 空格 dotnet format whitespace、代碼風格 dotnet format style 或者第三方的分析器 dotnet format analyzers

更多可以參考 dotnet format 的介紹：https://github.com/dotnet/format/blob/main/README.md

總體上使用下來，感覺還是挺不錯的，但是目前有遇到兩個問題，一個是在使用框架條件編譯的時候

也就是代碼里有 #if NET6_0 類似代碼時格式可能會有問題，出現(xiàn)一段被注釋的代碼，這里有一個示例，但是手動改了以后似乎沒有這個問題了，只遇到過一次，而且 review 了更改的代碼也沒什么問題

代碼太多了截圖了一部分，感興趣的可以直接看對應 commit 的文件：https://github.com/WeihanLi/WeihanLi.Common/blob/3b080c08c87fa24d99a938a8b3173fb7ec3e92de/src/WeihanLi.Common/Helpers/SecurityHelper.cs

另外一個問題是項目中有 source generator 的時候會 format 失敗，提了一個 issue，暫時還沒有解決方案，感興趣的可以參考：https://github.com/dotnet/format/issues/1461

References

https://github.com/dotnet/format
https://github.com/dotnet/format/issues/1268
https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/code-style-rule-options?view=vs-2019
https://github.com/dotnet/format/blob/main/docs/Supported-.editorconfig-options.md
https://github.com/WeihanLi/WeihanLi.Npoi/commit/201427b95f2bc23e97e2be595bc103301b7898e3
https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/dotnet-format.yml
https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/dotnet-format-pr-validation.yml
https://github.com/dotnet/format/issues/1461

使用 dotnet format 格式化代碼

使用 dotnet format 格式化代碼

Intro

Editorconfig

Sample

CI Service

More

References