Digitals.Analyzers 0.5.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Digitals.Analyzers --version 0.5.0
                    
NuGet\Install-Package Digitals.Analyzers -Version 0.5.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Digitals.Analyzers" Version="0.5.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Digitals.Analyzers" Version="0.5.0" />
                    
Directory.Packages.props
<PackageReference Include="Digitals.Analyzers">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Digitals.Analyzers --version 0.5.0
                    
#r "nuget: Digitals.Analyzers, 0.5.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Digitals.Analyzers@0.5.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Digitals.Analyzers&version=0.5.0
                    
Install as a Cake Addin
#tool nuget:?package=Digitals.Analyzers&version=0.5.0
                    
Install as a Cake Tool

Digitals.Analyzers

Single NuGet package that brings the full org analyzer set plus the shared severity policy. Reference one package instead of four, and severity/banned-API policy comes along centrally.

What it brings

Package Purpose
SonarAnalyzer.CSharp Quality and bug rules
Roslynator.Analyzers Refactoring/style rules
Roslynator.Formatting.Analyzers Formatting rules
Microsoft.VisualStudio.Threading.Analyzers Async/threading rules (VSTHRD)
Microsoft.CodeAnalysis.BannedApiAnalyzers Enforces BannedSymbols.txt (RS0030)

Plus config injected automatically via auto-imported build/Digitals.Analyzers.props / .targets:

  • Digitals.Analyzers.globalconfig — the full org style + severity policy (formatting, idioms, naming rules, CA/S/RCS/VSTHRD severities), ported from the master templates/dotnet/.editorconfig.

  • Digitals.Analyzers.Tests.globalconfig — test-project relaxations (the old [**.Tests/**.cs] section). Injected only into projects whose name ends with .Tests — global configs cannot scope by path, so scoping is per project.

  • BannedSymbols.txt — banned APIs (RS0030, warning; each repo decides escalation via TreatWarningsAsErrors): DateTime.Now/UtcNow/Today and DateTimeOffset.Now/UtcNow — inject TimeProvider instead (TimeProvider.System in DI composition roots, FakeTimeProvider in tests). RS0030 is deliberately clock-only — see the custom rules below.

  • analyzers/dotnet/cs/Digitals.Analyzers.CSharp.dll — custom org rules (warning), enforcing the org temporal-types rule:

    • DT00001 — any reference to System.DateTime, including bare declarations (DateTime Foo { get; set; }) that a banned-symbol list cannot see. Use DateOnly (calendar date), TimeOnly (time of day), TimeSpan (duration) or DateTimeOffset in UTC (instant); DateTime is an interop-boundary exception carrying a #pragma with a reason.
    • DT00002 — DateTimeOffset.LocalDateTime/.DateTime, which silently reintroduce DateTime; .UtcDateTime is the sanctioned boundary conversion.
    • DT00003 — new HttpClient(); use IHttpClientFactory (AddHttpClient) — a client per call exhausts sockets.
    • DT00004 — dynamic; resolve types at compile time (generics, DI, typed models). Not expressible as a banned symbol — dynamic compiles to object plus an attribute.
    • DT00005 — xUnit test names must be Method_Scenario_ExpectedResult (three PascalCase segments). Scoped by the [Fact]/[Theory] attribute, so it is inert outside test projects.
    • DT00006 (suggestion) — double/float member or parameter whose name contains a money term (price, cost, fee, …); use decimal. Name heuristic, IDE-only.
    • Own IDs on purpose: a boundary #pragma warning disable DT00001 never switches off the RS0030 ambient-clock ban in the same region.
  • The globalconfig also escalates shipped-pack rules that are off or info-only by default: SYSLIB1045 ([GeneratedRegex]), CA2254 (structured log templates), VSTHRD100 (no async void, pinned) as warning; CA2100 (raw SQL), CA1002/CA1819 (read-only collection properties), CA1021 (no out params), S109 (magic numbers) as IDE-only suggestion.

  • Digitals.Analyzers.targets — banned NuGet packages (DIGB001 build error on a direct PackageReference): Moq (use NSubstitute), FluentAssertions (use xUnit built-in Assert.*; v8+ requires a commercial license, frozen v7 gets no security backports), xunit/xunit.core (xUnit v2 — use xunit.v3), Newtonsoft.Json/Microsoft.AspNetCore.Mvc.NewtonsoftJson (use System.Text.Json), AutoMapper + its DI extension (write explicit mapping; v15+ commercial license), EntityFramework (EF6 — use Microsoft.EntityFrameworkCore), System.Data.SqlClient (use Microsoft.Data.SqlClient), Microsoft.EntityFrameworkCore.Proxies (no lazy loading), NUnit/MSTest/MSTest.TestFramework (org framework is xunit.v3), and the v2-lineage xUnit integrations TngTech.ArchUnitNET.xUnit/FsCheck.Xunit/Verify.Xunit/Microsoft.Playwright.Xunit (each has a v3-ID replacement). Per the org .NET test stack. Transitive dependencies are not visible to the check. Escape hatch, next to a comment explaining why:

    <DigitalsAllowBannedPackages>Moq</DigitalsAllowBannedPackages>
    

Usage

<PackageReference Include="Digitals.Analyzers">
    <PrivateAssets>all</PrivateAssets>
</PackageReference>

Typically once in Directory.Build.props, replacing the individual analyzer references. Migrating an existing repo: step-by-step in docs/ADOPTION.md. The package is marked DevelopmentDependency, so PrivateAssets="all" is also the default NuGet applies on install — it prevents the analyzers from flowing further into your consumers.

Escape hatch

Legitimate banned-API sites exist (bootstrap logging before DI is built, EF migration defaults):

#pragma warning disable RS0030 // Serilog bootstrap, DI not built yet
Log.Information("Starting at {Now}", DateTimeOffset.UtcNow);
#pragma warning restore RS0030

Suppressions are grep-able and reviewable. If they multiply, that is signal.

Overriding a rule per repo

A repo-local .editorconfig always wins over the packaged globalconfig:

[*.cs]
dotnet_diagnostic.S1234.severity = none

What stays in each repo

Some things a global config cannot express — each repo keeps a thin .editorconfig with only:

root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
trim_trailing_whitespace = true

[*.{props,csproj}]
indent_style = tab
indent_size = 4
tab_width = 4

[*.{cs,vb,cshtml}]
indent_style = tab
indent_size = 4
tab_width = 4
max_line_length = 120

plus any repo-specific path-scoped overrides (e.g. [**/Pages/**.cshtml.cs], [**/Migrations/**.cs]) — global configs have no path sections. A repo-local .editorconfig also always overrides the packaged policy, which is the per-rule opt-out mechanism.

And in Directory.Build.props (compiler switches, not editorconfig knobs):

<Nullable>enable</Nullable>
<WarningsAsErrors>nullable</WarningsAsErrors>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>

EnforceCodeStyleInBuild is required for the IDExxxx style rules to fire in dotnet build at all.

Design notes

  • Verified in a real build (scratch consumer against the packed nupkg): RS0030 fires, Sonar/Roslynator/VSTHRD load, naming rules (IDE1006) fire from the globalconfig, and the .Tests globalconfig suppresses (e.g. S1186) only in test projects.

  • Naming-rule build enforcement needs dotnet_diagnostic.IDE1006.severity — the per-rule severity inside dotnet_naming_rule.* is IDE-only. The master .editorconfig was missing this; the packaged globalconfig has it.

  • Test scoping is by project name (*.Tests), not path glob. Rename conventions (.Tests.Unit etc.) need the condition in build/Digitals.Analyzers.props extended.

  • Meta-package mechanics. NuGet's default for dependencies is exclude="build,analyzers" — a naive meta-package brings nothing. Every PackageReference in the csproj carries PrivateAssets="none" to force analyzer assets to flow. Do not remove it.

  • netstandard2.0, no multi-targeting. Analyzers run inside the compiler process, not the consuming app; consumer TFM is irrelevant. The only multi-targeting dimension that exists for analyzers is Roslyn version (analyzers/dotnet/roslyn4.x/cs/ folders) — not needed until a custom rule requires a newer Roslyn API.

  • C# only in practice. Sonar C# and Roslynator are C#-only; the threading and banned-API analyzers also cover VB. F# is out of scope entirely (different compiler, no Roslyn analyzers). In a VB or F# project this package silently does nothing.

  • Version pinning lives here. Bumping any analyzer means releasing a new version of this package. That is the point: one version to review, org-wide consistency.

Adding custom org rules

Custom Roslyn analyzers (org naming conventions, architecture rules) live in src/Digitals.Analyzers.CSharp (netstandard2.0, conservative Roslyn pin, DLL packed into analyzers/dotnet/cs/ — not lib/), tested in tests/Digitals.Analyzers.CSharp.Tests with Microsoft.CodeAnalysis.CSharp.Analyzer.Testing + xUnit v3. Adding a rule:

  1. Next DT##### ID — stable prefix, never reuse or renumber IDs: they end up in suppressions and configs across repos.
  2. Row in AnalyzerReleases.Unshipped.md (RS2008 release tracking); move to Shipped.md when the version ships.
  3. Severity line in the globalconfig (warning — repos escalate via TreatWarningsAsErrors).
  4. Tests for the report cases, the clean cases, and the #pragma escape.

Simple naming/style rules are cheap (a day for the first including tests, hours after that). Avoid dataflow rules — Sonar already does them.

Releasing

Versioning is MinVer: the version comes from git v* tags, not the csproj. To release:

git tag v1.1.0
git push origin v1.1.0

.github/workflows/release.yml packs the tagged commit and pushes it to nuget.org, then opens a GitHub Release for the tag. Re-running the workflow on the same tag is a no-op (--skip-duplicate), because the tag fully determines the version.

Tags are the only thing that publishes. Pushes to main run .github/workflows/ci.yml, which tests and packs and attaches the .nupkg as a build artifact, but publishes nothing. For a local package to inspect or test against, just pack writes to artifacts/.

Publishing uses nuget.org Trusted Publishing — a short-lived OIDC-issued key, no long-lived API key in GitHub secrets. The policy on nuget.org is bound to this repo and to the release.yml filename, so renaming that workflow file breaks publishing until the policy is updated. The one secret required is NUGET_USER, the nuget.org profile name.

License

MIT — see LICENSE. The license covers this repository's own code: the globalconfigs, BannedSymbols.txt, the .targets banned-package check and the custom DT##### analyzer. The bundled third-party analyzers keep their own licenses and reach consumers as ordinary NuGet dependencies.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.