Mapperly

https://mapperly.riok.app/docs
Admin
Mapperly is a .NET source generator that automatically generates high-performance, trimming-safe...
Tokens:57,614
Snippets:558
Trust Score:7.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Start local development server

Source: https://mapperly.riok.app/docs/contributing/docs/

Starts a local development server and opens a browser window. Most changes are reflected live without restarting. Note that documentation search does not work in this mode because it depends on statically built content.

```bash
npm run start
```

--------------------------------

### Install documentation dependencies with npm i

Source: https://mapperly.riok.app/docs/contributing/docs/

Run this command in the docs directory to install all required npm packages. Ensure your node version matches the one specified in the .node-version file.

```bash
npm i
```

--------------------------------

### Mapper usage example

Source: https://mapperly.riok.app/docs/getting-started/first-mapper/

Instantiates the CarMapper and calls CarToCarDto to map a Car object to a CarDto. The example asserts that the NumberOfSeats property is mapped correctly.

```csharp
var mapper = new CarMapper();
var car = new Car { NumberOfSeats = 10, ... };
var dto = mapper.CarToCarDto(car);
dto.NumberOfSeats.ShouldBe(10);
```

--------------------------------

### Install Riok.Mapperly with Package Manager Console

Source: https://mapperly.riok.app/docs/getting-started/installation/

PowerShell command to install the Riok.Mapperly package via the NuGet Package Manager Console. After installation, you may need to add ExcludeAssets="runtime" and PrivateAssets="all" to the resulting PackageReference to remove the runtime dependency.

```powershell
Install-Package Riok.Mapperly
```

--------------------------------

### External instance method classes

Source: https://mapperly.riok.app/docs/configuration/external-mappings/

The external classes referenced by the instance external method examples. PriceMapper is an instance class and SourceSystems is static.

```csharp
public class PriceMapper
{
    public string MapPrice(decimal price)
    => (price / 100).ToString("C");

    public string MapPriceFromSource(Car source)
    => (source.Price / 100).ToString("C");
}

public static class SourceSystems
{
    public static string GetSourceSystem() => "C1";
}
```

--------------------------------

### Name Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.includemappingconfigurationattribute/

Gets the name of the mapping configuration to include.

```APIDOC
## Name Property

### Description
Gets the name of the mapping configuration to include.

### Property Signature
`public string Name { get; }`

### Property Value
- Type: string
- Description: The name of the mapping configuration to include.
```

--------------------------------

### Install Riok.Mapperly with .NET CLI

Source: https://mapperly.riok.app/docs/getting-started/installation/

Command to add the Riok.Mapperly package using the .NET CLI. After running, you may need to add ExcludeAssets="runtime" and PrivateAssets="all" to the resulting PackageReference to remove the runtime dependency.

```bash
dotnet add package Riok.Mapperly
```

--------------------------------

### Squash commits with interactive rebase

Source: https://mapperly.riok.app/docs/contributing/

Starts an interactive rebase against main to squash smaller commits into larger, cohesive ones. The 'git checkout' command is incomplete in the source; ensure you are on the correct branch before running the rebase.

```bash
# Rebase all commits on your development branch
git checkout
git rebase -i main
```

--------------------------------

### Mapper declaration with MemberVisibility.All

Source: https://mapperly.riok.app/docs/configuration/private-members/

Configure Mapperly to map all members and constructors, including inaccessible ones, by setting IncludedMembers and IncludedConstructors to MemberVisibility.All. The example defines a FruitMapper, Fruit, and FruitDto classes.

```csharp
[Mapper(
    IncludedMembers = MemberVisibility.All,
    IncludedConstructors = MemberVisibility.All)]
public partial class FruitMapper
{
    public partial FruitDto ToDto(Fruit source);
}

public class Fruit
{
  private bool _isSeeded;

  public string Name { get; set; }

  private int Sweetness { get; set; }
}

public class FruitDto
{
  private FruitDto() {}

  private bool _isSeeded;

  public string Name { get; set; }

  private int Sweetness { get; set; }
}
```

--------------------------------

### Generic object factory example

Source: https://mapperly.riok.app/docs/configuration/object-factories/

Shows two generic object factories: one with a type constraint (T : CarDto) and one without. Both are parameterless and have exactly one type parameter that is also the return type. The first creates instances of CarDto and its subclasses, the second resolves any type from a DI container.

```csharp
[Mapper]
public partial class CarMapper
{
    // an object factory which will create instances of CarDto and all it's subclasses
    [ObjectFactory]
    private T CreateCar<T>()
        where T : CarDto
        => CarDto.CreateFromCustomMethod();

    // or an object factory which will create objects for all types
    [ObjectFactory]
    private T Create<T>()
        => _diContainer.Resolve<T>();

    public partial CarDto CarToCarDto(Car car);
}
```

--------------------------------

### Basic object factory example

Source: https://mapperly.riok.app/docs/configuration/object-factories/

Shows a mapper class with an object factory method annotated with [ObjectFactory]. The factory method returns a CarDto and is used by the mapping method CarToCarDto. Note that when an object factory is used for a type, Mapperly cannot map to init-only properties or constructor parameters.

```csharp
[Mapper]
public partial class CarMapper
{
    [ObjectFactory]
    private CarDto CreateCarDto()
        => CarDto.CreateFromCustomMethod();

    public partial CarDto CarToCarDto(Car car);
}
```

```csharp
public partial class CarMapper
{
    public partial CarDto CarToCarDto(Car car)
    {
        var target = CreateCarDto();
        // map all properties...
        return target;
    }
}
```

--------------------------------

### MapProperty with Use and AutoUserMappings disabled

Source: https://mapperly.riok.app/docs/configuration/mapper/

Shows the same mapping as the previous example but with AutoUserMappings = false on the Mapper attribute. In this case, the UserMapping attribute is not needed. The generated code is shown in a comment.

