2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

設計書だけでは守れないので、C#のアーキテクチャルールをコンパイル時にチェックするAnalyzerを作った

2
Last updated at Posted at 2026-09-10

C#でレイヤードアーキテクチャやClean Architectureを採用していると、

「Domain層からApplication層へ依存してはいけない」

「Domain層ではConsoleやFileなどのI/Oを直接使ってはいけない」

といったルールを決めることがあります。

しかし、これらのルールをREADMEやADR、設計書に書いているだけでは、実際のコードがそのルールを守っているとは限りません。

レビューで見落としたり、「今回だけ」のつもりで依存関係が追加されたりすると、少しずつ設計と実装がずれていきます。

今回は、こうしたアーキテクチャルールをRoslyn Analyzerでコンパイル時に検証するために作成した ArchitectureAnalyzer を紹介します。

この記事を読むとできるようになること

  • C#プロジェクトのレイヤー間依存をコンパイル時にチェックできる
  • 特定のレイヤーから利用してはいけないAPIを定義できる
  • アーキテクチャルールをJSONファイルとして管理できる
  • 通常の dotnet build やCIでアーキテクチャ違反を検出できる

ArchitectureAnalyzerとは?

ArchitectureAnalyzerは、C#プロジェクトのアーキテクチャルールをコンパイル時に検証するRoslyn Analyzerです。

ルールそのものはAnalyzerのコードには記述せず、プロジェクト側に置いた architecture.contract.json に定義します。

例えば、

  • Domain
  • Application

という2つのレイヤーを定義し、

「DomainからApplicationへの依存は禁止」

というルールを設定できます。

ArchitectureAnalyzerは、このJSONを読み取り、実際のC#コードが定義されたルールに違反していないかをコンパイル時に検証します。

Architecture Contractを作成する

まず、プロジェクトに architecture.contract.json を作成します。

例えば、以下のような設定です。

{
  "layers": [
    {
      "name": "Domain",
      "namespaceRoots": [
        "MyApp.Domain"
      ]
    },
    {
      "name": "Application",
      "namespaceRoots": [
        "MyApp.Application"
      ]
    }
  ],
  "forbiddenDependencies": [
    {
      "from": "Domain",
      "to": "Application",
      "reason": "Domain must not depend on the outer Application layer."
    }
  ]
}

この設定では、MyApp.Domain 以下をDomainレイヤー、MyApp.Application 以下をApplicationレイヤーとして扱います。

そして、DomainからApplicationへの依存を禁止しています。

namespaceRoots はprefixとして扱われるため、例えば MyApp.Domain.Orders や MyApp.Domain.Products もDomainレイヤーに分類されます。

実際に違反してみる

例えばApplication側に次の型があるとします。

namespace MyApp.Application;

public class OrderService
{
}

これをDomain側から直接参照します。

using MyApp.Application;

namespace MyApp.Domain;

public class Order
{
    private readonly OrderService _service = new();
}

この状態でビルドすると、ArchitectureAnalyzerが依存方向の違反を検出します。

error AARC002: 'MyApp.Domain.Order' (Domain) must not depend on 'MyApp.Application.OrderService' (Application): Domain must not depend on the outer Application layer.

つまり、人間がコードレビューで見つける前に、コンパイラがアーキテクチャ違反を止めてくれます。

禁止APIも定義できる

レイヤー間の依存だけでなく、特定のAPIそのものを禁止することもできます。

例えばDomain層から System.Console を使わせたくない場合は、Architecture Contractに次のようなルールを追加します。

{
  "forbiddenApis": [
    {
      "layer": "Domain",
      "type": "System.Console",
      "reason": "Console I/O must be abstracted behind an Infrastructure adapter."
    }
  ]
}

Domain層で次のようなコードを書くと、Analyzerが検出します。

namespace MyApp.Domain;

public class Order
{
    public void Print()
    {
        Console.WriteLine("Order");
    }
}

これにより、Domain層をI/Oから分離したい場合などに、ルールをレビューだけに頼らず機械的に維持できます。

なぜルールをJSONにしたのか

