AutoMapperAnalyzer.Analyzers 2.30.99

AutoMapper Roslyn Analyzer

Compile-time AutoMapper CreateMap validation for .NET — a high-signal Roslyn analyzer that checks Profile, CreateMap, ForMember, MapFrom, ReverseMap, ConvertUsing, and ProjectTo configurations so type mismatches, nullable holes, unmapped required members, and missing registrations fail in the editor and CI, not as AutoMapperMappingException in production.

Catch AutoMapper configuration errors at compile-time before they cause runtime chaos.

The problem

AutoMapper is powerful, but many mapping failures compile cleanly. A property type mismatch on CreateMap, a nullable source into a non-nullable destination, an unmapped required member, a nested object without its own map, or a Map/ProjectTo call with no reachable registration typically surfaces as a runtime exception, silent default, or production NullReferenceException — not as a compile error.

Runtime tests and manual review miss what static analysis can prove from your mapping configuration.

What it catches

AutoMapperAnalyzer reports high-signal mapping problems early:

• property type mismatches on CreateMap (AM001) with conversion or Ignore code fixes
• nullable → non-nullable mappings that risk null failures (AM002)
• incompatible collection containers and element types (AM003 / AM021)
• missing source members, unmapped destinations, case-only name drift, and required members (AM004 / AM005 / AM006 / AM011)
• nested object maps that need an extra CreateMap (AM020)
• circular reference risk without MaxDepth / PreserveReferences (AM022)
• invalid, null-unsafe, or unused type converters (AM030 / AM032 / AM033)
• expensive or multi-enumeration mapping expressions (AM031 / AM034–AM038)
• duplicate registrations, redundant MapFrom, and unregistered Map/ProjectTo pairs (AM041 / AM050 / AM060)
• enum member name/value misalignment that silently corrupts mapped data (AM061)

When the analyzer cannot prove a mapping shape statically, it stays quiet. High-signal feedback, not noisy guesses. Code fixes are withheld when a rewrite would be side-effecting, incomplete, or behavior-changing without review.

Install

<PackageReference Include="AutoMapperAnalyzer.Analyzers" Version="2.30.99">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

Or:

dotnet add package AutoMapperAnalyzer.Analyzers --version 2.30.99

No runtime dependency is added to your app. The package is a development-time Roslyn analyzer (plus code fixes). Open any file with AutoMapper configuration and diagnostics appear in supported IDEs and dotnet build.

See the compatibility contract for verified target-framework and AutoMapper version pairings.

See it work

Product-flow diagrams from real sample diagnostics (tests/.../sample-diagnostics.json):

1. Build / IDE diagnostics (CreateMap validation)

2. Before / after code fix (property type mismatch)

3. IDE + CI product loop

30-second path

1. Reference the package with PrivateAssets="all".
2. Keep your existing profiles, for example:

public class UserProfile : Profile
{
    public UserProfile()
    {
        CreateMap<User, UserDto>();
    }
}

3. Build in the IDE or with ContinuousIntegrationBuild=true on the command line so analyzers run under this repo’s local defaults.
4. Fix any AMxxx diagnostics (most rules offer code fixes; review scaffold / likely-rewrite actions).
5. Optionally open the samples project to see the full rule set in one place:

dotnet build samples/AutoMapperAnalyzer.Samples

Feature snapshot

Compatibility

Analyzer targets .NET Standard 2.0. Matrix details: docs/COMPATIBILITY.md.

Latest Release: v2.30.99

AM060 scopes open-generic registrations to compatible mapping pairs

• An open-generic registration such as CreateMap(typeof(Wrapper<>), typeof(Destination)) no longer suppresses AM060 for an unrelated Source → Destination mapping call.
• Compatible constructed pairs such as Wrapper<int> → Destination remain quiet, and generic registration helpers still fail closed when their source/destination shapes cannot be bounded.
• ReverseMap() retains the swapped open-generic direction, while partially dynamic CreateMap(Type, Type) calls still use whichever typeof operand is statically known.
• No rule ID or severity changes.