```csharp
[Mapper(AutoUserMappings = false)]
public partial class CarMapper
{
    [MapProperty(nameof(Car.Price), nameof(CarDto.Price), Use = nameof(MapPrice))]
    public partial CarDto MapCar(Car source);

    private string MapPrice(decimal price)
        => (price / 100).ToString("C");

    // generates
    target.Price = MapPrice(source.Price);
}
```

--------------------------------

### Enable only specific automatic conversions (Constructor and ExplicitCast)

Source: https://mapperly.riok.app/docs/configuration/conversions/

Set EnabledConversions to a bitwise OR of the desired conversion types. This example enables only Constructor and ExplicitCast conversions, disabling ToString() which is enabled by default.

```csharp
// This disables conversions using the ToString() method, which is enabled by default:
[Mapper(EnabledConversions = MappingConversionType.Constructor | MappingConversionType.ExplicitCast)]
public partial class CarMapper
{
  ...
}
```

--------------------------------

### Source classes: Car, CarColor, Manufacturer, Tire

Source: https://mapperly.riok.app/docs/getting-started/generated-mapper-example/

Defines the source model for the Mapperly example. Car includes a Manufacturer property and a list of Tires. CarColor enum uses values Black=1, Blue=2, White=3. Manufacturer has a constructor with id and name.

```csharp
namespace Riok.Mapperly.Sample;

public class Car
{
    public string Name { get; set; } = string.Empty;

    public int NumberOfSeats { get; set; }

    public CarColor Color { get; set; }

    public Manufacturer? Manufacturer { get; set; }

    public List<Tire> Tires { get; } = [];
}

public enum CarColor
{
    Black = 1,
    Blue = 2,
    White = 3,
}

public class Manufacturer
{
    public Manufacturer(int id, string name)
    {
        Id = id;
        Name = name;
    }

    public int Id { get; }

    public string Name { get; }
}

public class Tire
{
    public string Description { get; set; } = string.Empty;
}
```

--------------------------------

### Generated mapping method with no members mapped (C#)

Source: https://mapperly.riok.app/docs/configuration/analyzer-diagnostics/RMG066/

Example of the generated implementation part of a mapping method that triggers RMG066. The method creates a new Target instance but does not map any members from Source, which is usually not expected.

```csharp
public partial Target Map(Source source)
{
    var target = new Target();
    return target;
}
```

--------------------------------

### MapValueAttribute.TargetFullName Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/

Gets the full name of the target property path.

```APIDOC
## TargetFullName Property

### Description
Gets the full name of the target property path.

### Definition
```csharp
public string TargetFullName { get; }
```

### Property Value
[String](https://docs.microsoft.com/en-us/dotnet/api/system.string)
```

--------------------------------

### External static method classes

Source: https://mapperly.riok.app/docs/configuration/external-mappings/

The external static classes referenced by the static external method examples. PriceMapper provides mapping methods and SourceSystems provides a source system value.

```csharp
namespace OtherNamespace;

public static class PriceMapper
{
    public static string MapPrice(decimal price)
    => (price / 100).ToString("C");

    public static string MapPriceFromSource(Car source)
    => (source.Price / 100).ToString("C");
}

public static class SourceSystems
{
    public static string GetSourceSystem() => "C1";
}
```

--------------------------------

### RequiredMappingStrategy Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperrequiredmappingattribute/

Gets the strategy used when emitting warnings for unmapped members.

```APIDOC
## RequiredMappingStrategy Property

### Description
Gets the strategy used when emitting warnings for unmapped members.

### Property Signature
`public RequiredMappingStrategy RequiredMappingStrategy { get; }`

### Property Value
Type: RequiredMappingStrategy

### Example
```csharp
var strategy = attribute.RequiredMappingStrategy;
```
```

--------------------------------

### Mapper with MemberVisibility.Private | Protected

Source: https://mapperly.riok.app/docs/configuration/private-members/

Control which members are considered by setting IncludedMembers to a combination of MemberVisibility flags. This example only maps private and protected members, generating unsafe accessors as needed.

```csharp
[Mapper(IncludedMembers = MemberVisibility.Private | MemberVisibility.Protected)]
public partial class FruitMapper
{
    public partial FruitDto ToDto(Fruit source);
}
```

--------------------------------

### UseMapper for instance external mappings

Source: https://mapperly.riok.app/docs/configuration/external-mappings/

Use UseMapper on a field or property to reference an instance of a mapper class. The example shows a BoxMapper with a private readonly BananaMapper field. The user must initialize the field or property.

```csharp
[Mapper]
public static partial class BoxMapper
{
    [UseMapper]
    private readonly BananaMapper _bananaMapper = new();

    public static partial BananaBox MapBananaBox(BananaBoxDto dto);
}

public static class BananaMapper
{
    public static Banana MapBanana(BananaDto dto)
    => new Banana(dto.Weight);
}
```

--------------------------------

### Target classes: CarDto, CarColorDto, ProducerDto, TireDto

Source: https://mapperly.riok.app/docs/getting-started/generated-mapper-example/

Defines the target DTO classes for the Mapperly example. CarDto uses CarColorDto, ProducerDto (instead of Manufacturer), and a nullable list of TireDto. CarColorDto intentionally uses different numeric values (Yellow=1, Green=2, Black=3, Blue=4) to demonstrate enum mapping.

```csharp
namespace Riok.Mapperly.Sample;

public class CarDto
{
    public string Name { get; set; } = string.Empty;

    public int NumberOfSeats { get; set; }

    public CarColorDto Color { get; set; }

    public ProducerDto? Producer { get; set; }

    public List<TireDto>? Tires { get; set; }
}

// Intentionally use different numeric values for demonstration purposes
public enum CarColorDto
{
    Yellow = 1,
    Green = 2,
    Black = 3,
    Blue = 4,
}

// The manufacturer, but named differently for demonstration purposes
public class ProducerDto
{
    public ProducerDto(int id, string name)
    {
        Id = id;
        Name = name;
    }

    public int Id { get; }

    public string Name { get; }
}

public class TireDto
{
    public string Description { get; set; } = string.Empty;
}
```

--------------------------------

