Chd.Mapping.Roslyn.Advanced 8.0.1

Chd.Mapping.Roslyn – A Modern, High-Performance Source Generator for .NET Mapping

What is Chd.Mapping.Roslyn?

Chd.Mapping.Roslyn is a modern, compile-time object mapper for .NET, built with Roslyn source generators. It automatically creates fast, type-safe, and debuggable mapping code between DTOs and entities during your build process – eliminating runtime reflection, configuration headaches, and mapping errors typical of tools like AutoMapper or Mapster.

Why Choose Compile-time Mapping over Runtime Mapping Libraries?

1. Performance

• No Reflection: All mapping logic is generated at build time. There is no runtime cost of reflection or emitted dynamic code.
• Inlining: The compiler can inline mapping logic for maximum speed.
• Benchmarks: Compile-time mapping is consistently 2x to 5x faster than runtime mappers (see below).

2. Type Safety

• Compile-time Validation: All mapping is verified at build – if your DTO or entity changes, mapping errors become compiler errors, not runtime threats.
• Refactoring-Proof: Rename properties, types, or restructure classes freely; the generator always produces matching code.

3. Debuggability

• See the Code! All generated mapping code is standard C#, fully visible in your IDE – you can set breakpoints, watch variables, and step through mappings with the debugger.
• No Magic: No hidden configuration, reflection voodoo, or runtime exceptions.

4. Simplicity

• Usage is trivial: Just add mapping attributes, build, and use generated code.
• No configuration files, dependency injection, or startup scanning required.

How Does It Work? Detailed Example

1. Install NuGet Package

Install-Package Chd.Mapping.Roslyn

2. Use Mapping Attributes

Place an attribute on your DTO declaring which entity it maps to:

using Chd.Mapping.Roslyn;

[MapTo(typeof(UserEntity))]
public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public partial class UserEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
}

• Note: Entities and DTOs must be partial classes so that generated code can extend them.

3. Enjoy Generated Implicit Conversion Operators

The source generator automatically creates:

• DTO → Entity mapping operator
• Entity → DTO mapping operator

So you can write:

UserEntity entity = dto;     // Implicit mapping
UserDto dto2 = entity;       // Implicit reverse mapping

Or call extension methods for explicit conversion:

var entity = dto.MapTo<UserEntity>();
var dto2 = entity.MapTo<UserDto>();

4. Debugging is First-Class

• All generated mapping code is standard C#, located in /obj or /Generated folders.
• See the actual logic:

  // Example generated code
  public static implicit operator UserEntity(UserDto dto)
  {
      if (dto == null) return null;
      return new UserEntity
      {
          Id = dto.Id,
          Name = dto.Name
      };
  }
  

• Place breakpoints, watch values, step into each property mapping:

  UserEntity entity = dto; // You can F11 into the mapped operator!
  

5. No Reflection, No Surprises

• Unlike AutoMapper/Mapster, no runtime scanning, no runtime configuration, no chance of mapping being missed.
• All logic is generated. If your build passes, so will your mapping at runtime.

Feature Comparison Table

Real-World .NET Performance Benchmarks

Source: Internal benchmarks in /benchmarks, inspired by Ben Day’s Mapping Performance Comparison.

Key Takeaway:
Roslyn source generator mapping is orders of magnitude faster, almost as fast as hand-written code or hand-coded implicit operators – and much faster than AutoMapper or Mapster!

Installation & Integration Tips

• One NuGet install: No config files, no Fody, no IL weaving headaches.
• Ensure all mapped classes are partial.
• After build, mappings become instantly available.
• Compatible with all SDK-style .NET projects – Core, Framework, etc.
• No runtime dependency: shipping just your compiled assembly is enough.

⚠️ What End-Users Need to Pay Attention To

1. Partial Classes are Mandatory

• Both your DTO and Entity classes must be marked partial:

  public partial class UserDto { ... }
  public partial class UserEntity { ... }
  

• Otherwise, the source generator cannot inject mapping operators and you will not see mapping code after build.

2. Use the Mapping Attribute on DTOs

• On your DTO, use the [MapTo(typeof(EntityType))] attribute to declare the mapping target.
• No attribute is required on your Entity; only the DTO "owns" mapping metadata.

3. SDK-Style Project Structure Required

• Chd.Mapping.Roslyn (and all Roslyn source generators) require an SDK-style .csproj – classic .NET Framework projects will not work.
• Compatible with .NET Core 3.1+, .NET 5+, .NET 6+, .NET 7+.

4. Always Build (not just save)

• Mapping code is only generated on build.
• You must perform a full “Build” or “Rebuild” to see mapping operators, extension methods, and generated sources.
• If code isn’t showing, try “Clean” then “Rebuild.”

5. No Fody, No XML Config, No Manual Mapping Setup Needed

• You do not need Fody, FodyWeavers.xml, or any config file.
• No startup code or dependency injection needed.

6. NuGet Package Must Be Up-to-Date

• Keep your Chd.Mapping.Roslyn NuGet package updated – source generator bugs/limitations are addressed in new releases.
• Outdated packages may not work reliably with the latest .NET SDK.

7. Mapping Visible Under /obj or /Generated

• Generated code appears in your IDE (e.g., VS “Solution Explorer” under “Analyzers” or /obj/Debug/netX/Generated).
• If it doesn’t, check the above steps, especially that classes are partial and you’ve built the project.

8. Troubleshooting: Most Common Issues

• Mapping operators/extensions not found:
  • Are your mapped classes partial?
  • Have you performed a full build/rebuild?
  • Is your project SDK-style?
  • Is the mapping attribute present on the DTO?
• Intellisense not updating:
  • Try cleaning and rebuilding; sometimes IDEs cache old generated code.
• Not working in old .NET Framework:
  • Only modern .NET projects are supported.

9. No Extra Config Needed

• If you follow the steps above, mapping is fully automatic:
  • Write your DTO with [MapTo(...)] and make both classes partial
  • Build the project
  • Use mapping operators and extension methods immediately

Usage Example (after setup)

var dto = new UserDto { Id = 1, Name = "Alice" };
UserEntity entity = dto;                    // Implicit mapping, automatically generated
UserDto dto2 = entity;                      // Implicit reverse mapping
var entity2 = dto.MapTo<UserEntity>();      // Extension method mapping

CI/CD & Artefacts

• Source-generated mapping code is tested via unit tests and on PR CI pipelines.
• No runtime dependency except standard .NET BCL.

Best Practices

• Keep your DTO and Entity property names and types synchronized for automatic mapping.
• For custom property names, use attributes (see above).
• Remove old/unused mapping attributes to avoid stale generated code.

Official-Quality, Practical Code Samples

Mapping Complex Classes:

[MapTo(typeof(ProductEntity))]
public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<CategoryDto> Categories { get; set; }
}

// Corresponding entity
public partial class ProductEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<CategoryEntity> Categories { get; set; }
}

Generated mapping automatically traverses nested lists and even supports inheritance if safe.

Advanced Scenarios Supported

• Nested mappings (DTOs containing other DTOs/entities)
• Collections (List<T>, arrays, IEnumerable<T>)
• Null-safe mapping
• Attribute-based customization for property name mismatches

Example:

[MapTo(typeof(UserEntity))]
public class UserDto
{
    public int Id { get; set; }
    [MapProperty("FullName")] // Maps DTO.Name → Entity.FullName
    public string Name { get; set; }
}

public partial class UserEntity
{
    public int Id { get; set; }
    public string FullName { get; set; }
}

Installation & Integration Tips

• One NuGet install: No config files, no Fody, no IL weaving headaches.
• Ensure all mapped classes are partial.
• After build, mappings become instantly available.
• Compatible with all SDK-style .NET projects – Core, Framework, etc.
• No runtime dependency: shipping just your compiled assembly is enough.

How to Test, Benchmark and Debug

• See /benchmarks/Mapping.Benchmark for full test suites & reproducible performance data.
• Use your favorite test runner: mapping code is just plain C#.
• All mappings checked on every PR via CI.

Best Articles & External Performance References

• Entity to DTO – AutoMapper vs. Explicit Mapping vs. Implicit Operators (Ben Day)
  • Presents measured speed: implicit operators and hand-written code are dramatically faster than dynamic mapping frameworks.
  • Great discussion on the value of compile-time type safety vs. runtime magic.
• Object Mapping in .NET – Compile-time vs. Runtime (Andrew Lock)
  • Explains Roslyn source generator mapping, with code samples and performance comparisons.

Authors & Credits

• Mehmet Yoldaş (mehmet-yoldas)
• Inspired by the .NET community, Roslyn, and a desire for ultra-fast, bug-proof mapping in real-world enterprise codebases.

Professional Summary

Chd.Mapping.Roslyn brings mapping speed, reliability, and maintainability worthy of high-end .NET development shops.

• Immediate feedback on mapping errors
• Blazing speed: up to 7x faster than reflection-based mappers
• Readable, debuggable code
• No runtime overhead, no surprises

Upgrade your DTO ↔ Entity transformations now!

Appendix: Sample Generated Code (for Debugging)

// In auto-generated partial:
// UserDto → UserEntity
public static implicit operator UserEntity(UserDto dto)
{
    if (dto == null) return null;
    return new UserEntity
    {
        Id = dto.Id,
        Name = dto.Name
    };
}

// UserEntity → UserDto
public static implicit operator UserDto(UserEntity entity)
{
    if (entity == null) return null;
    return new UserDto
    {
        Id = entity.Id,
        Name = entity.Name
    };
}

You can always step through this code in your debugger!

Further Reading

• Source Generators in .NET 5+
• Roslyn Cookbook – Source Generator Recipes
• Approaches to Mapping in .NET

For feedback, improvements or open source contributions, see mehmet-yoldas/library-core.