This project has moved. For the latest updates, please go here.
This project has been moved to GitHub.
For the latest documentation please follow this link:
https://github.com/realvizu/NsDepCop

Dependency Rules

  • Allowed and disallowed dependencies are described with dependency rules in config files.
  • There can be one rule config file per C# project (csproj file).
  • The rule config file must be named config.nsdepcop and must be placed next to the csproj file.

Example

<NsDepCopConfig IsEnabled="true" CodeIssueKind="Warning" ChildCanDependOnParentImplicitly="true">
    <Allowed From="*" To="System.*" />
    <Allowed From="Codartis.NsDepCop.MsBuildTask" To="Microsoft.Build.*" />
    <Allowed From="Codartis.NsDepCop.MsBuildTask" To="Codartis.NsDepCop.Core" />
</NsDepCopConfig>

Meaning:
  • Any namespace can reference the System namespace and any of its sub-namespaces.
  • The Codartis.NsDepCop.MsBuildTask namespace can reference the Microsoft.Build namespace and its sub-namespaces.
  • The Codartis.NsDepCop.MsBuildTask namespace can reference the Codartis.NsDepCop.Core namespace (but not its sub-namespaces).

Config switches

You can set the following switches on the root element. (Bold marks the the default value.)

Attribute Values Description
IsEnabled true, false If set to false then analysis is not performed for the project.
CodeIssueKind Info, Warning, Error Disallowed dependencies are reported at this severity level.
ChildCanDependOnParentImplicitly true, false If set to true then all child namespaces can depend on any of their parents without an explicit allowing rule.

Allowed element: whitelisting dependencies

To allow a namespace dependency there must be at least one matching Allowed rule for it.

Special symbols:
. (a single dot) = the global namespace
* (a single star) = any namespace
MyNamespace.* = MyNamespace and any sub-namespaces

Examples:
<Allowed From="MyNamespace" To="System" /> MyNamespace can depend on System
<Allowed From="MyNamespace" To="System.*" /> MyNamespace can depend on System and any sub-namespace
<Allowed From="MyNamespace" To="*" /> MyNamespace can depend on any namespace
<Allowed From="MyNamespace" To="." /> MyNamespace can depend on the global namespace

VisibleMembers element: defining a "surface"

If you're using a namespace that has some types that must be visible but also other types that you don't want to depend upon then you can narrow down the visible part of the namespace.

Example:
<NsDepCopConfig>
    <Allowed From="GameLogic" To="UnityEngine" />
    <VisibleMembers OfNamespace="UnityEngine">
        <Type Name="Vector2" />
        <Type Name="Vector3" />
    </VisibleMembers>
</NsDepCopConfig>

Meaning:
  • GameLogic can use UnityEngine but only Vector2 and Vector3 types.

Disallowed element: blacklisting dependencies

  • The recommended approach is whitelisting: that is, nothing is allowed but the ones explicitly listed as such.
  • However there is also the blacklisting approach: that is, everything is allowed but the ones that are explicitly listed as disallowed.
  • To implement the blacklisting (opt-out) behavior, define an "allow all" rule and then the desired disallowed rules.
Example blacklisting config:
<NsDepCopConfig IsEnabled="True" CodeIssueKind="Warning">
    <Allowed From="*" To="*" />
    <Disallowed From="MyFrontEnd.*" To="MyDataAccess.*" />
</NsDepCopConfig>

Meaning:
  • Every dependency is allowed but MyFrontEnd cannot reference MyDataAccess (or any of their sub-namespaces).
Details:
  • You can specify any number of "Allowed" and "Disallowed" rules in any order.
  • Only those dependencies are allowed that has a matching "Allowed" rule and no match with any of the "Disallowed" rules.
  • If both an "Allowed" and a "Disallowed" rule is matched then "Disallowed" is the "stronger".

The ChildCanDependOnParentImplicitly attribute

You can specify the ChildCanDependOnParentImplicitly attribute on the NsDepCopConfig element:
  • True means that all child namespaces can depend on any of their parent namespaces without an explicit Allowed rule.
  • True is in line with how C# type resolution works: it searches parent namespaces without an explicit using statement.
  • False means that all dependencies must be explicitly allowed with a rule.
  • False is the default for backward compatibility.
Example:
<NsDepCopConfig IsEnabled="True" CodeIssueKind="Warning" ChildCanDependOnParentImplicitly="true">
    <!-- The following rule is not necessary because the ChildCanDependOnParentImplicitly="true" attribute implies it. -->
    <Allowed From="MyNamespace.SubNamespace" To="MyNamespace" />
</NsDepCopConfig>

Last edited Mar 26 at 1:15 PM by vizu, version 9

Comments

No comments yet.