### Ignore members with MapperIgnoreTarget and MapperIgnoreSource

Source: https://mapperly.riok.app/docs/configuration/mapper/

Use MapperIgnoreTarget and MapperIgnoreSource attributes on a mapping method to ignore specific source and target members. The example ignores CarDto.MakeId and Car.Id.

```csharp
[Mapper]
public partial class CarMapper
{
    [MapperIgnoreTarget(nameof(CarDto.MakeId))]
    [MapperIgnoreSource(nameof(Car.Id))]
    public partial CarDto ToDto(Car car);
}
```

--------------------------------

### Disable automatic user mapping discovery with AutoUserMappings=false

Source: https://mapperly.riok.app/docs/configuration/user-implemented-methods/

When AutoUserMappings is set to false, only methods marked with [UserMapping] are discovered. The example shows an ignored method that would otherwise be considered.

```csharp
[Mapper(AutoUserMappings = false)]
public partial class CarMapper
{
    public partial CarDto CarToCarDto(Car car);

    // mark as user-implemented mapping
    [UserMapping]
    private int TimeSpanToHours(TimeSpan t) => t.Hours;

    private int IgnoredTimeSpanToHours(TimeSpan t) => t.Minutes / 60;
}
```

--------------------------------

### Exclude conversion methods with MapperIgnore

Source: https://mapperly.riok.app/docs/configuration/mapper/

Annotate conversion methods with MapperIgnore to prevent them from being used in mappings. The example shows ignoring Parse and ToB while alternative methods are still considered.

```csharp
public class A
{
    // Prevents using Parse(string) in string -> A mappings
    [MapperIgnore]
    public static A Parse(string s) => new();

    // Alternative factory is still considered
    public static A Create(string s) => new();

    // Prevents using ToB() in A -> B mappings
    [MapperIgnore]
    public B ToB() => new();

    public B Convert() => new();
}
```

--------------------------------

### Use user-implemented mapping with ref keyword

Source: https://mapperly.riok.app/docs/configuration/user-implemented-methods/

Example of a Mapperly partial class with a method that uses a user-implemented mapping for a property. The Use property is required to prevent Mapperly from generating its own mapping. The ref keyword on the target parameter allows the reference to be updated in the caller.

```csharp
  [Mapper(AllowNullPropertyAssignment = false, UseDeepCloning = true, RequiredMappingStrategy = RequiredMappingStrategy.Source)]
  public static partial class UseUserMethodWithRef
  {
      [MapProperty(nameof(ArrayObject.IntArray), nameof(ArrayObject.IntArray), Use = nameof(MapArray))] // `Use` is required otherwise it will generate it's own
      public static partial void Merge([MappingTarget] ArrayObject target, ArrayObject second);

      private static void MapArray([MappingTarget] ref int[] target, int[] second) => target = [.. target, .. second.Except(target)];
  }
```

--------------------------------

### Case-insensitive property name mapping with PropertyNameMappingStrategy

Source: https://mapperly.riok.app/docs/configuration/mapper/

Set PropertyNameMappingStrategy to CaseInsensitive on the MapperAttribute to match properties that differ only in casing. The example maps ModelName to modelName.

```csharp
[Mapper(PropertyNameMappingStrategy = PropertyNameMappingStrategy.CaseInsensitive)]
public partial class CarMapper
{
    public partial CarDto ToDto(Car car);
}

public class Car
{
    public string ModelName { get; set; }
}

public class CarDto
{
    public string modelName { get; set; }
}
```

--------------------------------

### UseStaticMapper for static external mappings

Source: https://mapperly.riok.app/docs/configuration/external-mappings/

Use UseStaticMapper to reference a static class containing mapping methods. The example shows a BoxMapper that uses BananaMapper to map BananaDto to Banana.

```csharp
[Mapper]
[UseStaticMapper(typeof(BananaMapper))]
public static partial class BoxMapper
{
    public static partial BananaBox MapBananaBox(BananaBoxDto dto);
}

public static class BananaMapper
{
    public static Banana MapBanana(BananaDto dto)
    => new Banana(dto.Weight);
}
```

--------------------------------

### AutoUserMappings Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperattribute/

Gets or sets a value indicating whether to automatically discover user mapping methods based on their signature. When true, all partial methods and methods with an implementation body and a mapping method signature are discovered. When false, only partial methods and methods with a UserMappingAttribute are discovered.

```APIDOC
## AutoUserMappings Property

### Description
Gets or sets a value indicating whether to automatically discover user mapping methods based on their signature. When true, all partial methods and methods with an implementation body and a mapping method signature are discovered. When false, only partial methods and methods with a UserMappingAttribute are discovered.

### Property Signature
```csharp
public bool AutoUserMappings { get; set; }
```

### Property Value
- **Type**: Boolean
- **Description**: A boolean value indicating whether automatic discovery of user mapping methods is enabled.
```

--------------------------------

### Run prebuild script to generate documentation

Source: https://mapperly.riok.app/docs/contributing/docs/

Builds generated parts of the documentation such as API docs, analyzer rules table, and samples. Requires the dotnet solution to be built first. Re-run whenever the source of generated output changes.

```bash
npm run prebuild
```

--------------------------------

### Disable specific automatic conversion (ToStringMethod) with EnabledConversions = All & ~ToStringMethod

Source: https://mapperly.riok.app/docs/configuration/conversions/

Use bitwise complement to exclude a specific conversion type from the default All set. This example disables conversions using the ToString() method.

```csharp
// this disables conversions using the ToString() method:
[Mapper(EnabledConversions = MappingConversionType.All & ~MappingConversionType.ToStringMethod)]
public partial class CarMapper
{
  ...
}
```

--------------------------------

### MapperDefaultsAttribute.AutoUserMappings

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperdefaultsattribute/

Gets or sets a value indicating whether to automatically discover user mapping methods based on their signature. When true, all partial methods and methods with a mapping method signature are discovered; when false, only partial methods and methods with UserMappingAttribute are discovered.

