Conventions Complete

Getting Started With Conventions Complete

Conventions Complete is a convention management tool for .NET projects. It automates the enforcement of naming rules, coding standards, and architectural constraints across your codebase. The package scans assemblies at build time and surfaces violations as compilation warnings or errors depending on your configuration. Most teams use it as part of their CI pipeline rather than relying on it during local development. I installed it on a medium-sized solution with roughly 45 projects about eight months ago. The initial setup took about twenty minutes. After that, the first scan produced over three hundred violations. That number dropped to under forty within two weeks after the team addressed the high-confidence items. The rest stayed as suppressed warnings.

What Conventions Complete Actually Does

The core workflow works in three stages. First, you install the NuGet package into a shared analytical project. Second, you define a rule set in code using a fluent configuration API. Third, you run the analyzer either through MSBuild integration or as a standalone console task. The tool does not modify your source files. It only reports what it finds. The configuration uses Cobjects rather than JSON files or YAML configs. This means you get full IntelliSense support and compile-time validation of your rule definitions. If you mistype a method name in the configuration, you will know before deploying the analyzer. That eliminates a whole category of setup errors that show up with other convention tools.

Installation and Basic Setup

Create a separate class library project for your conventions. Call it something like MyCompany.CodeAnalysis or Team.Analyzers. Add the ConventionsComplete package from NuGet. Then create a configuration class that implements IConventionConfig or uses the provided ConventionConfig base class. Next, reference that project from each of your source projects. Do not add the NuGet package to every project. One central analytical project keeps version management straightforward. When you need to update the analyzer version, you change one line instead of forty-five. The build integration works automatically once you reference the analytical project. You will see convention violations appear in the Error List window within Visual Studio. The warnings show up with a distinctive prefix that makes filtering quick. I typically pin a filtered view to my main editor window so violations stay visible throughout the day.

Writing Your First Rule Set

Start with simple naming conventions. The default configuration includes basic rules for types, methods, properties, and fields. You do not need to define every rule from scratch. Override only what you want to change. A typical configuration block looks like this:

public override void Configure()
{
    ForTypes()
        .ShouldMatchPattern("[A-Z][a-zA-Z0-9]*")
        .WithSeverity(WarningLevel.Error);

    ForMethods()
        .ShouldNotContainSubstring("Async")
        .When(x => x.ReturnType == typeof(Task));
}

The pattern matching uses regular expressions by default. You can switch to simple string matching if that feels cleaner for your team. I prefer regex for type names because it handles acronyms better. Words like URLParser or IOManager match more predictably with pattern-based rules. Conventions Complete supports conditional rules. You can apply different conventions based on project type, namespace, assembly origin, or custom attributes. This is useful when you need to treat library code differently from application code or when third-party assemblies should be excluded from certain checks. Here is a real example from my setup. I needed to allow underscore-prefixed private fields in one project because it was wrapping a legacy COM interface. The workaround was to create a custom attribute and then check for it in the field naming rule:

ForFields()
    .ShouldMatchPattern("_?[a-z][a-zA-Z0-9]*")
    .ExceptWhen();

I placed that attribute on the AssemblyInfo file for the affected project. The analyzer skips underscore fields only in assemblies marked with that attribute. Other projects still enforce the stricter rule. This kept consistency across the solution while handling the one edge case that could not be refactored. The biggest issue I encountered during the first month was rule ordering. Conventions Complete evaluates rules in declaration order. If you define a broad exception rule before a specific enforcement rule, the exception takes precedence and the specific rule never fires. I spent about three hours debugging a situation where a naming exception appeared to be completely ignored. The problem was that I had placed it after a blanket rule that suppressed all warnings in a certain namespace. Another problem surface-level configurations create. Setting a rule to Error severity on the first day will break builds across your entire organization. I recommend starting every new rule at Warning level. Let the team adjust their code gradually. Once the warning count for a rule drops below ten percent of the codebase, then promote it to Error. This timeline usually takes two to four weeks depending on team size and codebase age.

