DiagnosticCatalog.Self 1.0.1

DiagnosticCatalog.Self

🌍 Languages:
🇬🇧 English (this file) | 🇫🇷 Français

The DCAT rules — the ones the analyzers inside DiagnosticCatalog report — as constants you can reference.

It is the library applied to itself. The analyzers that check your suppressions publish their own rules the same way they ask everybody else to, and they do it through the same generator that produces the Sonar, .NET-analyzers and StyleCop catalogues.

When you want it

When you suppress a DCAT diagnostic and would rather the suppression be checked:

using System.Diagnostics.CodeAnalysis;
using DiagnosticCatalog.Self;

// Migrating a large codebase: this file is done last, and the literals here are deliberate.
[SuppressMessage(
    DcatRule.DCAT0006.Category,
    DcatRule.DCAT0006.Id,
    Justification = "Legacy suppressions, migrated in the next pass.")]
public static class LegacyInterop
{
}

Without the catalogue you would write [SuppressMessage("DiagnosticCatalog", "DCAT0006")] — two strings nothing checks, which is the exact problem this repository exists to remove. It would have been odd to leave our own rules as the one place you still had to write them by hand.

Most projects will not need this: .editorconfig is the usual way to turn a DCAT diagnostic down, and it takes plain text that no constant can ever be substituted into. Reach for the catalogue when you are suppressing at a specific site, for a reason worth writing down.

Where it comes from

Generated from the analyzers' own DiagnosticDescriptor instances, never from documentation, so the id and the category are the values the analyzer actually reports. Regenerating it is one command:

dotnet run --project src/DiagnosticCatalog.Cli -- generate --manifest eng/catalogs.json

CI regenerates it on every pull request and fails if the result differs from what is committed — so a new DCAT id cannot ship without the catalogue that publishes it.

Versioning

This catalogue rides the lib train, with the analyzers it mirrors, and that is deliberate: the two are generated from one source in one repository and must never describe different rule sets. The other eleven catalogues version independently because an outside vendor sets their pace (ADR-0015); nobody outside sets this one's.

A retired rule is carried forward as [Obsolete] rather than deleted, like everywhere else here: constants are inlined into your assembly at your compile time, so removing one breaks your build with a message that names nothing useful.

See also

Every catalogue this repository publishes is listed in one place — pick the one that matches an analyzer you run:

The ready-made catalogues

Want a catalogue of your own? Your analyzer's rules, or an internal ruleset, are declared exactly the way these are: a static class of constants marked [DiagnosticRule], referenced by consumers instead of retyped. That marker ships in DiagnosticCatalog, the foundation this catalogue is built on, and its README is the guide.

Documentation

• The DCAT diagnostics — every rule catalogued here, seen from the side that reports it.
• Writing suppressions that the compiler checks — how to use these constants, which is the same as for any other catalogue.
• Repository architecture — the self-application loop this package is one half of, and why it runs in one direction.

The documentation map picks a page by what you are trying to do; every guide exists in English and French.

Licence

Apache-2.0.