```APIDOC
## AutoUserMappings

### Description
Gets or sets a value indicating whether to automatically discover user mapping methods based on their signature. When true, all partial methods and methods with a mapping method signature are discovered; when false, only partial methods and methods with UserMappingAttribute are discovered.

### Property Value
- **Type**: Boolean

### Remarks
To discover mappings in external mappers (UseMapperAttribute and UseStaticMapperAttribute) the same rules are applied: If set to true all methods with a mapping method signature are automatically discovered. If set to false methods with a UserMappingAttribute and if the containing class has a MapperAttribute partial methods are discovered.

### Code Example
```csharp
public bool AutoUserMappings { get; set; }
```
```

--------------------------------

### Build static documentation site

Source: https://mapperly.riok.app/docs/contributing/docs/

Generates static content into the build directory. The output can be served by any static hosting service or locally using npm run serve.

```bash
npm run build
```

--------------------------------

### Run all tests with dotnet test

Source: https://mapperly.riok.app/docs/contributing/tests/

Runs all unit and integration tests in the solution. Use this command from the repository root.

```bash
dotnet test
```

--------------------------------

### MapperDefaultsAttribute.TypeId

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperdefaultsattribute/

Gets the TypeId property of the MapperDefaultsAttribute.

```APIDOC
## TypeId

### Description
Gets the TypeId property of the MapperDefaultsAttribute.

### Property Value
- **Type**: Object

### Code Example
```csharp
public object TypeId { get; }
```
```

--------------------------------

### Use IQueryable projection with Entity Framework

Source: https://mapperly.riok.app/docs/configuration/queryable-projections/

Shows how to use the ProjectToDto method in a query with Entity Framework, retrieving only fields present in the target class.

```csharp
var dtos = await DbContext.Cars
    .Where(...)
    .ProjectToDto()
    .ToListAsync();
```

--------------------------------

### MapValueAttribute.Value Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/

Gets the value to be assigned to MapValueAttribute.Target.

```APIDOC
## Value Property

### Description
Gets the value to be assigned to [MapValueAttribute.Target](https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/#target).

### Definition
```csharp
public object Value { get; }
```

### Property Value
[Object](https://docs.microsoft.com/en-us/dotnet/api/system.object)
```

--------------------------------

### MapValueAttribute.Target Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/

Gets the name of the target property.

```APIDOC
## Target Property

### Description
Gets the name of the target property.

### Definition
```csharp
public IReadOnlyCollection<string> Target { get; }
```

### Property Value
[IReadOnlyCollection<String>](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ireadonlycollection-1)
```

--------------------------------

### Include mapping configuration from base class

Source: https://mapperly.riok.app/docs/configuration/reusing-mapping-configurations/

Shows a mapper that includes a private mapping method for base classes Fruit and FruitDto, and a public method that maps Apple to AppleDto using the base class configuration. The classes Fruit, FruitDto, Apple, and AppleDto are defined in the second block.

```csharp
[Mapper]
public partial class MyMapper
{
    [MapProperty(nameof(Fruit.Name), nameof(FruitDto.Title))]
    [MapperIgnoreSource(nameof(Fruit.PricePerUnit))]
    private partial FruitDto ToFruit(Fruit fruit);

    [IncludeMappingConfiguration(nameof(ToFruit))]
    public partial static AppleDto Map(Apple apple);
}
```

```csharp
class Fruit
{
    public string Name { get; set; }
    public decimal PricePerUnit { get; set; }
}

class FruitDto
{
public string Title { get; set; }
}

class Apple : Fruit
{
public int Weight { get; set; }
}

class AppleDto : FruitDto
{
public int Weight { get; set; }
}
```

--------------------------------

### User-implemented mapping method for ordering and aggregating collections

Source: https://mapperly.riok.app/docs/configuration/queryable-projections/

Shows a user-implemented mapping method that orders and selects a collection. Note the comment: do not use the method group '.Select(MapCarModel)' as that cannot be inlined.

```csharp
[Mapper]
public static partial class CarMapper
{
    public static partial IQueryable<CarDto> ProjectToDto(this IQueryable<Car> q);

    private static partial CarModelDto MapCarModel(CarModel model);

    private static ICollection<CarModelDto> MapOrderedCarBrandName(ICollection<CarModel> models)
      // note: do not use the method group '.Select(MapCarModel)', as that cannot be inlined
      => models.OrderBy(x => x.Name).Select(x => MapCarModel(x)).ToList();
  }
```

--------------------------------

### MapValueAttribute.TypeId Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/

Gets the TypeId property (inherited from Attribute).

```APIDOC
## TypeId Property

### Description
Gets the TypeId property (inherited from Attribute).

### Definition
```csharp
public object TypeId { get; }
```

### Property Value
[Object](https://docs.microsoft.com/en-us/dotnet/api/system.object)
```

--------------------------------

### ObjectFactoryAttribute.TypeId Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.objectfactoryattribute/

Gets the TypeId property inherited from System.Attribute.

```APIDOC
## ObjectFactoryAttribute.TypeId

### Description
Gets the TypeId property, which is inherited from System.Attribute.

### Property Signature
public object TypeId { get; }

### Property Value
- **TypeId** (object) - The type identifier for the attribute.
```

--------------------------------

### Include mapping configuration by method name

Source: https://mapperly.riok.app/docs/configuration/reusing-mapping-configurations/

Use IncludeMappingConfiguration with nameof to include configurations from an existing mapping method. The included configurations include MapProperty, MapPropertyFromSource, MapperIgnoreTarget, MapperIgnoreSource, MapperIgnoreObsoleteMembers, MapperRequiredMapping, MapValue, and MapDerivedType.

```csharp
[MapProperty("Weight", "WeightInGrams")]
public partial static void CopyApple(AppleDto dto, Apple apple);

[IncludeMappingConfiguration(nameof(CopyApple))]
public partial static AppleDto ToApple(Apple apple);
```

--------------------------------

### NamedMappingAttribute.Name Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.namedmappingattribute/

Gets the custom name specified for the mapping.

