EnsureArch 🏗️

Architecture Guarantee at Compile Time with Roslyn Analyzers

EnsureArch is a library that uses Roslyn Analyzers to ensure your .NET application follows defined architecture rules, providing immediate feedback during compilation instead of relying on unit tests.

🎯 Motivation

Unlike libraries such as NetArchTest that validate architecture through unit tests, EnsureArch:

• ✅ Immediate Feedback: Architecture errors are detected during compilation
• ✅ IDE Integration: Warnings and errors appear directly in Visual Studio/VS Code
• ✅ CI/CD Friendly: Build fails automatically if there are violations
• ✅ Zero Overhead: Doesn't add code to the application runtime

🚀 How It Works

flowchart TD
    Config[architecture.json] --> Analyzer[Roslyn Analyzer]
    Code[C# Code] --> Analyzer
    Analyzer --> Validation{Validate Dependencies}
    Validation -->|✅ Valid| Success[Compilation OK]
    Validation -->|❌ Invalid| Error[ARCH001: Architecture Violation]
    Error --> BuildFail[Build Fails]

Loading

📦 Installation

dotnet add package EnsureArch.Analyzer

🔧 Configuration

1. Create architecture.json file

Add the file to your project root:

{
  "baseNamespace": "EnsureArch.Playground",
  "rules": [
    {
      "on": "Api",
      "allow": ["IoC", "ServiceDefaults", "Shareable"]
    },
    {
      "on": "Domain", 
      "allow": ["Shareable"]
    },
    {
      "on": "Data",
      "allow": ["Domain", "Shareable"]
    },
    {
      "on": "IoC",
      "allow": ["Api", "Domain", "Data", "ServiceDefaults", "Shareable"]
    },
    {
      "on": "ServiceDefaults",
      "allow": ["Shareable"]
    },
    {
      "on": "Shareable",
      "allow": []
    }
  ]
}

2. Include in .csproj

<Project Sdk="Microsoft.NET.Sdk">
  
  <ItemGroup>
    <PackageReference Include="EnsureArch.Analyzer" Version="1.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
  
  <ItemGroup>
    <AdditionalFiles Include="architecture.json" />
  </ItemGroup>
  
</Project>

🏗️ Architecture Example

graph TB
    subgraph "Application Layers"
        Api[🌐 Api Layer<br/>Controllers, Endpoints]
        Domain[🏢 Domain Layer<br/>Entities, Services]
        Data[💾 Data Layer<br/>Repositories, DbContext]
        IoC[🔌 IoC Layer<br/>Dependency Injection]
        ServiceDefaults[⚙️ Service Defaults<br/>Common Configurations]
        Shareable[📦 Shareable<br/>DTOs, Interfaces]
    end
    
    Api --> IoC
    Api --> ServiceDefaults
    Api --> Shareable
    
    Domain --> Shareable
    
    Data --> Domain
    Data --> Shareable
    
    IoC --> Api
    IoC --> Domain
    IoC --> Data
    IoC --> ServiceDefaults
    IoC --> Shareable
    
    ServiceDefaults --> Shareable

Loading

❌ Detected Violations

Violation Example

// ❌ ARCH001: Namespace dependency violation
// The namespace 'EnsureArch.Playground.Domain' cannot depend on 'EnsureArch.Playground.Api' according to architecture.json

namespace EnsureArch.Playground.Domain;

using EnsureArch.Playground.Api; // ❌ Violation!

public class UserService
{
    // Domain cannot depend on Api
}

Error Message

ARCH001: The namespace 'EnsureArch.Playground.Domain' cannot depend on 'EnsureArch.Playground.Api' according to architecture.json

✅ Correct Usage

// ✅ Allowed dependency
namespace EnsureArch.Playground.Domain;

using EnsureArch.Playground.Shareable; // ✅ Allowed!

public class UserService
{
    public UserDto GetUser(int id) // Using DTO from Shareable
    {
        // Implementation
    }
}

🔍 How the Analyzer Works

1. Configuration Loading

public static ArchitectureModel? LoadArchitecture(AnalyzerOptions options)
{
    var file = options.AdditionalFiles.FirstOrDefault(f => f.Path.EndsWith("architecture.json"));
    if (file == null) return null;

    using var fileStream = new FileStream(file.Path, FileMode.Open);
    var deserializer = System.Text.Json.JsonSerializer.Deserialize<ArchitectureModel>(fileStream);
    return deserializer;
}

2. Dependency Analysis

context.RegisterSyntaxNodeAction(ctx =>
{
    if (ctx.Node is UsingDirectiveSyntax { Name: { } @namespace } usingDirective)
    {
        var sourceNamespace = GetSourceNamespace(ctx.Node);
        var targetNamespace = @namespace.ToString();
        
        if (!IsAllowedDependency(sourceNamespace, targetNamespace))
        {
            var diagnostic = Diagnostic.Create(Rule, usingDirective.GetLocation(), 
                sourceNamespace, targetNamespace);
            ctx.ReportDiagnostic(diagnostic);
        }
    }
}, SyntaxKind.UsingDirective);

📋 Data Models

public record ArchitectureModel(string BaseNamespace, List<DependencyRule> Rules);

public record DependencyRule(string On, List<string> Allow);

🛠️ Advanced Configuration

Multiple Projects

For solutions with multiple projects, each project can have its own architecture.json:

Solution/
├── Project.Api/
│   ├── architecture.json
│   └── Project.Api.csproj
├── Project.Domain/
│   ├── architecture.json
│   └── Project.Domain.csproj
└── Project.Data/
    ├── architecture.json
    └── Project.Data.csproj

Global Configuration

Or use a global file at the solution root:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <AdditionalFiles Include="../architecture.json" />
  </ItemGroup>
</Project>

🔧 CI/CD Integration

GitHub Actions

name: Architecture Validation

on: [push, pull_request]

jobs:
  validate-architecture:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '8.0.x'
    
    - name: Build and Validate Architecture
      run: dotnet build --configuration Release
      # Build will fail if there are ARCH001 violations

Azure DevOps

- task: DotNetCoreCLI@2
  displayName: 'Build and Validate Architecture'
  inputs:
    command: 'build'
    configuration: 'Release'
    # Pipeline will fail automatically with violations

🎨 IDE Integration

Visual Studio

• ✅ Errors appear in Error List
• ✅ Red squiggles in code
• ✅ Tooltips with error messages
• ✅ Solution Explorer integration

VS Code

• ✅ Problems appear in Problems Panel
• ✅ C# Extension integration
• ✅ IntelliSense warnings

🆚 Comparison with NetArchTest

Aspect	EnsureArch	NetArchTest
Feedback	⚡ Compile time	🧪 Test time
IDE Integration	✅ Native	❌ Only in tests
CI/CD	✅ Build fails automatically	⚠️ Depends on test execution
Performance	✅ Zero runtime overhead	⚠️ Test overhead
Configuration	📄 JSON file	💻 C# code
Flexibility	⚠️ Limited to JSON	✅ Custom logic

🔮 Roadmap

• Attribute Support: Attribute-based validation
• Custom Rules: Plugin extensibility
• Architecture Metrics: Complexity reports
• Visual Studio Extension: GUI for configuration
• VB.NET Support: Expand beyond C#
• Integration Tests: External dependency validation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

🔗 Useful Links

• Roslyn Analyzers Documentation
• NetArchTest (Inspiration)
• Clean Architecture Principles

---

Keep your architecture clean and consistent with EnsureArch! 🏗️✨