Skip to content
Skills Library
Programming · Building & coding

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

Repository
recyclarr ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

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

  1. Mapper Conventions
  2. Null Handling
  3. Diagnostics
  4. User-Implemented Methods
  5. Verifying Generated Code
Original SKILL.md headings · 70 lines, 497 words
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

RepositoryScoreLicence
This page · recyclarr/recyclarr90MIT
Tyler-R-Kendrick/agent-skills100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.