AutoMapperAnalyzer.Analyzers 2.30.88

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.88">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

Or:

dotnet add package AutoMapperAnalyzer.Analyzers --version 2.30.88

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.88

IncludeMembers awareness for AM004, AM006, and AM011

• Fixes an Error-severity AM011 false positive: a required destination property supplied by an IncludeMembers(...) member was reported as unmapped, breaking builds that use a documented AutoMapper feature.
• AM004 no longer reports a source member consumed by IncludeMembers(...) as data loss, and AM006 recognises destination members supplied by an included member.
• Stays conservative: only the final IncludeMembers call is effective (matching AutoMapper's replace-on-call behaviour), an explicit ForMember(... MapFrom(...)) on the included child map counts as supplying the member, and only plain member-access selectors are interpreted — anything else suppresses rather than guesses. Boundaries are documented in docs/TEST_LIMITATIONS.md.
• No analyzer rule ID or severity changes.

Recent highlights

• 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

.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.