dotnet format と Linting

このドキュメントでは、.NET プロジェクトにおけるコード品質を保つためのツールである dotnet format と、それに関連する Linting（静的解析）の概念について解説します。

dotnet format とは

dotnet format は、.NET SDK に含まれるコードフォーマッターです。.editorconfig ファイルで定義されたルールに基づいて、コードのスタイルを自動的に修正します。

主な機能

コードスタイルの適用: インデント、改行、スペースなどのスタイルを統一します。
アナライザーの修正: Roslyn アナライザーによって検出された警告やエラーの一部を自動修正します。
インポートの整理: 不要な using ディレクティブの削除や並べ替えを行います。

基本的な使い方

インストール

.NET 6 以降の SDK には標準で含まれています。それ以前のバージョンの場合は、以下のコマンドでグローバルツールとしてインストールできます。

dotnet tool install -g dotnet-format

コマンド

プロジェクトのルートディレクトリで以下のコマンドを実行します。

# ソリューションまたはプロジェクト内のすべてのファイルをフォーマット
dotnet format

# 特定のプロジェクトファイルを指定してフォーマット
dotnet format ./src/MyProject.csproj

# スタイルの問題を確認するが、修正は行わない（CIなどで使用）
dotnet format --verify-no-changes

設定: .editorconfig

dotnet format の動作は、ソリューションのルートなどに配置された .editorconfig ファイルによって制御されます。

.editorconfig の例

# 最上位の EditorConfig ファイルであることを示す
root = true

# すべてのファイルに適用
[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# C# ファイル固有の設定
[*.cs]
# インデント設定
csharp_indent_labels = one_less_than_current

# using の整理
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

# コードスタイル（var vs 明示的な型）
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion

Linting と Roslyn Analyzers

Linting（リンティング）とは、ソースコードを静的に解析し、バグの可能性やスタイルの違反、怪しい構造などを検出するプロセスです。.NET では Roslyn Analyzers がこの役割を担います。

Roslyn Analyzers の仕組み

Roslyn（.NET Compiler Platform）は、コンパイル時にコードを解析する API を提供しています。これを利用して、リアルタイムにコードの問題を検出し、Visual Studio や VS Code 上で波線として表示したり、ビルド時の警告として出力したりします。

dotnet format は、これらのアナライザーが提供する「コード修正（Code Fix）」機能をコマンドラインから一括実行するツールと捉えることもできます。

一般的なアナライザーパッケージ

Microsoft.CodeAnalysis.NetAnalyzers: .NET SDK に標準で含まれている推奨アナライザー集。
StyleCop.Analyzers: コードスタイルに特化した厳格なルールセット。
SonarAnalyzer.CSharp: SonarQube のルールセットを含むアナライザー。

ローカル開発でのベストプラクティス (Shift Left)

CI でのエラー検出は最終防衛ラインですが、フィードバックループが遅くなりがちです。開発者がコードを書いている最中やコミットする前に問題を修正する「Shift Left」のアプローチが推奨されます。

1. IDE の設定 (Format on Save)

最も手軽で効果的な方法は、ファイルを保存した瞬間にフォーマットを適用することです。

VS Code: .vscode/settings.json に以下を追加します。
```
{
  "editor.formatOnSave": true
}
```
また、C# Dev Kit 拡張機能を入れることで、Roslyn アナライザーの警告をリアルタイムにエディタ上で確認できます。
Visual Studio: [ツール] > [オプション] > [テキストエディター] > [コードクリーンアップ] で「保存時にコードクリーンアップを実行する」にチェックを入れます。プロファイルを設定して、適用するルール（using の整理など）を選択できます。

2. Git Hooks の活用 (Husky)

コミットする前に自動的に dotnet format を実行し、修正されたファイルのみをコミットするように強制することで、フォーマットされていないコードがリポジトリに混入するのを防ぎます。

Node.js 環境がある場合、Husky と lint-staged を組み合わせるのが一般的です。

セットアップ例:

パッケージのインストール

npm install --save-dev husky lint-staged
npx husky install

package.json の設定

{
  "lint-staged": {
    "*.cs": "dotnet format --include"
  }
}

pre-commit フックの作成

npx husky add .husky/pre-commit "npx lint-staged"

これにより、git commit 時に変更された .cs ファイルに対してのみ dotnet format が実行されます。

3. タスクランナーの利用

VS Code のタスク機能などを利用して、手動でも簡単に実行できるようにしておくと便利です。

.vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "dotnet format",
      "command": "dotnet",
      "type": "process",
      "args": ["format"],
      "problemMatcher": "$msCompile"
    }
  ]
}

CI/CD への統合

GitHub Actions などの CI/CD パイプラインで dotnet format を使用することで、コードベースの品質を保つことができます。

GitHub Actions の例

プルリクエスト時にフォーマットが正しいかチェックするワークフローの例です。

name: Lint Code

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0.x'
          
      - name: Verify formatting
        run: dotnet format --verify-no-changes --verbosity diagnostic

--verify-no-changes オプションを使用すると、フォーマットが必要なファイルがある場合にコマンドが失敗（終了コードが非ゼロ）するため、CI を失敗させることができます。

VS Code での利用

VS Code では、C# 拡張機能（C# Dev Kit）が .editorconfig を認識し、エディタ上でリアルタイムにスタイル違反を警告してくれます。

保存時にフォーマット: settings.json で "editor.formatOnSave": true を設定すると、ファイル保存時に自動的にフォーマットが適用されます。
クイックフィックス: 波線が出ている箇所で Ctrl + . を押すと、修正案が表示され、適用できます。

まとめ

dotnet format はコードスタイルを統一するための強力な CLI ツールです。
.editorconfig を使用してチーム全体のルールを共有・管理しましょう。
Roslyn Analyzers と組み合わせることで、スタイルだけでなく潜在的なバグも防ぐことができます。
CI/CD に組み込むことで、継続的にコード品質を維持できます。

dotnet format とは​

主な機能​

基本的な使い方​

インストール​

コマンド​

設定: .editorconfig​

.editorconfig の例​

Linting と Roslyn Analyzers​

Roslyn Analyzers の仕組み​

一般的なアナライザーパッケージ​

ローカル開発でのベストプラクティス (Shift Left)​

1. IDE の設定 (Format on Save)​

2. Git Hooks の活用 (Husky)​

3. タスクランナーの利用​

CI/CD への統合​

GitHub Actions の例​

VS Code での利用​

まとめ​