mapperly
/mapperly
Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper classes; adding or changing a `[Mapper]`-attributed partial class; configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`, or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs and non-nullable domain records; debugging null-handling in generated mapping code (positional records, `required init`, initializer defaults); investigating Mapperly diagnostics such as RMG023, RMG060, or RMG089; inspecting source-generated output under `obj/*/*/generated/Riok.Mapperly/`. Triggers on phrases
- Author
- recyclarr ↗
- Repository
- recyclarr ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper classes; adding or changing a `[Mapper]`-attributed partial class; configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`, or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs and non-nullable domain records; debugging null-handling in generated mapping code (positional records, `required init`, initializer defaults); investigating Mapperly diagnostics such as RMG023, RMG060, or RMG089; inspecting source-generated output under `obj/*/*/generated/Riok.Mapperly/`. Triggers on phrases
Original author description
Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper classes; adding or changing a `[Mapper]`-attributed partial class; configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`, or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs and non-nullable domain records; debugging null-handling in generated mapping code (positional records, `required init`, initializer defaults); investigating Mapperly diagnostics such as RMG023, RMG060, or RMG089; inspecting source-generated output under `obj/*/*/generated/Riok.Mapperly/`. Triggers on phrases
How it works
- Mapper Conventions
- Null Handling
- Diagnostics
- User-Implemented Methods
- Verifying Generated Code
SKILL.md preview
---
name: mapperly
description: >-
Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper
classes; adding or changing a `[Mapper]`-attributed partial class;
configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`,
or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs
and non-nullable domain records; debugging null-handling in generated
mapping code (positional records, `required init`, initializer defaults);
investigating Mapperly diagnostics such as RMG023, RMG060, or RMG089;
inspecting source-generated output under
`obj/*/*/generated/Riok.Mapperly/`. Triggers on phrases like "add a
Mapperly mapper", "Mapperly null handling", "DTO to domain mapping",
"generated mapper", or edits to files ending in `*Mapper.cs` under
`ServarrApi/`. Do NOT use for hand-written mapping code or AutoMapper.
---
# Mapperly
Repository conventions and verified null-handling behavior for Mapperly mappers. Behavior below was
observed in generated output from `Riok.Mapperly` 4.3.1 (pinned in `Directory.Packages.props`).
Re-verify against generated code after a Mapperly upgrade.
## Mapper Conventions
- `[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.None)]` on every mapper. Generated DTOs
have many properties we don't map; this silences unmapped-member warnings (RMG012, RMG020).
- Mappers are `internal static partial class`.
- One mapper class per service API generation (`SonarrV3*`, `SonarrV5*`, `Radarr*`). Generated DTO
types share names but are distinct types; alias namespaces:
`using SonarrApi = Recyclarr.Api.Sonarr.V3`.
- Domain-to-DTO writes use an existing-target method
(`void UpdateDto(TDomain, [MappingTarget] TDto)`) so DTO fields the domain does not model keep
their fetched values.
## Null Handling
Refit DTOs declare every property nullable. Mapper settings stay at defaults
(`ThrowOnMappingNullMismatch = true`, `AllowNullPropertyAssignment = true`). The generated code for
a null source value depends on the target member shape:
| Target member | Null source value |
| ------------------------------------------------------- | -------------------------------------- |
| Nullable (`T?`) | Assigned, including null |
| Non-nullable constructor parameter | `?? throw ArgumentNullException` |
| Non-nullable `init` or `required` (with or without `=`) | `?? throw ArgumentNullException` |
| Non-nullable settable (`set`) | Assignment skipped; prior value stays |
Consequences:
- Property initializers never act as fallbacks for constructor or `init` targets; the generated
object initializer overwrites them or throws. `public string Name { get; init; } = "";` still
throws when the DTO field is null.
- A field that Sonarr/Radarr may omit needs a nullable domain property, or a user-implemented method
that supplies the fallback (see `ItemToDomain` in `SonarrV3QualityProfileMapper`).
- A non-nullable settable property with no initializer stays `null` when the source is null,
silently violating its contract. Avoid this shape.
- In `UpdateDto`, a null domain value overwrites the DTO field with null, because DTO targets are
nullable.
- `ThrowOnMappingNullMismatch = false` replaces the throw with `""`, `new T()`, or `default`. It is
unused in this repository; collections such as `List<T>` still throw and report RMG002.
## Diagnostics
- RMG089 (Info): "Mapping the nullable source property ... to the target property ... which is not
nullable". Expected for every nullable DTO to non-nullable domain member; it marks a member that
throws or skips per the table above. Check that outcome is intended rather than suppressing it.
- RMG023 (Error): a `required` target member has no matching source member.
`RequiredMappingStrategy .None` does not suppress it; add `[MapProperty]` or a user-implemented
method.
- RMG060 (Warning): multiple user-implemented methods for the same type pair.
## User-Implemented Methods
Mapperly discovers any non-partial method in the mapper with a mapping signature and uses it for
that type pair, including nested members and collection elements (`MapFieldValue` in
`SonarrV3CustomFormatMapper`). Parameter and return types must match the mapped types exactly,
including nullability.
## Verifying Generated Code
`Directory.Build.props` enables `EmitCompilerGeneratedFiles` for the whole repository. After a
build, find the output with `rg --files --no-ignore -g '<Mapper>.g.cs' src/<Project>/obj`; it lives
under `obj/<Configuration>/<tfm>/generated/Riok.Mapperly/Riok.Mapperly.MapperGenerator/`. Confirm
null handling there instead of inferring it from attributes.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · recyclarr/recyclarr | 90 | MIT |
| Tyler-R-Kendrick/agent-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version f9cafe6dea98 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100abp-object-mapping
ABP Framework v10.x (10.4–10.6) object mapping: IObjectMapper, Mapperly (default since v10.4, MapperBase), AutoMapper profiles, entity↔DTO conversion, AutoMap attributes. Use when you need object mapping or DTO mapping in ABP. - 100abp-object-mapping
ABP Framework v10.x (10.4–10.6) object mapping quick reference: IObjectMapper, Mapperly (default since v10.4), AutoMapper profile/attribute, entity↔DTO. Use when you need object mapping in ABP. - 100map-objects-and-dtos
Maps entities to DTOs (or object-to-object) in an ABP app through the IObjectMapper abstraction. USE FOR: IObjectMapper usage, defining AutoMapper profiles or Mapperly mappers, registering maps with AbpAutoMapperOptions.AddMaps, mapping extra properties, mapping collections,… - 95csharp-nullable-types
Use when C# nullable reference types and value types for null safety, nullable annotations, and patterns for handling null values. - 100vertical-slice-architecture
Scaffold and navigate a .NET Clean Architecture codebase organised as Vertical Slice Architecture (VSA) — the Hona/VerticalSliceArchitecture layout of Domain / Common / Features slices with FastEndpoints, EF Core, Vogen strong IDs, Mapperly, FluentValidation, and Testcontainers.… - 91csharp-nullable-types
Use when C# nullable reference types, null safety patterns, and migration strategies. Use when ensuring null safety in C# code.