ArchitectureAnalyzerでは、

  • Domain
  • Application
  • Infrastructure

といったレイヤー名をAnalyzer側にハードコードしていません。

プロジェクトごとにアーキテクチャが異なるためです。

Analyzer側に「DomainはApplicationへ依存してはいけない」と直接実装してしまうと、そのAnalyzerは特定のプロジェクト専用になってしまいます。

そこでArchitectureAnalyzerでは、

Analyzerはルールを判定する仕組みだけを持ち、実際のアーキテクチャルールは利用するプロジェクト側で定義する

という構成にしています。

ルールを変更したい場合もAnalyzerを修正する必要はなく、architecture.contract.json を変更します。

アーキテクチャルールそのものを、コードと同じようにリポジトリでレビュー・履歴管理できるようにすることを狙っています。

Roslyn Analyzerにした理由

同じようなチェックは、専用のCLIツールやCIスクリプトでも実装できます。

しかしArchitectureAnalyzerではRoslyn Analyzerとして実装しました。

理由は、普段のC#開発の流れにそのまま組み込めるためです。

  • IDE上で違反を確認できる
  • dotnet build だけでチェックできる
  • CIでも通常のビルドを実行するだけでよい
  • 開発者が別の検証コマンドを覚える必要がない
  • pre-commit hookのようにローカル設定へ依存しない

設計チェックのためだけに別の仕組みを用意するのではなく、通常のコンパイルに混ぜてしまう方が運用しやすいと考えました。

NuGetから導入する

ArchitectureAnalyzerはNuGetパッケージとして公開しています。

csproj に次のように追加します。

<ItemGroup>
  <PackageReference Include="loach.ArchitectureAnalyzer"
                    Version="0.1.0"
                    PrivateAssets="all" />
  <AdditionalFiles Include="architecture.contract.json" />
</ItemGroup>

PackageReference でAnalyzerを導入し、AdditionalFiles としてArchitecture Contractを渡します。

あとは通常通りビルドするだけです。

dotnet build

Architecture Contractに違反するコードがあれば、Roslyn Diagnosticとして報告されます。

CIでもそのまま利用できる

ArchitectureAnalyzerの主要な診断はコンパイルエラーとして扱われるため、CI専用の特別なコマンドは必要ありません。

例えばGitHub Actionsでも、通常通り dotnet build を実行するだけです。

- name: Build
  run: dotnet build MySolution.sln --no-restore

アーキテクチャ違反があればビルドが失敗するため、そのままCIのゲートとして利用できます。

ローカルではチェックしていたのにCIではAnalyzerを無効化していた、という状態にならないよう、CI側で RunAnalyzersDuringBuild=false を指定したり、対象診断を無効化したりしないことも重要です。

属性ベースのレイヤー宣言にも対応

ArchitectureAnalyzer 0.1.0では、namespaceだけでなく属性を使ったレイヤー宣言にも対応しています。

Architecture Contractに layerDeclaration を定義すると、

  • 必要なレイヤー属性が付いていない
  • 複数の異なるレイヤーが宣言されている
  • namespaceから判定したレイヤーと属性による宣言が一致していない

といった状態を診断できます。

例えば、DomainとApplicationを表す属性を用意して、次のようにArchitecture Contractへ登録します。

{
  "layers": [
    {
      "name": "Domain",
      "namespaceRoots": ["MyApp.Domain"]
    },
    {
      "name": "Application",
      "namespaceRoots": ["MyApp.Application"]
    }
  ],
  "layerDeclaration": {
    "required": true,
    "markerAttributes": [
      {
        "attributeFqn": "MyApp.Architecture.DomainAttribute",
        "layer": "Domain"
      },
      {
        "attributeFqn": "MyApp.Architecture.ApplicationAttribute",
        "layer": "Application"
      }
    ],
    "validateNamespaceConsistency": true,
    "markerNamespace": "MyApp.Architecture"
  }
}

属性自体は通常のC#属性として定義できます。

namespace MyApp.Architecture;

[AttributeUsage(AttributeTargets.Class)]
public sealed class DomainAttribute : Attribute
{
}