```APIDOC
## Name Property

### Description
Gets the custom name specified for the mapping.

### Property Signature
`public string Name { get; }`

### Property Value
- **Name** (string) - The custom name for the mapping.

### Example
```csharp
var attribute = new NamedMappingAttribute("CustomName");
string name = attribute.Name; // "CustomName"
```
```

--------------------------------

### MapperIgnoreSourceValueAttribute.TypeId

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoresourcevalueattribute/

Gets the type identifier for the attribute, inherited from System.Attribute.

```APIDOC
## MapperIgnoreSourceValueAttribute.TypeId

### Description
Gets the type identifier for the attribute, inherited from System.Attribute.

### Property
`public object TypeId { get; }`

### Property Value
- **TypeId** (Object) - The type identifier.
```

--------------------------------

### MapperIgnoreSourceValueAttribute.SourceValue

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoresourcevalueattribute/

Gets the source enum value which should be ignored from the mapping.

```APIDOC
## MapperIgnoreSourceValueAttribute.SourceValue

### Description
Gets the source enum value which should be ignored from the mapping.

### Property
`public Enum SourceValue { get; }`

### Property Value
- **SourceValue** (Enum) - The source enum value to ignore.
```

--------------------------------

### TypeId Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.includemappingconfigurationattribute/

Gets the TypeId property inherited from System.Attribute.

```APIDOC
## TypeId Property

### Description
Gets the TypeId property inherited from System.Attribute.

### Property Signature
`public object TypeId { get; }`

### Property Value
- Type: object
- Description: The TypeId of the attribute.
```

--------------------------------

### IncludeMappingConfigurationAttribute(String)

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.includemappingconfigurationattribute/

Initializes a new instance of the IncludeMappingConfigurationAttribute class with the name of the mapping configuration to include.

```APIDOC
## IncludeMappingConfigurationAttribute(String)

### Description
Initializes a new instance of the IncludeMappingConfigurationAttribute class. The attribute is used to include the mapping configuration of another mapping method in the attributed method.

### Constructor
`public IncludeMappingConfigurationAttribute(string name)`

### Parameters
- `name` (string) - Required - The name of the mapping configuration to include. Use the method name of the other mapping method.

### Usage Example
```csharp
[IncludeMappingConfiguration("OtherMappingMethod")]
public void MyMappingMethod() { }
```
```

--------------------------------

### MapPropertyFromSource with Use

Source: https://mapperly.riok.app/docs/configuration/mapper/

Shows how to use the Use property on MapPropertyFromSource to access multiple source properties in the mapping method. The mapping method takes the entire source object as a parameter. The generated code is shown in a comment.

```csharp
[Mapper]
public partial class CarMapper
{
  [MapPropertyFromSource(nameof(CarDto.NetPrice), Use = nameof(MapPrice))]
  public partial CarDto MapCar(Car source);

  private decimal MapPrice(Car car)
    => car.Price - car.Discount;

  // generates
  target.NetPrice = MapPrice(source);
}
```

--------------------------------

### TargetValue Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoretargetvalueattribute/

Gets the target enum value which should be ignored from the mapping.

```APIDOC
## TargetValue Property

### Description
Gets the target enum value which should be ignored from the mapping.

### Property Signature
`public Enum TargetValue { get; }`

### Property Value
Type: [Enum](https://docs.microsoft.com/en-us/dotnet/api/system.enum)

### Remarks
This property returns the enum value that was specified in the constructor.
```

--------------------------------

### Include external configuration via string path

Source: https://mapperly.riok.app/docs/configuration/reusing-mapping-configurations/

Reference an external mapping configuration using a fully qualified string path. The type must be fully qualified in the string.

```csharp
using OtherNamespace;

namespace MyNamespace;

[Mapper]
public partial class FruitMapper
{
    [IncludeMappingConfiguration("OtherNamespace.OtherMapper.CopyApple")]
    public partial static AppleDto ToApple(Apple apple);
}
```

```csharp
namespace OtherNamespace;

public static class OtherMapper
{
    // Property mapping configurations
    public partial static void CopyApple(AppleDto dto, Apple apple);
}
```

--------------------------------

### TargetType Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapderivedtypeattribute/

Gets the target type of the derived type mapping.

```APIDOC
## TargetType Property

### Description
Gets the target type of the derived type mapping.

### Property Signature
`public Type TargetType { get; }`

### Property Value
Type

```

--------------------------------

### SourceType Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapderivedtypeattribute/

Gets the source type of the derived type mapping.

```APIDOC
## SourceType Property

### Description
Gets the source type of the derived type mapping.

### Property Signature
`public Type SourceType { get; }`

### Property Value
Type

```

--------------------------------

### Property Source

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoresourceattribute/

Gets the source property name which should be ignored from the mapping.

```APIDOC
## Property Source

### Description
Gets the source property name which should be ignored from the mapping.

### Signature
public string Source { get; }

### Property Value
- **Source** (string) - The name of the source property to ignore.
```

--------------------------------

### Include mapping configuration by named mapping

Source: https://mapperly.riok.app/docs/configuration/reusing-mapping-configurations/

Use IncludeMappingConfiguration with a string name that matches a NamedMapping attribute to include configurations from a method with a custom name.

```csharp
[NamedMapping("CustomToApple")]
[MapProperty("Weight", "WeightInGrams")]
public partial static void CopyApple(AppleDto dto, Apple apple);

[IncludeMappingConfiguration("CustomToApple")]
public partial static AppleDto ToApple(Apple apple);
```

--------------------------------

### Target Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoretargetattribute/

Gets the target property name which should be ignored from the mapping.

```APIDOC
## Target Property

### Description
Gets the target property name which should be ignored from the mapping.

### Property Signature
`public string Target { get; }`

### Property Value
- **Target** (string) - The name of the target property to ignore.
```

--------------------------------

### IgnoreObsoleteStrategy Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperignoreobsoletemembersattribute/

Gets the strategy used to map members marked with the ObsoleteAttribute.

