Skip to content

Needlr Analyzers

Needlr includes optional Roslyn analyzers to help developers avoid common mistakes and ensure best practices.

Core Analyzers (NexusLabs.Needlr.Analyzers)

These analyzers are included with the NexusLabs.Needlr package.

Rule ID Severity Description
NDLRCOR001 Error Reflection API used in AOT project
NDLRCOR002 Warning Plugin has constructor dependencies
NDLRCOR003 Error [DeferToContainer] attribute in generated code is ignored
NDLRCOR004 Warning Injectable type in global namespace may not be discovered
NDLRCOR005 Warning Lifetime mismatch: longer-lived service depends on shorter-lived service
NDLRCOR006 Error Circular dependency detected
NDLRCOR007 Error Intercept type must implement IMethodInterceptor
NDLRCOR008 Warning [Intercept] applied to class without interfaces
NDLRCOR009 Info Lazy references undiscovered type
NDLRCOR010 Info IEnumerable has no discovered implementations
NDLRCOR011 Info [FromKeyedServices] keyed service usage tracking
NDLRCOR012 Error Disposable captive dependency
NDLRCOR015 Error [RegisterAs] type T not implemented by class

SignalR Analyzers (NexusLabs.Needlr.SignalR.Analyzers)

These analyzers are included with the NexusLabs.Needlr.SignalR package.

Rule ID Severity Description
NDLRSIG001 Warning HubPath must be a constant expression
NDLRSIG002 Warning HubType must be a typeof expression

Generator Diagnostics (NexusLabs.Needlr.Generators)

These diagnostics are emitted by the source generator to detect configuration issues at compile time.

Rule ID Severity Description
NDLRGEN001 Error Internal type in referenced assembly cannot be registered
NDLRGEN002 Error Referenced assembly has internal plugin types but no type registry
NDLRGEN003 Warning [GenerateFactory] all parameters are injectable
NDLRGEN004 Warning [GenerateFactory] no parameters are injectable
NDLRGEN005 Error [GenerateFactory] type T not implemented by class
NDLRGEN006 Error [OpenDecoratorFor] type must be an open generic interface
NDLRGEN007 Error [OpenDecoratorFor] decorator must be an open generic class
NDLRGEN008 Error [OpenDecoratorFor] decorator must implement the interface
NDLRGEN014 Error [Options] Validator type has no validation method
NDLRGEN015 Error [Options] Validator type mismatch
NDLRGEN016 Error [Options] Validation method not found
NDLRGEN017 Error [Options] Validation method has wrong signature
NDLRGEN018 Warning [Options] Validator won't run (ValidateOnStart is false)
NDLRGEN019 Warning [Options] Validation method won't run (ValidateOnStart is false)
NDLRGEN020 Error [Options] is not compatible with Native AOT
NDLRGEN021 Warning [Options] Positional record must be partial
NDLRGEN022 Error Disposable captive dependency (uses inferred lifetimes)
NDLRGEN031 Error [Provider] on class requires partial modifier
NDLRGEN032 Error [Provider] interface has invalid member
NDLRGEN033 Warning [Provider] property uses concrete type
NDLRGEN034 Error [Provider] circular dependency detected

Diagnostic ID Naming Convention

Needlr uses a component-based naming convention for diagnostic IDs:

Component Prefix Example
Core Analyzers NDLRCOR NDLRCOR001
SignalR Analyzers NDLRSIG NDLRSIG001
Source Generators NDLRGEN NDLRGEN001

Suppressing Warnings

To suppress a specific analyzer warning, use pragma directives:

#pragma warning disable NDLRCOR001
// Code that triggers the warning
#pragma warning restore NDLRCOR001

Or suppress in your project file for the entire project:

<PropertyGroup>
  <NoWarn>$(NoWarn);NDLRCOR002</NoWarn>
</PropertyGroup>

Or configure severity in .editorconfig (recommended):

# .editorconfig
[*.cs]
# Disable a diagnostic
dotnet_diagnostic.NDLRCOR009.severity = none

# Promote to warning
dotnet_diagnostic.NDLRCOR010.severity = warning

# Promote to error
dotnet_diagnostic.NDLRCOR005.severity = error

Resolution Validation Analyzers

NDLRCOR009, NDLRCOR010, and NDLRCOR011 are resolution validation analyzers that help catch potential issues with service resolution patterns.

These analyzers:

  • Only activate when [assembly: GenerateTypeRegistry] is present
  • Default to Info severity (non-blocking)
  • Can be promoted to Warning or Error via .editorconfig
Analyzer Purpose
NDLRCOR009 Validates Lazy<T> references discoverable types
NDLRCOR010 Validates IEnumerable<T> has implementations
NDLRCOR011 Tracks [FromKeyedServices] keyed service usage

To see which analyzers are active in your project, enable diagnostics output:

<PropertyGroup>
  <NeedlrDiagnostics>true</NeedlrDiagnostics>
</PropertyGroup>

This generates AnalyzerStatus.md in your output directory showing all analyzers and their current severity.

Configuration

Analyzers are automatically enabled when you reference the Needlr packages. No additional configuration is required.

For AOT projects, ensure your project has the appropriate settings for the analyzers to detect AOT mode:

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <!-- or -->
  <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>