<details><summary>Previous release: verifiable build provenance (v2.30.94–95)</summary>

• Releases carry GitHub build provenance, so you can confirm the package was built by this repository's release workflow rather than trusting the uploader.

• Verify the asset attached to the GitHub release — NuGet.org repository-signs packages on upload, which changes the bytes, so the NuGet copy will not match the attestation:

  gh release download v2.30.95 --repo georgepwall1991/automapper-analyser --pattern "*.nupkg"
  gh attestation verify AutoMapperAnalyzer.Analyzers.2.30.95.nupkg --repo georgepwall1991/automapper-analyser
  

• No rule ID, severity, or diagnostic changes.

</details>

<details><summary>Previous release (v2.30.93)</summary>

Every diagnostic links to its documentation

• All 23 rules now set HelpLinkUri, so IDEs offer "learn more" on any AutoMapper diagnostic. None did before.
• Links open the rule's own section of the reference rather than the top of the document, and tests assert every anchor resolves to a real heading.
• No rule ID, severity, or diagnostic changes.

</details>

<details><summary>Previous release (v2.30.92)</summary>

Faster analysis on code unrelated to AutoMapper

• Every analyzer registers on every method invocation in a compilation, so the shared AutoMapper-method check ran symbol binding for calls that could not match by name. It now compares the invoked name syntactically first.
• Shapes whose name cannot be read still resolve semantically, so the gate can only skip work and never changes a diagnostic. Measured against a new throughput baseline: directionally ~12% lower analysis time on mostly-unrelated code.
• No rule ID, severity, or diagnostic changes.

</details>

Recent highlights

• v2.30.99: AM060 scopes unresolved open-generic registrations to mapping pairs they could cover.
• v2.30.98: AM041 respects mutually exclusive switch sections in direct MapperConfiguration lambdas.
• v2.30.97: AM011 reports required members that an included child map explicitly ignores.
• v2.30.96: Faster analysis of profiles with long fluent chains.
• v2.30.95: Corrects the provenance verification command — verify the GitHub release asset, not the NuGet download.
• v2.30.94: The published package carries verifiable build provenance.
• v2.30.93: Every diagnostic now links to its documentation section — IDEs offer "learn more" on all 23 rules.
• v2.30.92: Faster analysis on code unrelated to AutoMapper — the shared AutoMapper-method check no longer binds symbols for invocations that cannot match.
• v2.30.91: AM041 no longer reports registrations in separate MapperConfiguration instances as duplicates.
• v2.30.90: Severity presets (Minimal/Recommended) for brownfield adoption.
• v2.30.89: AutoMapper 15 and 16 added to the verified compatibility contract.
• v2.30.88: IncludeMembers awareness — AM004, AM006, and AM011 no longer report members supplied by an included source member.
• v2.30.87: Discoverability assets (metadata, funnel README, product-flow SVGs, pack verify).
• v2.30.86: AM020 capture-once computed receivers for nested-map fixes.
• v2.30.85: AM021 withholds ineffective element-map fixes for nested collection/array shapes.
• v2.30.84: AM060 unregistered Map/ProjectTo; AM061 enum member mismatch.
• v2.30.62: Performance rules split into AM031 + AM034–AM038.

Full history: CHANGELOG.md.

Complete Analyzer Coverage

Example: one CreateMap, many issues

public class UserEntity
{
    public int Id { get; set; }
    public string? FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime CreatedAt { get; set; }
    public List<string> Tags { get; set; }
    public Address HomeAddress { get; set; }
}

public class UserDto
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string FullName { get; set; }
    public string Age { get; set; }
    public HashSet<int> Tags { get; set; }
    public AddressDto HomeAddress { get; set; }
}

cfg.CreateMap<UserEntity, UserDto>();
// AM002: FirstName nullable → non-nullable
// AM001 / related: type and shape mismatches on Age / Tags
// AM020: HomeAddress → AddressDto needs its own CreateMap
// AM006 / AM004 family: unmapped / missing members depending on direction

