Newsletter

Get the Thursday issue.

One focused C# tutorial. Free, and easy to leave.

  • 4,000+ engineers
  • 100+ tutorials
Enforcing Architecture Rules in .NET with NsDepCop

Enforcing Architecture Rules in .NET with NsDepCop

19 Nov 2026 · 5 min

Sponsor Newsletter

As .NET solutions grow, structure stops being the problem.

You can define folders, layers, or even full architectural styles, but over time something always happens:

  • A shortcut gets introduced
  • A “temporary” dependency stays forever
  • Boundaries slowly disappear
  • Refactoring becomes a nightmare

Worst part? It happens slowly and you don't even notice it. Until you do and you have to untangle the mess because there was nothing to stop it in the first place.

This is where NsDepCop becomes useful. It doesn't care what architecture you use, it only cares about enforcing the dependency rules you defined.

What is NsDepCop?

NsDepCop is a static analysis tool for C# that checks whether code in one namespace depends on code in another.

Instead of relying on project structure, it allows you to define explicit rules like:

  • Namespace A can depend on Namespace B
  • Namespace B cannot depend on Namespace C
  • Certain namespaces must remain isolated
  • Some namespaces are allowed to reference everything

Unlike architectural tests that run in a test project, NsDepCop runs as part of the normal compile pipeline, so broken boundaries are caught before you push.

To learn more about Architecture Tests, you can read my blog post on Architecture Tests in .NET.

Getting Started

To get started with NsDepCop, you'll first need to install the necessary NuGet packages. You can do this via the NuGet Package Manager or by running the following command in the Package Manager Console:

shell
dotnet add package NsDepCop

Then define your rules in an XML configuration file, config.nsdepcop:

xml
<NsDepCopConfig>

  <Allowed From="*" To="*"/>
  <Disallowed From="WebApi.Domain.*" To="WebApi.Persistence.*"/>

</NsDepCopConfig>

At build time, NsDepCop checks all namespace dependencies against rules you can define in XML file.

Because it's a Roslyn analyzer, there will be no runtime surprises or hidden couplings.

Enforce Clean Architecture rules

A very common setup in real-world .NET applications is following Clean Architecture principles.

To enforce the separation between layers, teams often create a separate class library for each layer.

So you end up with something like:

src
 ├── Domain
 ├── Business
 ├── Persistence
 ├── Infrastructure
 └── Presentation

And while this does work, it often becomes unnecessarily heavy, especially in the early stages of a project.

Before you even get to real business value, you’ve already spent time on solution structure, project references, and wiring everything together. For small or medium systems, it can feel like overhead that slows you down more than it helps.

That’s why I prefer starting with a single project and using namespaces instead of class libraries to represent architectural layers.

This keeps the solution simple while still allowing a clear separation of concerns:

src
 └── WebApi
      ├── Domain
      ├── Business
      ├── Persistence
      ├── Infrastructure
      └── Presentation

The problem with this approach has always been enforcement. Without additional tooling, namespaces are just conventions.

That’s where NsDepCop becomes extremely useful, allowing me to enforce architectural rules directly on namespaces:

xml
<?xml version="1.0" encoding="utf-8"?>

<NsDepCopConfig IsEnabled="true">

  <Allowed From="*" To="*"/>

  <!-- Domain must stay isolated -->
  <Disallowed From="WebApi.Domain.*" To="WebApi.Infrastructure.*"/>
  <Disallowed From="WebApi.Domain.*" To="WebApi.Persistence.*"/>
  <Disallowed From="WebApi.Domain.*" To="WebApi.Business.*"/>

  <!-- Business/Application -->
  <Disallowed From="WebApi.Business.*" To="WebApi.Infrastructure.*"/>
  <Disallowed From="WebApi.Business.*" To="WebApi.Persistence.*"/>

</NsDepCopConfig>

This way, we enforced the Clean Architecture rules at the namespace level.

Domain stays isolated, and Business cannot depend on the Infrastructure or Persistence namespaces.

By default, NsDepCop reports these violations as warnings, so the build still passes. To make them fail the build, raise the severity of the NSDEPCOP01 diagnostic to an error in an .editorconfig file:

ini
[*.cs]
dotnet_diagnostic.NSDEPCOP01.severity = error

Now any illegal namespace reference breaks the build instead of just showing a warning.

You can also set a few more options on the root element, such as:

  • ChildCanDependOnParentImplicitly
  • ParentCanDependOnChildImplicitly
  • IsEnabled
  • MaxIssueCount etc.

Conclusion

NsDepCop is a very interesting tool with a lot of potential when it comes to enforcing rules at the namespace level.

With NsDepCop, architecture rules are no longer optional, they are enforced at build time.

You can define strict boundaries even in a single-project setup and prevent architectural erosion over time, instead of relying on conventions or manual discipline.

If you want to check out the example I created, you can find the source code here:

Source Code

I hope you enjoyed it, subscribe and get a notification when a new blog is up!