MapsterChecker

A Roslyn analyzer that performs static analysis on Mapster.Adapt method calls to detect type compatibility issues at build time, with a focus on nullable to non-nullable type mapping violations.

Overview

MapsterChecker helps prevent runtime null reference exceptions by analyzing your Mapster mapping calls during compilation. It identifies potentially dangerous mappings where nullable types are mapped to non-nullable types, as well as fundamentally incompatible type mappings.

Features

• MAPSTER001: Detects nullable to non-nullable mappings that may cause null reference exceptions
• MAPSTER002: Identifies incompatible type mappings that cannot be converted
• MAPSTER003: Reports missing property mappings (future feature)
• Build-time analysis: Catches issues during compilation, not at runtime
• IDE integration: Real-time feedback in Visual Studio, VS Code, and JetBrains Rider
• Configurable: Customize rule severity and behavior via EditorConfig

Installation

Via NuGet Package Manager

dotnet add package MapsterChecker.Analyzer

Via Package Manager Console

Install-Package MapsterChecker.Analyzer

Via PackageReference

<PackageReference Include="MapsterChecker.Analyzer" Version="1.0.1"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>

Diagnostic Rules

MAPSTER001: Nullable to Non-Nullable Mapping

Severity: Warning
Category: MapsterChecker.Nullability

Detects when mapping from a nullable type to a non-nullable type, which may result in null reference exceptions.

Examples

// ⚠️ MAPSTER001: Warning string? nullableString = GetNullableString(); var result = nullableString.Adapt<string>(); // May throw if nullableString is null // ⚠️ MAPSTER001: Warning int? nullableInt = GetNullableInt(); var number = nullableInt.Adapt<int>(); // May throw if nullableInt is null // ✅ Safe: Non-nullable to nullable string nonNullableString = "test"; var result = nonNullableString.Adapt<string?>(); // Safe conversion

MAPSTER002: Incompatible Type Mapping

Severity: Error
Category: MapsterChecker.Compatibility

Detects when attempting to map between fundamentally incompatible types that cannot be converted.

Examples

// ❌ MAPSTER002: Error int number = 42; var dateTime = number.Adapt<DateTime>(); // Incompatible types // ❌ MAPSTER002: Error string text = "hello"; var guid = text.Adapt<Guid>(); // Cannot convert arbitrary string to Guid // ✅ Safe: Compatible numeric types int number = 42; long longNumber = number.Adapt<long>(); // Valid widening conversion

MAPSTER003: Missing Property Mapping (Future)

Severity: Info
Category: MapsterChecker.Mapping

Will detect when destination type contains properties not present in the source type.

Configuration

EditorConfig

You can configure rule severity in your .editorconfig file:

[*.cs] # Set MAPSTER001 to error instead of warning dotnet_diagnostic.MAPSTER001.severity = error # Disable MAPSTER002 completely dotnet_diagnostic.MAPSTER002.severity = none # Set MAPSTER003 to suggestion dotnet_diagnostic.MAPSTER003.severity = suggestion

Suppression

You can suppress specific diagnostics using standard C# suppression methods:

// Suppress via pragma #pragma warning disable MAPSTER001 var result = nullableString.Adapt<string>(); #pragma warning restore MAPSTER001 // Suppress via attribute [SuppressMessage("MapsterChecker", "MAPSTER001")] public string ConvertToString(string? input) => input.Adapt<string>();

Supported Mapster Patterns

MapsterChecker analyzes the following Mapster usage patterns:

Generic Adapt Method

var destination = source.Adapt<DestinationType>();

Non-Generic Adapt Method

var destination = new DestinationType(); source.Adapt(destination);

Extension Method Usage

using Mapster; var result = sourceObject.Adapt<TargetType>();

Type Compatibility Rules

Nullable Analysis

• string? → string: ⚠️ MAPSTER001 (Warning)
• string → string?: ✅ Safe
• int? → int: ⚠️ MAPSTER001 (Warning)
• int → int?: ✅ Safe

Numeric Type Compatibility

• int → long: ✅ Safe (widening conversion)
• float → double: ✅ Safe (widening conversion)
• long → int: ⚠️ Potential data loss (but allowed by Mapster)
• string → int: ❌ MAPSTER002 (Incompatible)

Reference Type Compatibility

• Inheritance hierarchy: ✅ Safe (base ↔ derived)
• Interface to concrete: ✅ Safe (with runtime validation)
• Unrelated types: ❌ MAPSTER002 (Incompatible)

Collection Compatibility

• List<T> → IEnumerable<U>: Checks T → U compatibility
• T[] → List<U>: Checks T → U compatibility
• Collections with incompatible element types: ❌ MAPSTER002

Building from Source

Prerequisites

• .NET 9.0 or .NET 10.0 SDK
• Visual Studio 2022 or JetBrains Rider (optional)

Build Steps

# Clone the repository git clone https://github.com/mapsterchecker/mapsterchecker.git cd mapsterchecker # Restore dependencies dotnet restore # Build the solution dotnet build # Run tests dotnet test # Create NuGet package dotnet pack --configuration Release

Sample Application

The repository includes a sample application demonstrating various mapping scenarios:

cd samples/SampleApp dotnet build # This will show analyzer warnings/errors dotnet run # Run the sample application

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add unit tests for new features
• Update documentation for user-facing changes
• Ensure all tests pass before submitting PR

Performance

MapsterChecker is designed to be fast and responsive:

• < 50ms per file: Average analysis time
• Concurrent execution: Leverages Roslyn's concurrent analysis capabilities
• Syntax-first filtering: Quick rejection of non-Adapt method calls
• Semantic analysis caching: Efficient type symbol lookups

Limitations

• Mapster-specific: Only analyzes Mapster.Adapt calls, not other mapping libraries
• Static analysis only: Cannot detect runtime configuration-based mappings
• Conservative approach: May report false positives for complex scenarios
• Configuration mapping: Does not analyze custom Mapster configuration rules

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Mapster - The object-to-object mapper this analyzer supports
• Roslyn - The .NET Compiler Platform that makes this analyzer possible
• Microsoft.CodeAnalysis.Testing - Testing framework for analyzers

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact