abp/docs/en/framework/infrastructure/luckypenny-automapper.md

//[doc-seo]
{
    "Description": "Learn how to use the Volo.Abp.LuckyPenny.AutoMapper package to integrate the commercial AutoMapper (LuckyPenny) with ABP Framework."
}

LuckyPenny AutoMapper Integration

Introduction

AutoMapper became a commercial product starting from version 15.x. The free open-source version (14.x) contains a security vulnerability (GHSA-rvv3-g6hj-g44x) — a DoS (Denial of Service) vulnerability — and no patch will be released for the 14.x series. The patched version is only available in the commercial editions (15.x and later).

The existing Volo.Abp.AutoMapper package uses AutoMapper 14.x and remains available for existing users. If you hold a valid LuckyPenny AutoMapper commercial license, the Volo.Abp.LuckyPenny.AutoMapper package provides the same ABP AutoMapper integration built on the patched commercial version.

If you don't need to use AutoMapper, you can migrate to Mapperly, which is free and open-source. See the AutoMapper to Mapperly migration guide.

Installation

Install the Volo.Abp.LuckyPenny.AutoMapper NuGet package to your project:

dotnet add package Volo.Abp.LuckyPenny.AutoMapper

Then add AbpLuckyPennyAutoMapperModule to your module's [DependsOn] attribute, replacing the existing AbpAutoMapperModule:

[DependsOn(typeof(AbpLuckyPennyAutoMapperModule))]
public class MyModule : AbpModule
{
    // ...
}

Note: Volo.Abp.LuckyPenny.AutoMapper and Volo.Abp.AutoMapper should not be used together in the same application. They are mutually exclusive — choose one or the other.

Usage

Volo.Abp.LuckyPenny.AutoMapper is a drop-in replacement for Volo.Abp.AutoMapper. All the same APIs, options, and extension methods are available. Refer to the AutoMapper Integration section of the Object to Object Mapping documentation for full usage details.

The only difference from a user perspective is the module class name:

	Package	Module class
Free (14.x, has security vulnerability)	Volo.Abp.AutoMapper	AbpAutoMapperModule
Commercial (patched)	Volo.Abp.LuckyPenny.AutoMapper	AbpLuckyPennyAutoMapperModule

License Configuration

The commercial AutoMapper uses an honor-system license. Without a configured key, everything works normally but a warning is written to the logs under the LuckyPennySoftware.AutoMapper.License category. To configure your license key, use AbpAutoMapperOptions.Configurators:

[DependsOn(typeof(AbpLuckyPennyAutoMapperModule))]
public class MyModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpAutoMapperOptions>(options =>
        {
            options.Configurators.Add(ctx =>
            {
                ctx.MapperConfiguration.LicenseKey = "YOUR_LICENSE_KEY";
            });
        });
    }
}

It is recommended to read the key from configuration rather than hardcoding it:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var licenseKey = context.Configuration["AutoMapper:LicenseKey"];

    Configure<AbpAutoMapperOptions>(options =>
    {
        options.Configurators.Add(ctx =>
        {
            ctx.MapperConfiguration.LicenseKey = licenseKey;
        });
    });
}

{
  "AutoMapper": {
    "LicenseKey": "YOUR_LICENSE_KEY"
  }
}

To suppress the license warning in non-production environments (e.g. unit tests or local development), filter the log category in Program.cs:

builder.Logging.AddFilter("LuckyPennySoftware.AutoMapper.License", LogLevel.None);

Or in appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "LuckyPennySoftware.AutoMapper.License": "None"
    }
  }
}

Client-side applications (Blazor WebAssembly, MAUI, WPF, etc.) should not set the license key to avoid exposing it on the client. Use the log filter above to silence the warning instead.

Obtaining a License

AutoMapper offers a free Community License and several paid plans.

Community License (Free)

A free license is available to organizations that meet all of the following criteria:

• Annual gross revenue under $5,000,000 USD
• Never received more than $10,000,000 USD in outside capital (private equity or venture capital)
• Registered non-profits with an annual budget under $5,000,000 USD also qualify

Government and quasi-government agencies do not qualify for the Community License.

Register for the Community License at: https://luckypennysoftware.com/community

Paid Plans

For organizations that do not meet the Community License criteria, paid plans are available at https://luckypennysoftware.com/purchase. For questions, contact sales@luckypennysoftware.com.

Migration from Volo.Abp.AutoMapper

To migrate an existing project from Volo.Abp.AutoMapper to Volo.Abp.LuckyPenny.AutoMapper:

1. Replace the NuGet package reference in all *.csproj files:

   -<PackageReference Include="Volo.Abp.AutoMapper" />
   +<PackageReference Include="Volo.Abp.LuckyPenny.AutoMapper" />
   

2. Replace the module dependency in all *.cs files:

   -[DependsOn(typeof(AbpAutoMapperModule))]
   +[DependsOn(typeof(AbpLuckyPennyAutoMapperModule))]
   

3. No other code changes are required. All types (AbpAutoMapperOptions, IMapperAccessor, AutoMapperExpressionExtensions, etc.) remain in the same namespaces.