```APIDOC
## Property: IgnoreObsoleteStrategy

### Description
Gets the strategy used to map members marked with the ObsoleteAttribute.

### Signature
```csharp
public IgnoreObsoleteMembersStrategy IgnoreObsoleteStrategy { get; }
```

### Property Value
Type: IgnoreObsoleteMembersStrategy

```

--------------------------------

### Supported object factory method signatures

Source: https://mapperly.riok.app/docs/configuration/object-factories/

Lists the supported signatures for object factory methods. These include parameterless, single source parameter, generic with source, and two generic parameters variants.

```csharp
TargetType CreateTargetType();
TargetType CreateTargetType(SourceType source);
TargetType CreateTargetType<S>(S source);
T CreateTargetType<T>();
T CreateTargetType<T>(SourceType source);
TTarget CreateTargetType<TSource, TTarget>(TSource source);
TTarget CreateTargetType<TTarget, TSource>(TSource source);
```

--------------------------------

### Void mapping method with target as second parameter

Source: https://mapperly.riok.app/docs/configuration/existing-target/

Declares a partial mapping method that updates an existing CarDto from a Car. The method is void and takes the target as the second parameter. Usage shows calling the method and verifying the result.

```csharp
[Mapper]
public partial class CarMapper
{
    public partial void UpdateCarDto(Car car, CarDto dto);
}
```

```csharp
var mapper = new CarMapper();
var car = new Car { NumberOfSeats = 10, ... };
var dto = new CarDto();

mapper.UpdateCarDto(car, dto);
dto.NumberOfSeats.ShouldBe(10);
```

--------------------------------

### Include external configuration via type

Source: https://mapperly.riok.app/docs/configuration/reusing-mapping-configurations/

Reference an external mapping configuration using the fullnameof syntax with the @ prefix and the type name. The external mapper is in another namespace and must be fully qualified.

```csharp
using OtherNamespace;

namespace MyNamespace;

[Mapper]
public partial class FruitMapper
{
    [IncludeMappingConfiguration(nameof(@OtherMapper.CopyApple))]
    public partial static AppleDto ToApple(Apple apple);
}
```

```csharp
namespace OtherNamespace;

public static class OtherMapper
{
    // Property mapping configurations
    public partial static void CopyApple(AppleDto dto, Apple apple);
}
```

--------------------------------

### MapValueAttribute.Use Property

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/

Gets or sets the method name of the method which generates the value to be assigned to MapValueAttribute.Target.

```APIDOC
## Use Property

### Description
Gets or sets the method name of the method which generates the value to be assigned to [MapValueAttribute.Target](https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/#target). Either this property or [MapValueAttribute.Value](https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/#value) needs to be set. The return type of the referenced method must exactly match the type of [MapValueAttribute.Target](https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapvalueattribute/#target) and needs to be parameterless. The usage of nameof is encouraged.

### Definition
```csharp
public string Use { get; set; }
```

### Property Value
[String](https://docs.microsoft.com/en-us/dotnet/api/system.string)
```

--------------------------------

### Manual flattening with MapProperty attribute

Source: https://mapperly.riok.app/docs/configuration/flattening/

Shows three equivalent ways to configure flattening of Car.Make.Id to CarDto.MakeId using MapPropertyAttribute: with nameof array, dot-separated string, or interpolated nameof string.

```csharp
[MapProperty([nameof(Car.Make), nameof(Car.Make.Id)], nameof(CarDto.MakeId))]
// Or alternatively
[MapProperty("Make.Id", "MakeId")]
// Or
[MapProperty($"{nameof(Make)}.{nameof(Make.Id)}", "MakeId")]
partial CarDto Map(Car car);
```

--------------------------------

### Ignore obsolete members locally with MapperIgnoreObsoleteMembersAttribute

Source: https://mapperly.riok.app/docs/configuration/mapper/

Use MapperIgnoreObsoleteMembersAttribute on a mapping method to override the global strategy. The example uses IgnoreObsoleteMembersStrategy.Both for MapMake.

```csharp
[Mapper]
public partial class CarMapper
{
    [MapperIgnoreObsoleteMembers(IgnoreObsoleteMembersStrategy.Both)]
    public partial CarMakeDto MapMake(CarMake make);
}
```

--------------------------------

### ObjectFactoryAttribute Constructor

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.objectfactoryattribute/

Initializes a new instance of the ObjectFactoryAttribute class.

```APIDOC
## ObjectFactoryAttribute()

### Description
Initializes a new instance of the ObjectFactoryAttribute class.

### Method
Constructor

### Signature
public ObjectFactoryAttribute()

### Parameters
None

### Return Value
None (constructor)
```

--------------------------------

### Ignore obsolete members globally with MapperAttribute

Source: https://mapperly.riok.app/docs/configuration/mapper/

Set IgnoreObsoleteMembersStrategy on the MapperAttribute to ignore obsolete members for all methods in the mapper. The example uses IgnoreObsoleteMembersStrategy.Both.

```csharp
[Mapper(IgnoreObsoleteMembersStrategy = IgnoreObsoleteMembersStrategy.Both)]
public partial class CarMapper
{
    ...
}
```

--------------------------------

### Add Riok.Mapperly PackageReference

Source: https://mapperly.riok.app/docs/getting-started/installation/

XML snippet for adding the Riok.Mapperly NuGet package to a .csproj file. Includes ExcludeAssets="runtime" and PrivateAssets="all" to remove the runtime dependency.

```xml
<PackageReference Include="Riok.Mapperly" Version="4.3.1" ExcludeAssets="runtime" PrivateAssets="all" />
```

--------------------------------

### Create a new Git branch

Source: https://mapperly.riok.app/docs/contributing/

Creates a new branch named 'my-fix-branch' from the 'main' branch. Use this when starting work on a fix or feature.

```shell
git checkout -b my-fix-branch main
```

--------------------------------

### MapperConstructorAttribute

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperconstructorattribute/

Marks the constructor to be used when type gets activated by Mapperly. This attribute is applied to constructors to indicate that Mapperly should use them during object activation.