Code fixes can suggest ForMember conversions, Ignore, nested CreateMap, and aggregate map/ignore actions when safe enough to propose. Always review scaffold-level fixes.

Severity and suppression

Adopting in an existing codebase

Turning 23 rules on across a large solution at once is the fastest way to get the package uninstalled. Five rules default to error (AM001, AM002, AM003, AM011, AM030), so a first dotnet add package on a mature codebase can break the build immediately.

Two presets ship inside the package so you do not have to hand-write 23 severities:

If you build with TreatWarningsAsErrors, warnings are promoted to errors by your build settings, independently of any analyzer configuration — no preset can override that. Minimal documents a ready-made WarningsNotAsErrors list covering exactly the rules it sets to warning; copy it from the top of the file.

AM002 is deliberately absent from Recommended. A severity setting is keyed by rule ID, but AM002 ships two descriptors at different severities (nullable-to-non-nullable as Error, non-nullable-to-nullable as Info). One ID-level override would apply to both and silently promote the informational one, failing builds on string → string? mappings that are safe today. Leaving it out preserves its shipped per-descriptor behaviour. Minimal sets it to suggestion, which removes the build-breaking descriptor without promoting the informational one.

Reference one from your project file:

<ItemGroup>
  <PackageReference Include="AutoMapperAnalyzer.Analyzers" Version="2.30.99"
                    PrivateAssets="all" GeneratePathProperty="true" />
  <GlobalAnalyzerConfigFiles
    Include="$(PkgAutoMapperAnalyzer_Analyzers)\config\AutoMapperAnalyzer.Minimal.globalconfig" />
</ItemGroup>

GeneratePathProperty="true" is what makes $(PkgAutoMapperAnalyzer_Analyzers) available. If you would rather not depend on that, open either file in the package and copy its lines into your .editorconfig — the presets are plain severity settings with no magic.

A workable ramp: start on Minimal, fix the warnings that matter to you, then switch to Recommended and raise individual rules back to error as your codebase catches up.

.editorconfig

dotnet_diagnostic.AM001.severity = error
dotnet_diagnostic.AM002.severity = error
dotnet_diagnostic.AM011.severity = error

dotnet_diagnostic.AM004.severity = warning
dotnet_diagnostic.AM005.severity = warning

dotnet_diagnostic.AM020.severity = suggestion
dotnet_diagnostic.AM021.severity = suggestion

Selective suppression

#pragma warning disable AM001 // Custom IValueConverter handles string→int
cfg.CreateMap<Source, Dest>();
#pragma warning restore AM001

[SuppressMessage("AutoMapper", "AM004:Missing destination property",
    Justification = "PII data intentionally excluded for GDPR compliance")]
public void ConfigureSafeUserMapping() { }

Development experience

• Visual Studio / Rider / VS Code (OmniSharp): diagnostics and lightbulb code fixes
• CLI: dotnet build (this repo disables analyzers on local CLI builds unless ContinuousIntegrationBuild=true)
• Samples: dotnet build samples/AutoMapperAnalyzer.Samples
• Tests: dotnet test

CI / quality

• Multi-TFM test suite and package compatibility matrix
• Catalog, sample diagnostic snapshots, and package content verification
• Codecov coverage reporting

Architecture notes

• Incremental Roslyn analysis with minimal IDE impact
• Central rule catalog for descriptors, fixers, samples, and fix-trust levels
• Cross-platform behavior on Windows, macOS, and Linux
• Conservative fix selection: no silent no-op lightbulbs; withhold when ownership cannot be proven

Contributing

git clone https://github.com/georgepwall1991/automapper-analyser.git
cd automapper-analyser
dotnet test

Useful contributions: edge-case scenarios, documentation, performance, and carefully scoped new rules.

Deep dive

• Architecture Guide
• Diagnostic Rules
• Generated Rule Catalog
• Sample Gallery
• CI/CD Pipeline
• Compatibility Matrix
• CHANGELOG

Community

• Issues
• Discussions

License

MIT — see LICENSE.