From b9339f19d7796643329340904a690bb1de751d17 Mon Sep 17 00:00:00 2001
From: maliming <malimings@gmail.com>
Date: Wed, 28 Jan 2026 14:33:32 +0800
Subject: [PATCH 1/2] docs: add section on nullable reference types for
 Mapperly

---
 .../object-to-object-mapping.md               | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/en/framework/infrastructure/object-to-object-mapping.md b/docs/en/framework/infrastructure/object-to-object-mapping.md
index 4a54500814..30995dedf1 100644
--- a/docs/en/framework/infrastructure/object-to-object-mapping.md
+++ b/docs/en/framework/infrastructure/object-to-object-mapping.md
@@ -313,6 +313,34 @@ It is suggested to use the `MapExtraPropertiesAttribute` attribute if both class
 
 Mapperly requires that properties of both source and destination objects have `setter` methods. Otherwise, the property will be ignored. You can use `protected set` or `private set` to control the visibility of the `setter` method, but each property must have a `setter` method.
 
+### Nullable Reference Types
+
+Mapperly respects C# nullable reference types (NRT). If your project enables NRT via `<Nullable>enable</Nullable>` in the project file, Mapperly will treat reference type properties as **non-nullable by default**.
+
+That means:
+
+- If a property can be `null`, declare it as nullable so Mapperly (and the compiler) understands it can be missing.
+- If you declare a property as non-nullable, Mapperly assumes it is not `null`.
+
+Otherwise, the generated mapping code may throw runtime exceptions (e.g., `NullReferenceException`) if a value is actually `null` during the mapping process.
+
+Example:
+
+````xml
+<!-- .csproj -->
+<PropertyGroup>
+    <Nullable>enable</Nullable>
+</PropertyGroup>
+````
+
+````csharp
+public class PersonDto
+{
+    public Country? Country { get; set; } // Nullable (can be null)
+    public City City { get; set; } // Non-nullable (cannot be null)
+}
+````
+
 ### Deep Cloning
 
 By default, Mapperly does not create deep copies of objects to improve performance. If an object can be directly assigned to the target, it will do so (e.g., if the source and target type are both `List<T>`, the list and its entries will not be cloned). To create deep copies, set the `UseDeepCloning` property on the `MapperAttribute` to `true`.
@@ -505,6 +533,7 @@ Each solution has its own advantages:
 
 Choose the approach that best aligns with your application's architecture and maintainability requirements.
 
+
 ### More Mapperly Features
 
 Most of Mapperly's features such as `Ignore` can be configured through its attributes. See the [Mapperly documentation](https://mapperly.riok.app/docs/intro/) for more details.

From e6e5a22243d217cd01593265eb5c258f93934562 Mon Sep 17 00:00:00 2001
From: Ma Liming <malimings@gmail.com>
Date: Wed, 28 Jan 2026 14:37:28 +0800
Subject: [PATCH 2/2] Update
 docs/en/framework/infrastructure/object-to-object-mapping.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/en/framework/infrastructure/object-to-object-mapping.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/framework/infrastructure/object-to-object-mapping.md b/docs/en/framework/infrastructure/object-to-object-mapping.md
index 30995dedf1..39218e7c86 100644
--- a/docs/en/framework/infrastructure/object-to-object-mapping.md
+++ b/docs/en/framework/infrastructure/object-to-object-mapping.md
@@ -337,7 +337,7 @@ Example:
 public class PersonDto
 {
     public Country? Country { get; set; } // Nullable (can be null)
-    public City City { get; set; } // Non-nullable (cannot be null)
+    public City City { get; set; } = default!; // Non-nullable (cannot be null)
 }
 ````