```APIDOC
## MapperConstructorAttribute

### Description
Marks the constructor to be used when type gets activated by Mapperly.

### Namespace
Riok.Mapperly.Abstractions

### Inheritance
Object → Attribute → MapperConstructorAttribute

### Attributes
AttributeUsageAttribute, ConditionalAttribute

### Constructors

#### MapperConstructorAttribute()

```csharp
public MapperConstructorAttribute()
```

Initializes a new instance of the MapperConstructorAttribute class.

### Properties

#### TypeId

```csharp
public object TypeId { get; }
```

Gets the type identifier for this attribute.

##### Property Value
Object
```

--------------------------------

### Ignore a member at definition with MapperIgnore

Source: https://mapperly.riok.app/docs/configuration/mapper/

Use MapperIgnore on a property, field, or method to exclude it from mapping. The example shows a mapper and its source/target classes where Car.Id is ignored.

```csharp
public partial class CarMapper
{
    public partial CarDto ToDto(Car car);
}

public class Car
{
    [MapperIgnore]
    public int Id { get; set; }

    public string ModelName { get; set; }
}

public class CarDto
{
    public string ModelName { get; set; }
}
```

--------------------------------

### Run linters locally

Source: https://mapperly.riok.app/docs/contributing/docs/

Runs the linters to check for code style and potential issues in the documentation source.

```bash
npm run lint
```

--------------------------------

### Enable generated file emission in .csproj

Source: https://mapperly.riok.app/docs/configuration/generated-source/

Set EmitCompilerGeneratedFiles to true in a PropertyGroup to write generated source files to disk. Default output is {BaseIntermediateOutpath}/generated/{Assembly}/Riok.Mapperly/{GeneratedFile}.

```xml
<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>
```

--------------------------------

### Enable generated file emission via .NET CLI

Source: https://mapperly.riok.app/docs/configuration/generated-source/

Pass the EmitCompilerGeneratedFiles property as a build parameter to emit generated files without editing the project file.

```bash
dotnet build /p:EmitCompilerGeneratedFiles=true
```

--------------------------------

### MappingTargetAttribute()

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mappingtargetattribute/

Initializes a new instance of the MappingTargetAttribute class.

```APIDOC
## MappingTargetAttribute()

### Description
Initializes a new instance of the MappingTargetAttribute class.

### Method
Constructor

### Signature
```csharp
public MappingTargetAttribute()
```

### Parameters
None.

### Return Value
None (constructor).
```

--------------------------------

### MapPropertyAttribute(String[], String[]) Constructor

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mappropertyattribute/

Maps a specified source property to the specified target property. The source and target parameters are string arrays representing the property paths.

```APIDOC
## MapPropertyAttribute(String[], String[]) Constructor

### Description
Maps a specified source property to the specified target property. The source and target parameters are string arrays representing the property paths.

### Method
Constructor

### Signature
public MapPropertyAttribute(String[] source, String[] target)

### Parameters
- **source** (String[]) - Required - The path of the source property. The use of `nameof()` is encouraged.
- **target** (String[]) - Required - The path of the target property. The use of `nameof()` is encouraged.

### Remarks
This constructor is part of the MapPropertyAttribute class in the Riok.Mapperly.Abstractions namespace. It allows mapping nested properties by specifying the path as an array of property names.
```

--------------------------------

### Wrap generated map method with custom before/after logic

Source: https://mapperly.riok.app/docs/configuration/before-after-map/

Defines a partial CarMapper class with a generated CarToCarDto method and a custom MapCarToCarDto method that calls it. The [UserMapping(Default = true)] attribute ensures Mapperly uses this custom mapping instead of the generated one. Place custom before-map code before the call and after-map code after it.

```csharp
[Mapper]
public partial class CarMapper
{
    private partial CarDto CarToCarDto(Car car);

    // Default ensures Mapperly uses this mapping whenever a conversion
    // from Car to CarDto is needed instead of the `CarToCarDto` method.
    [UserMapping(Default = true)]
    public CarDto MapCarToCarDto(Car car)
    {
        // custom before map code...
        var dto = CarToCarDto(car);
        // custom after map code...
        return dto;
    }
}
```

--------------------------------

### Define the CarMapper with [Mapper] and [MapProperty] attributes

Source: https://mapperly.riok.app/docs/getting-started/generated-mapper-example/

Use this static partial class to define a mapping from Car to CarDto. The [Mapper] attribute with EnumMappingStrategy.ByName is required because the enum numeric values differ. The [MapProperty] attribute maps the Manufacturer property to Producer.

```csharp
using Riok.Mapperly.Abstractions;

namespace Riok.Mapperly.Sample;

// Enums of source and target have different numeric values -> use ByName strategy to map them
[Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName)]
public static partial class CarMapper
{
    [MapProperty(nameof(Car.Manufacturer), nameof(CarDto.Producer))] // Map property with a different name in the target type
    public static partial CarDto MapCarToDto(Car car);
}
```

--------------------------------

### Merge objects with AllowNullPropertyAssignment = false

Source: https://mapperly.riok.app/docs/configuration/existing-target/

Shows how to merge two objects by setting AllowNullPropertyAssignment to false, which ignores null source properties. Includes declaration, usage, and generated code that conditionally assigns non-null properties.

```csharp
[Mapper(AllowNullPropertyAssignment = false)]
static partial class FruitMapper
{
    public static partial void ApplyUpdate(FruitUpdate update, Fruit fruit);
}

class Fruit { public required string Name { get; set; } public required string Color { get; set; } }
record FruitUpdate(string? Name, string? Color);
```

```csharp
FruitMapper.ApplyUpdate(myUpdateRequest, myFruit);
```

```csharp
static partial class FruitMapper
{
    public static partial void Update(global::FruitUpdate update, global::Fruit fruit)
    {
        if (update.Name != null)
        {
            fruit.Name = update.Name;
        }
        if (update.Color != null)
        {
            fruit.Color = update.Color;
        }
    }
}
```