[AttributeUsage(AttributeTargets.Class)]
public sealed class ApplicationAttribute : Attribute
{
}

あとは対象の型に属性を付与します。

using MyApp.Architecture;

namespace MyApp.Domain;

[Domain]
public class Order
{
}

この例では、Order はnamespaceからも属性からもDomainレイヤーとして判定されるため問題ありません。

一方、Domain namespace内の型にApplication属性を付けると、namespaceから判定したレイヤーと属性による宣言が食い違います。

using MyApp.Architecture;

namespace MyApp.Domain;

[Application]
public class Order
{
}

validateNamespaceConsistency が true の場合、このような不一致はAARC006として警告されます。

また、required を true にしているため、対象となるクラスに認識可能なレイヤー属性が一つも付いていなければAARC004、複数の異なるレイヤー属性を同時に付ければAARC005として検出されます。

using MyApp.Architecture;

namespace MyApp.Domain;

[Domain]
[Application]
public class Order
{
}

namespaceの配置だけでなく、コード側でも明示的に「この型はどのレイヤーなのか」を宣言したい場合に利用できます。

Interop境界もチェックできる

ArchitectureAnalyzer 0.1.0では、特定のInterop用属性を持つメソッドが、許可されたレイヤー以外に置かれていないかを検証する interopBoundaryRules にも対応しています。

例えばNative APIへの入口をInfrastructureのような特定レイヤーに閉じ込めたい場合、境界を越えたInterop宣言を検出できます。

ArchitectureAnalyzerでできないこと

ArchitectureAnalyzerは、プロジェクトのアーキテクチャそのものが正しいかどうかを判断するツールではありません。

例えば、

「DomainからApplicationへの依存を禁止する」

というルールが本当にそのプロジェクトにとって適切なのかはAnalyzerには分かりません。

ArchitectureAnalyzerが行うのは、

定義されたルールと実際のコードが一致しているかを検証すること

です。

また、通常の静的な型参照を経由しないものまで完全に検出できるわけではありません。

例えば、

  • reflection
  • dynamic
  • 対象外にした生成コード
  • unsafe を使った間接的なアクセス

などは、この仕組みだけですべてを保証できるものではありません。

アーキテクチャの良し悪しを判断するツールではなく、決めたルールが実装から崩れていないかをチェックするツールとして設計しています。

開発のきっかけ

ArchitectureAnalyzerを作ったきっかけは、別途開発している PSXRecompStudio です。

PSXRecompStudioでは、もともとプロジェクト専用のArchitecture Analyzerを使ってアーキテクチャルールを検証していました。

しかし開発を進める中で、

「この仕組みはPSXRecompStudioだけに必要なものではないのでは?」

と考えるようになりました。

そこで、PSXRecompStudio固有のレイヤー名やnamespace、APIルールをAnalyzerから切り離し、利用側のJSONから定義できるようにしたものがArchitectureAnalyzerです。

ArchitectureAnalyzer本体にはPSXRecompStudio固有のルールを持たせず、PSXRecompStudioもArchitectureAnalyzerを利用するプロジェクトの一つとして扱えるようにしています。

現在は、PSXRecompStudioで使用している既存Analyzerとの互換性を確認するためのparity suiteも整備を進めています。

まとめ

設計書やADRにアーキテクチャルールを書いていても、それだけではコードがそのルールを守っている保証にはなりません。

ArchitectureAnalyzerでは、

  • レイヤーを定義する
  • 禁止する依存方向を定義する
  • 禁止APIを定義する
  • 必要に応じて属性やInterop境界も定義する
  • Roslyn Analyzerでコンパイル時に検証する

ことで、アーキテクチャルールを通常の開発フローの中でチェックできるようにしています。

ルールをAnalyzer本体へハードコードせず、Architecture Contractとして利用側のリポジトリに置くことで、プロジェクトごとの設計に合わせられるようにした点がこのツールの特徴です。

まだ開発中のプロジェクトですが、C#プロジェクトのアーキテクチャを設計書だけでなくコンパイル時にも守りたい場合には、一つの方法になると思います。

最後まで読んでいただきありがとうございました。

2
1
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?