Performance is another consideration. Large solutions with many analytical rules can see build times increase by fifteen to thirty seconds. The bottleneck is usually reflection-based analysis on large assemblies. If your solution exceeds one hundred projects, consider running the convention checks as a separate post-build step rather than inline with compilation. A standalone execution takes about forty seconds on our largest project and produces a report file instead of warnings.

When Conventions Complete Is Not the Right Tool

The tool focuses on naming and structural conventions. It does not handle logic complexity, cyclomatic complexity, or design pattern enforcement. If your team needs those, you should pair it with a static analysis tool like NDepend or SonarQube. Using both together covers the gaps. The combination typically requires about five hours of initial configuration spread across a week of part-time work. Conventions Complete also struggles with generated code. If your project produces partial classes or auto-generated files through T4 templates, Entity Framework migrations, or protobuf generators, the analyzer will flag them unless you explicitly exclude those paths. I added a glob-based exclusion pattern for all generated directories. The configuration looked like this:

ExcludePaths("/Generated/", "/*.g.cs", "/Migrations/*.cs");

This reduced false positives by about eighty percent on our first scan. Without those exclusions, the violation count was nearly unusable. Generated code should never trigger convention warnings in my opinion. It is not something developers can control directly. The standard approach is to add a build step that runs the analyzer against the compiled assemblies. Most teams configure this as a failing step so that PRs cannot be merged with violation thresholds exceeded. A practical threshold for our team was set at five warnings per thousand lines of production code. Test code gets a separate, looser threshold. We use Azure DevOps for this integration. The pipeline stage runs the convention check after compilation and before the test phase. If the check fails, the pipeline exits with code one and the build turns red. The output includes a summary report that gets archived as a build artifact. Reviewers can download it to see what changed between passes.

The report format is XML by default. You can configure it to emit JSON instead if your pipeline tools prefer that format. JSON output is easier to parse programmatically and integrates better with dashboards. We route the JSON report into a Grafana panel so the team can track violation trends over time without opening individual build logs.

Suppressing Specific Violations

Sometimes you need to suppress a violation on a single line or method. Conventions Complete supports this through XML comments and compiler directives. Adding a special comment above the offending code suppresses just that instance: I recommend using suppressions sparingly. Each suppression is a signal that the rule may not fit the specific context. If you find yourself adding more than five suppressions for the same rule across a project, the rule probably needs adjustment rather than more overrides. I rewrote one of our method naming rules after noticing twelve suppressions in a single domain service layer. The original rule did not account for repository-style method names that the domain team wanted to preserve. If your team currently uses Resharper conventions or StyleCop, migrating to Conventions Complete requires reconfiguring each rule individually. There is no direct import path. The configuration syntax is fundamentally different. Resharper uses XML profiles. StyleCop uses XML settings. Conventions Complete uses Ccode. Expect to spend a day or two porting your rules unless your existing configuration is minimal.

One advantage during migration is that you can run both analyzers in parallel. Keep your old configuration active while you gradually move rules over. This gives the team a fallback if something breaks and lets you compare outputs side by side. I used a branch-based approach where the migration happened on a feature branch. The old and new analyzers ran concurrently for about two weeks before we removed the legacy configuration entirely.

Practical Tips That Matter

Version your convention configuration alongside your solution. Store it in the same repository. Pin the NuGet package version in a central packages.config or PackageReference file. Random updates to the analyzer version have caused breaking changes in our pipeline before. The team lost about an hour figuring out why a previously passing build started failing after a routine dependency update. Document your convention choices in a README inside the analytical project. Explain why certain rules exist and what business or technical rationale drove them. New team members benefit from this context. Without it, developers often see convention violations as arbitrary restrictions rather than deliberate engineering decisions. Run the analyzer locally before pushing to CI. A quick dotnet build with the analytical project referenced will catch most issues. The CI check becomes a safety net rather than the primary gate. This reduces feedback time from hours to minutes for most violations.

Conventions Complete works well for teams that need automated enforcement of coding standards without maintaining a large custom analyzer codebase. The trade-off is the initial configuration effort and the ongoing maintenance of the rule set as the team evolves its practices. The tool does not solve every convention problem. Naming and structural checks are where it shines. Anything beyond that requires additional tooling or manual code review.