--------------------------------

### Enable deep cloning with Mapper(UseDeepCloning = true)

Source: https://mapperly.riok.app/docs/configuration/mapper/

By default, Mapperly does not deep copy objects for performance. Set UseDeepCloning to true to create deep copies. Note: deep cloning is not applied to IQueryable projection mappings.

```csharp
[Mapper(UseDeepCloning = true)]
public partial class CarMapper
{
  ...
}
```

--------------------------------

### EnabledConversions property declaration

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.mapperdefaultsattribute/

Specifies which conversions Mapperly automatically implements. By default all supported conversions are enabled. Examples show disabling all conversions with MappingConversionType.None and disabling ToString() method calls with MappingConversionType.All & ~MappingConversionType.ToStringMethod.

```csharp
public MappingConversionType EnabledConversions { get; set; }
```

--------------------------------

### Static mapper with extension method

Source: https://mapperly.riok.app/docs/configuration/static-mappers/

Define a static partial mapper class with a static partial extension method and a private static helper method.

```csharp
[Mapper]
public static partial class CarMapper
{
    public static partial CarDto ToCarDto(this Car car);

    private static int TimeSpanToHours(TimeSpan t) => t.Hours;
}
```

--------------------------------

### User-implemented mapping method for inlining

Source: https://mapperly.riok.app/docs/configuration/queryable-projections/

Defines a user-implemented mapping method that Mapperly can inline. The method must be expression-bodied or consist of a single local variable declaration expression, and follow expression tree limitations.

```csharp
[Mapper]
public static partial class CarMapper
{
    public static partial IQueryable<CarDto> ProjectToDto(this IQueryable<Car> q);

    private static string MapCarBrandName(CarBrand brand)
      => brand.Name;
}
```

--------------------------------

### Set assembly-level mapper defaults with MapperDefaults

Source: https://mapperly.riok.app/docs/configuration/mapper/

Applies default configurations to all mappers in the assembly. Here, EnumMappingIgnoreCase is set to true.

```csharp
[assembly: MapperDefaults(EnumMappingIgnoreCase = true)]
```

--------------------------------

### Static external method reference with full-nameof

Source: https://mapperly.riok.app/docs/configuration/external-mappings/

Use the @ prefix with nameof to reference static methods from an external class in the Use property. The generated code calls the methods with the global:: namespace prefix.

```csharp
using OtherNamespace;

namespace MyNamespace;

[Mapper]
public partial class CarMapper
{
    [MapProperty(nameof(Car.Price), nameof(CarDto.Price), Use = nameof(@PriceMapper.MapPrice))]
    [MapPropertyFromSource(nameof(CarDto.NetPrice), Use = nameof(@PriceMapper.MapPriceFromSource))]
    [MapValue(nameof(CarDto.SourceSystem), Use = nameof(@SourceSystems.GetSourceSystem))]
    public partial CarDto MapCar(Car source);

    // generates
    target.Price = global::OtherNamespace.PriceMapper.MapPrice(source.Price);
    target.NetPrice = global::OtherNamespace.PriceMapper.MapPriceFromSource(source);
    target.SourceSystem = global::OtherNamespace.SourceSystems.GetSourceSystem();
}
```

--------------------------------

### FormatProviderAttribute Class

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.formatproviderattribute/

Marks a property or field as a format provider. The type must implement IFormatProvider and have a getter.

```APIDOC
## FormatProviderAttribute

### Description
Marks a property or field as a format provider. A format provider needs to be of a type which implements IFormatProvider and needs to have a getter.

### Namespace
Riok.Mapperly.Abstractions

### Inheritance
Object → Attribute → FormatProviderAttribute

### Attributes
AttributeUsageAttribute, ConditionalAttribute

### Constructors

#### FormatProviderAttribute()
Initializes a new instance of the FormatProviderAttribute class.

```csharp
public FormatProviderAttribute()
```

### Properties

#### Default
If set to true, this format provider acts as a default format provider and is used for all IFormattable conversions without an explicit MapPropertyAttribute.FormatProvider set. Only one FormatProviderAttribute in a Mapper can be set to true.

```csharp
public bool Default { get; set; }
```

Property Value: Boolean

#### TypeId
Gets the type identifier for this attribute.

```csharp
public object TypeId { get; }
```

Property Value: Object
```

--------------------------------

### Ignore a user-implemented mapping method with [UserMapping(Ignore = true)]

Source: https://mapperly.riok.app/docs/configuration/user-implemented-methods/

Use [UserMapping(Ignore = true)] to exclude a user-implemented mapping method from being discovered and used by Mapperly when AutoUserMappings is enabled. The example shows a CarMapper with a default mapping method and an ignored one.

```csharp
[Mapper]
public partial class CarMapper
{
    public partial CarDto CarToCarDto(Car car);

    // discovered and used by default (AutoUserMappings is true by default)
    private int TimeSpanToHours(TimeSpan t) => t.Hours;

    // ignored user-implemented mapping
    [UserMapping(Ignore = true)]
    private int IgnoredTimeSpanToHours(TimeSpan t) => t.Minutes / 60;
}
```

--------------------------------

### Verify no linting issues with CSharpier and dotnet format

Source: https://mapperly.riok.app/docs/contributing/tests/

Checks that the code is properly formatted and has no analyzer issues. These commands are used in CI to enforce code style.

```bash
dotnet csharpier check .
dotnet format style --verify-no-changes
dotnet format analyzers --verify-no-changes
```

--------------------------------

### ReferenceHandlerAttribute()

Source: https://mapperly.riok.app/docs/api/riok.mapperly.abstractions.referencehandling.referencehandlerattribute/

Initializes a new instance of the ReferenceHandlerAttribute class.

```APIDOC
## ReferenceHandlerAttribute()

### Description
Initializes a new instance of the ReferenceHandlerAttribute class.

### Constructor
`public ReferenceHandlerAttribute()`

### Parameters
None.

### Return Value
None (constructor).

```
Tokens:
Raw