From 56935ea789b105ece8d357a3a4e4aa74908ba267 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:39:49 +0500 Subject: [PATCH 01/13] --Duplicate .\Data-types.md history into .\data-types\Record-types.md --- .../mapping/{Data-types.md => data-types/Record-types.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/articles/mapping/{Data-types.md => data-types/Record-types.md} (100%) diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/data-types/Record-types.md similarity index 100% rename from docs/articles/mapping/Data-types.md rename to docs/articles/mapping/data-types/Record-types.md From 491eec7b9efe34f74292c0c2e174d29b3907abdc Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:39:49 +0500 Subject: [PATCH 02/13] --Restore .\Data-types.md --- docs/articles/mapping/Data-types.md | 192 ++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md new file mode 100644 index 00000000..c139ee0c --- /dev/null +++ b/docs/articles/mapping/Data-types.md @@ -0,0 +1,192 @@ +--- +uid: Mapster.Mapping.DataTypes +title: "Mapping - Data Types" +--- + +## Primitives + +Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. + +```csharp +decimal i = 123.Adapt(); //equal to (decimal)123; +``` + +## Enums + +Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. +The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. + +In Mapster, flagged enums are also supported. + +```csharp +var e = "Read, Write, Delete".Adapt(); +//FileShare.Read | FileShare.Write | FileShare.Delete +``` + +For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: + +```csharp +TypeAdapterConfig.GlobalSettings.Default + .EnumMappingStrategy(EnumMappingStrategy.ByName); +``` + +## Strings + +When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. + +```csharp +var s = 123.Adapt(); //equal to 123.ToString(); +var i = "123".Adapt(); //equal to int.Parse("123"); +``` + +## Collections + +This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... + +```csharp +var list = db.Pocos.ToList(); +var target = list.Adapt>(); +``` + +## Mappable Objects + +Mapster can map two different objects using the following rules: + +- Source and destination property names are the same. Ex: `dest.Name = src.Name` +- Source has get method. Ex: `dest.Name = src.GetName()` +- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` + +Example: + +```csharp +class Staff { + public string Name { get; set; } + public int GetAge() { + return (DateTime.Now - this.BirthDate).TotalDays / 365.25; + } + public Staff Supervisor { get; set; } + ... +} + +struct StaffDto { + public string Name { get; set; } + public int Age { get; set; } + public string SupervisorName { get; set; } +} + +var dto = staff.Adapt(); +//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name +``` + +**Mappable Object types are included:** + +- POCO classes +- POCO structs +- POCO interfaces +- Dictionary type implement `IDictionary` +- Record types (either class, struct, and interface) + +Example for object to dictionary: + +```csharp +var point = new { X = 2, Y = 3 }; +var dict = point.Adapt>(); +dict["Y"].ShouldBe(3); +``` + +## Record types + +>[!IMPORTANT] +> Mapster treats Record type as an immutable type. +> Only a Nondestructive mutation - creating a new object with modified properties. +> +> ```csharp +> var result = source.adapt(data) +>//equal var result = data with { X = source.X.Adapt(), ...} +>``` + +### Features and Limitations: + +# [v10.0](#tab/Records-v10) + +>[!NOTE] +> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. +> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. + + +#### Using default value in constuctor param + +If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. + +Example: + +```csharp + +class SourceData +{ + public string MyString {get; set;} +} + +record RecordDestination(int myInt, string myString); + +var result = source.Adapt() + +// equal var result = new RecordDestination (default(int),source.myString) + +``` + +#### MultiConstructor Record types + +If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. + +Example: + +```csharp +record MultiCtorRecord +{ + public MultiCtorRecord(int myInt) + { + MyInt = myInt; + } + + public MultiCtorRecord(int myInt, string myString) // This constructor will be used + : this(myInt) + { + MyString = myString; + } + +} +``` + +# [v7.4.0](#tab/Records-v7-4-0) + +>[!NOTE] +>Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. + +Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). + +Example for record types: + +```csharp +class Person { + public string Name { get; } + public int Age { get; } + + public Person(string name, int age) { + this.Name = name; + this.Age = age; + } +} + +var src = new { Name = "Mapster", Age = 3 }; +var target = src.Adapt(); +``` +--- + +### Support additional mapping features: + +| Mapping features | v7.4.0 | v10.0 | +|:-----------------|:------:|:-----:| +|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | +|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | +|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | From 4bccc4c51eafbb04c13dc7d14470c917e5b6115b Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:40:35 +0500 Subject: [PATCH 03/13] --Duplicate .\Data-types.md history into .\data-types\Mapping-types.md --- .../mapping/{Data-types.md => data-types/Mapping-types.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/articles/mapping/{Data-types.md => data-types/Mapping-types.md} (100%) diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/data-types/Mapping-types.md similarity index 100% rename from docs/articles/mapping/Data-types.md rename to docs/articles/mapping/data-types/Mapping-types.md From d84b3e788152a5ae76b4f23848fb936fc653e5d2 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:40:35 +0500 Subject: [PATCH 04/13] --Restore .\Data-types.md --- docs/articles/mapping/Data-types.md | 192 ++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md new file mode 100644 index 00000000..c139ee0c --- /dev/null +++ b/docs/articles/mapping/Data-types.md @@ -0,0 +1,192 @@ +--- +uid: Mapster.Mapping.DataTypes +title: "Mapping - Data Types" +--- + +## Primitives + +Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. + +```csharp +decimal i = 123.Adapt(); //equal to (decimal)123; +``` + +## Enums + +Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. +The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. + +In Mapster, flagged enums are also supported. + +```csharp +var e = "Read, Write, Delete".Adapt(); +//FileShare.Read | FileShare.Write | FileShare.Delete +``` + +For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: + +```csharp +TypeAdapterConfig.GlobalSettings.Default + .EnumMappingStrategy(EnumMappingStrategy.ByName); +``` + +## Strings + +When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. + +```csharp +var s = 123.Adapt(); //equal to 123.ToString(); +var i = "123".Adapt(); //equal to int.Parse("123"); +``` + +## Collections + +This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... + +```csharp +var list = db.Pocos.ToList(); +var target = list.Adapt>(); +``` + +## Mappable Objects + +Mapster can map two different objects using the following rules: + +- Source and destination property names are the same. Ex: `dest.Name = src.Name` +- Source has get method. Ex: `dest.Name = src.GetName()` +- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` + +Example: + +```csharp +class Staff { + public string Name { get; set; } + public int GetAge() { + return (DateTime.Now - this.BirthDate).TotalDays / 365.25; + } + public Staff Supervisor { get; set; } + ... +} + +struct StaffDto { + public string Name { get; set; } + public int Age { get; set; } + public string SupervisorName { get; set; } +} + +var dto = staff.Adapt(); +//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name +``` + +**Mappable Object types are included:** + +- POCO classes +- POCO structs +- POCO interfaces +- Dictionary type implement `IDictionary` +- Record types (either class, struct, and interface) + +Example for object to dictionary: + +```csharp +var point = new { X = 2, Y = 3 }; +var dict = point.Adapt>(); +dict["Y"].ShouldBe(3); +``` + +## Record types + +>[!IMPORTANT] +> Mapster treats Record type as an immutable type. +> Only a Nondestructive mutation - creating a new object with modified properties. +> +> ```csharp +> var result = source.adapt(data) +>//equal var result = data with { X = source.X.Adapt(), ...} +>``` + +### Features and Limitations: + +# [v10.0](#tab/Records-v10) + +>[!NOTE] +> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. +> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. + + +#### Using default value in constuctor param + +If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. + +Example: + +```csharp + +class SourceData +{ + public string MyString {get; set;} +} + +record RecordDestination(int myInt, string myString); + +var result = source.Adapt() + +// equal var result = new RecordDestination (default(int),source.myString) + +``` + +#### MultiConstructor Record types + +If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. + +Example: + +```csharp +record MultiCtorRecord +{ + public MultiCtorRecord(int myInt) + { + MyInt = myInt; + } + + public MultiCtorRecord(int myInt, string myString) // This constructor will be used + : this(myInt) + { + MyString = myString; + } + +} +``` + +# [v7.4.0](#tab/Records-v7-4-0) + +>[!NOTE] +>Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. + +Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). + +Example for record types: + +```csharp +class Person { + public string Name { get; } + public int Age { get; } + + public Person(string name, int age) { + this.Name = name; + this.Age = age; + } +} + +var src = new { Name = "Mapster", Age = 3 }; +var target = src.Adapt(); +``` +--- + +### Support additional mapping features: + +| Mapping features | v7.4.0 | v10.0 | +|:-----------------|:------:|:-----:| +|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | +|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | +|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | From f86367852f0c8560266dc9daaaca5276515ed2a7 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:40:56 +0500 Subject: [PATCH 05/13] --Duplicate .\Data-types.md history into .\data-types\Primitive-types.md --- .../mapping/{Data-types.md => data-types/Primitive-types.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/articles/mapping/{Data-types.md => data-types/Primitive-types.md} (100%) diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/data-types/Primitive-types.md similarity index 100% rename from docs/articles/mapping/Data-types.md rename to docs/articles/mapping/data-types/Primitive-types.md From 1878ffe26d4953a7652e6895ee8c875e157393d3 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:40:56 +0500 Subject: [PATCH 06/13] --Restore .\Data-types.md --- docs/articles/mapping/Data-types.md | 192 ++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md new file mode 100644 index 00000000..c139ee0c --- /dev/null +++ b/docs/articles/mapping/Data-types.md @@ -0,0 +1,192 @@ +--- +uid: Mapster.Mapping.DataTypes +title: "Mapping - Data Types" +--- + +## Primitives + +Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. + +```csharp +decimal i = 123.Adapt(); //equal to (decimal)123; +``` + +## Enums + +Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. +The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. + +In Mapster, flagged enums are also supported. + +```csharp +var e = "Read, Write, Delete".Adapt(); +//FileShare.Read | FileShare.Write | FileShare.Delete +``` + +For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: + +```csharp +TypeAdapterConfig.GlobalSettings.Default + .EnumMappingStrategy(EnumMappingStrategy.ByName); +``` + +## Strings + +When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. + +```csharp +var s = 123.Adapt(); //equal to 123.ToString(); +var i = "123".Adapt(); //equal to int.Parse("123"); +``` + +## Collections + +This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... + +```csharp +var list = db.Pocos.ToList(); +var target = list.Adapt>(); +``` + +## Mappable Objects + +Mapster can map two different objects using the following rules: + +- Source and destination property names are the same. Ex: `dest.Name = src.Name` +- Source has get method. Ex: `dest.Name = src.GetName()` +- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` + +Example: + +```csharp +class Staff { + public string Name { get; set; } + public int GetAge() { + return (DateTime.Now - this.BirthDate).TotalDays / 365.25; + } + public Staff Supervisor { get; set; } + ... +} + +struct StaffDto { + public string Name { get; set; } + public int Age { get; set; } + public string SupervisorName { get; set; } +} + +var dto = staff.Adapt(); +//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name +``` + +**Mappable Object types are included:** + +- POCO classes +- POCO structs +- POCO interfaces +- Dictionary type implement `IDictionary` +- Record types (either class, struct, and interface) + +Example for object to dictionary: + +```csharp +var point = new { X = 2, Y = 3 }; +var dict = point.Adapt>(); +dict["Y"].ShouldBe(3); +``` + +## Record types + +>[!IMPORTANT] +> Mapster treats Record type as an immutable type. +> Only a Nondestructive mutation - creating a new object with modified properties. +> +> ```csharp +> var result = source.adapt(data) +>//equal var result = data with { X = source.X.Adapt(), ...} +>``` + +### Features and Limitations: + +# [v10.0](#tab/Records-v10) + +>[!NOTE] +> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. +> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. + + +#### Using default value in constuctor param + +If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. + +Example: + +```csharp + +class SourceData +{ + public string MyString {get; set;} +} + +record RecordDestination(int myInt, string myString); + +var result = source.Adapt() + +// equal var result = new RecordDestination (default(int),source.myString) + +``` + +#### MultiConstructor Record types + +If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. + +Example: + +```csharp +record MultiCtorRecord +{ + public MultiCtorRecord(int myInt) + { + MyInt = myInt; + } + + public MultiCtorRecord(int myInt, string myString) // This constructor will be used + : this(myInt) + { + MyString = myString; + } + +} +``` + +# [v7.4.0](#tab/Records-v7-4-0) + +>[!NOTE] +>Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. + +Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). + +Example for record types: + +```csharp +class Person { + public string Name { get; } + public int Age { get; } + + public Person(string name, int age) { + this.Name = name; + this.Age = age; + } +} + +var src = new { Name = "Mapster", Age = 3 }; +var target = src.Adapt(); +``` +--- + +### Support additional mapping features: + +| Mapping features | v7.4.0 | v10.0 | +|:-----------------|:------:|:-----:| +|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | +|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | +|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | From e34d6599429461bc41cdc146fc0eeeec676dc04d Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:42:39 +0500 Subject: [PATCH 07/13] --Duplicate .\Data-types.md history into .\data-types\Mappable-Objects.md --- .../mapping/{Data-types.md => data-types/Mappable-Objects.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/articles/mapping/{Data-types.md => data-types/Mappable-Objects.md} (100%) diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/data-types/Mappable-Objects.md similarity index 100% rename from docs/articles/mapping/Data-types.md rename to docs/articles/mapping/data-types/Mappable-Objects.md From c075df53470a62dfe0f83534ba09804c77d0f458 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:42:39 +0500 Subject: [PATCH 08/13] --Restore .\Data-types.md --- docs/articles/mapping/Data-types.md | 192 ++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md new file mode 100644 index 00000000..c139ee0c --- /dev/null +++ b/docs/articles/mapping/Data-types.md @@ -0,0 +1,192 @@ +--- +uid: Mapster.Mapping.DataTypes +title: "Mapping - Data Types" +--- + +## Primitives + +Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. + +```csharp +decimal i = 123.Adapt(); //equal to (decimal)123; +``` + +## Enums + +Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. +The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. + +In Mapster, flagged enums are also supported. + +```csharp +var e = "Read, Write, Delete".Adapt(); +//FileShare.Read | FileShare.Write | FileShare.Delete +``` + +For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: + +```csharp +TypeAdapterConfig.GlobalSettings.Default + .EnumMappingStrategy(EnumMappingStrategy.ByName); +``` + +## Strings + +When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. + +```csharp +var s = 123.Adapt(); //equal to 123.ToString(); +var i = "123".Adapt(); //equal to int.Parse("123"); +``` + +## Collections + +This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... + +```csharp +var list = db.Pocos.ToList(); +var target = list.Adapt>(); +``` + +## Mappable Objects + +Mapster can map two different objects using the following rules: + +- Source and destination property names are the same. Ex: `dest.Name = src.Name` +- Source has get method. Ex: `dest.Name = src.GetName()` +- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` + +Example: + +```csharp +class Staff { + public string Name { get; set; } + public int GetAge() { + return (DateTime.Now - this.BirthDate).TotalDays / 365.25; + } + public Staff Supervisor { get; set; } + ... +} + +struct StaffDto { + public string Name { get; set; } + public int Age { get; set; } + public string SupervisorName { get; set; } +} + +var dto = staff.Adapt(); +//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name +``` + +**Mappable Object types are included:** + +- POCO classes +- POCO structs +- POCO interfaces +- Dictionary type implement `IDictionary` +- Record types (either class, struct, and interface) + +Example for object to dictionary: + +```csharp +var point = new { X = 2, Y = 3 }; +var dict = point.Adapt>(); +dict["Y"].ShouldBe(3); +``` + +## Record types + +>[!IMPORTANT] +> Mapster treats Record type as an immutable type. +> Only a Nondestructive mutation - creating a new object with modified properties. +> +> ```csharp +> var result = source.adapt(data) +>//equal var result = data with { X = source.X.Adapt(), ...} +>``` + +### Features and Limitations: + +# [v10.0](#tab/Records-v10) + +>[!NOTE] +> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. +> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. + + +#### Using default value in constuctor param + +If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. + +Example: + +```csharp + +class SourceData +{ + public string MyString {get; set;} +} + +record RecordDestination(int myInt, string myString); + +var result = source.Adapt() + +// equal var result = new RecordDestination (default(int),source.myString) + +``` + +#### MultiConstructor Record types + +If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. + +Example: + +```csharp +record MultiCtorRecord +{ + public MultiCtorRecord(int myInt) + { + MyInt = myInt; + } + + public MultiCtorRecord(int myInt, string myString) // This constructor will be used + : this(myInt) + { + MyString = myString; + } + +} +``` + +# [v7.4.0](#tab/Records-v7-4-0) + +>[!NOTE] +>Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. + +Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). + +Example for record types: + +```csharp +class Person { + public string Name { get; } + public int Age { get; } + + public Person(string name, int age) { + this.Name = name; + this.Age = age; + } +} + +var src = new { Name = "Mapster", Age = 3 }; +var target = src.Adapt(); +``` +--- + +### Support additional mapping features: + +| Mapping features | v7.4.0 | v10.0 | +|:-----------------|:------:|:-----:| +|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | +|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | +|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | From 15904682d87b5760a4204cdc1e99dd83af8c7d69 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:42:56 +0500 Subject: [PATCH 09/13] --Duplicate .\Data-types.md history into .\data-types\Collections.md --- .../articles/mapping/{Data-types.md => data-types/Collections.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/articles/mapping/{Data-types.md => data-types/Collections.md} (100%) diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/data-types/Collections.md similarity index 100% rename from docs/articles/mapping/Data-types.md rename to docs/articles/mapping/data-types/Collections.md From 7edece503850516b415444a3fccfba5145fc6bf1 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:42:56 +0500 Subject: [PATCH 10/13] --Restore .\Data-types.md --- docs/articles/mapping/Data-types.md | 192 ++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md new file mode 100644 index 00000000..c139ee0c --- /dev/null +++ b/docs/articles/mapping/Data-types.md @@ -0,0 +1,192 @@ +--- +uid: Mapster.Mapping.DataTypes +title: "Mapping - Data Types" +--- + +## Primitives + +Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. + +```csharp +decimal i = 123.Adapt(); //equal to (decimal)123; +``` + +## Enums + +Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. +The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. + +In Mapster, flagged enums are also supported. + +```csharp +var e = "Read, Write, Delete".Adapt(); +//FileShare.Read | FileShare.Write | FileShare.Delete +``` + +For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: + +```csharp +TypeAdapterConfig.GlobalSettings.Default + .EnumMappingStrategy(EnumMappingStrategy.ByName); +``` + +## Strings + +When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. + +```csharp +var s = 123.Adapt(); //equal to 123.ToString(); +var i = "123".Adapt(); //equal to int.Parse("123"); +``` + +## Collections + +This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... + +```csharp +var list = db.Pocos.ToList(); +var target = list.Adapt>(); +``` + +## Mappable Objects + +Mapster can map two different objects using the following rules: + +- Source and destination property names are the same. Ex: `dest.Name = src.Name` +- Source has get method. Ex: `dest.Name = src.GetName()` +- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` + +Example: + +```csharp +class Staff { + public string Name { get; set; } + public int GetAge() { + return (DateTime.Now - this.BirthDate).TotalDays / 365.25; + } + public Staff Supervisor { get; set; } + ... +} + +struct StaffDto { + public string Name { get; set; } + public int Age { get; set; } + public string SupervisorName { get; set; } +} + +var dto = staff.Adapt(); +//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name +``` + +**Mappable Object types are included:** + +- POCO classes +- POCO structs +- POCO interfaces +- Dictionary type implement `IDictionary` +- Record types (either class, struct, and interface) + +Example for object to dictionary: + +```csharp +var point = new { X = 2, Y = 3 }; +var dict = point.Adapt>(); +dict["Y"].ShouldBe(3); +``` + +## Record types + +>[!IMPORTANT] +> Mapster treats Record type as an immutable type. +> Only a Nondestructive mutation - creating a new object with modified properties. +> +> ```csharp +> var result = source.adapt(data) +>//equal var result = data with { X = source.X.Adapt(), ...} +>``` + +### Features and Limitations: + +# [v10.0](#tab/Records-v10) + +>[!NOTE] +> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. +> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. + + +#### Using default value in constuctor param + +If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. + +Example: + +```csharp + +class SourceData +{ + public string MyString {get; set;} +} + +record RecordDestination(int myInt, string myString); + +var result = source.Adapt() + +// equal var result = new RecordDestination (default(int),source.myString) + +``` + +#### MultiConstructor Record types + +If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. + +Example: + +```csharp +record MultiCtorRecord +{ + public MultiCtorRecord(int myInt) + { + MyInt = myInt; + } + + public MultiCtorRecord(int myInt, string myString) // This constructor will be used + : this(myInt) + { + MyString = myString; + } + +} +``` + +# [v7.4.0](#tab/Records-v7-4-0) + +>[!NOTE] +>Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. + +Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). + +Example for record types: + +```csharp +class Person { + public string Name { get; } + public int Age { get; } + + public Person(string name, int age) { + this.Name = name; + this.Age = age; + } +} + +var src = new { Name = "Mapster", Age = 3 }; +var target = src.Adapt(); +``` +--- + +### Support additional mapping features: + +| Mapping features | v7.4.0 | v10.0 | +|:-----------------|:------:|:-----:| +|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | +|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | +|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | From 7cb1f6d42b6b8d569c8a19a2968d60764ce9ee60 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:47:47 +0500 Subject: [PATCH 11/13] fix(docs): copy data to new articles --- .../mapping/data-types/Collections.md | 185 +---------------- .../mapping/data-types/Mappable-Objects.md | 146 +------------ .../mapping/data-types/Mapping-types.md | 192 ------------------ .../mapping/data-types/Primitive-types.md | 158 +------------- .../mapping/data-types/Record-types.md | 95 +-------- 5 files changed, 10 insertions(+), 766 deletions(-) delete mode 100644 docs/articles/mapping/data-types/Mapping-types.md diff --git a/docs/articles/mapping/data-types/Collections.md b/docs/articles/mapping/data-types/Collections.md index c139ee0c..a3d2d669 100644 --- a/docs/articles/mapping/data-types/Collections.md +++ b/docs/articles/mapping/data-types/Collections.md @@ -1,44 +1,8 @@ --- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" +uid: Mapster.Mapping.DataTypes.Collections +title: "Mapping - Collections" --- -## Primitives - -Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. - -```csharp -decimal i = 123.Adapt(); //equal to (decimal)123; -``` - -## Enums - -Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. -The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. - -In Mapster, flagged enums are also supported. - -```csharp -var e = "Read, Write, Delete".Adapt(); -//FileShare.Read | FileShare.Write | FileShare.Delete -``` - -For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: - -```csharp -TypeAdapterConfig.GlobalSettings.Default - .EnumMappingStrategy(EnumMappingStrategy.ByName); -``` - -## Strings - -When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. - -```csharp -var s = 123.Adapt(); //equal to 123.ToString(); -var i = "123".Adapt(); //equal to int.Parse("123"); -``` - ## Collections This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... @@ -46,147 +10,4 @@ This includes mapping among lists, arrays, collections, dictionary including var ```csharp var list = db.Pocos.ToList(); var target = list.Adapt>(); -``` - -## Mappable Objects - -Mapster can map two different objects using the following rules: - -- Source and destination property names are the same. Ex: `dest.Name = src.Name` -- Source has get method. Ex: `dest.Name = src.GetName()` -- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` - -Example: - -```csharp -class Staff { - public string Name { get; set; } - public int GetAge() { - return (DateTime.Now - this.BirthDate).TotalDays / 365.25; - } - public Staff Supervisor { get; set; } - ... -} - -struct StaffDto { - public string Name { get; set; } - public int Age { get; set; } - public string SupervisorName { get; set; } -} - -var dto = staff.Adapt(); -//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name -``` - -**Mappable Object types are included:** - -- POCO classes -- POCO structs -- POCO interfaces -- Dictionary type implement `IDictionary` -- Record types (either class, struct, and interface) - -Example for object to dictionary: - -```csharp -var point = new { X = 2, Y = 3 }; -var dict = point.Adapt>(); -dict["Y"].ShouldBe(3); -``` - -## Record types - ->[!IMPORTANT] -> Mapster treats Record type as an immutable type. -> Only a Nondestructive mutation - creating a new object with modified properties. -> -> ```csharp -> var result = source.adapt(data) ->//equal var result = data with { X = source.X.Adapt(), ...} ->``` - -### Features and Limitations: - -# [v10.0](#tab/Records-v10) - ->[!NOTE] -> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. -> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. - - -#### Using default value in constuctor param - -If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. - -Example: - -```csharp - -class SourceData -{ - public string MyString {get; set;} -} - -record RecordDestination(int myInt, string myString); - -var result = source.Adapt() - -// equal var result = new RecordDestination (default(int),source.myString) - -``` - -#### MultiConstructor Record types - -If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. - -Example: - -```csharp -record MultiCtorRecord -{ - public MultiCtorRecord(int myInt) - { - MyInt = myInt; - } - - public MultiCtorRecord(int myInt, string myString) // This constructor will be used - : this(myInt) - { - MyString = myString; - } - -} -``` - -# [v7.4.0](#tab/Records-v7-4-0) - ->[!NOTE] ->Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. - -Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). - -Example for record types: - -```csharp -class Person { - public string Name { get; } - public int Age { get; } - - public Person(string name, int age) { - this.Name = name; - this.Age = age; - } -} - -var src = new { Name = "Mapster", Age = 3 }; -var target = src.Adapt(); -``` ---- - -### Support additional mapping features: - -| Mapping features | v7.4.0 | v10.0 | -|:-----------------|:------:|:-----:| -|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | -|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | -|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | +``` \ No newline at end of file diff --git a/docs/articles/mapping/data-types/Mappable-Objects.md b/docs/articles/mapping/data-types/Mappable-Objects.md index c139ee0c..73c059d0 100644 --- a/docs/articles/mapping/data-types/Mappable-Objects.md +++ b/docs/articles/mapping/data-types/Mappable-Objects.md @@ -1,53 +1,8 @@ --- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" +uid: Mapster.Mapping.DataTypes.Overview +title: "Mapping - Mappable Objects" --- -## Primitives - -Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. - -```csharp -decimal i = 123.Adapt(); //equal to (decimal)123; -``` - -## Enums - -Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. -The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. - -In Mapster, flagged enums are also supported. - -```csharp -var e = "Read, Write, Delete".Adapt(); -//FileShare.Read | FileShare.Write | FileShare.Delete -``` - -For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: - -```csharp -TypeAdapterConfig.GlobalSettings.Default - .EnumMappingStrategy(EnumMappingStrategy.ByName); -``` - -## Strings - -When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. - -```csharp -var s = 123.Adapt(); //equal to 123.ToString(); -var i = "123".Adapt(); //equal to int.Parse("123"); -``` - -## Collections - -This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... - -```csharp -var list = db.Pocos.ToList(); -var target = list.Adapt>(); -``` - ## Mappable Objects Mapster can map two different objects using the following rules: @@ -93,100 +48,3 @@ var point = new { X = 2, Y = 3 }; var dict = point.Adapt>(); dict["Y"].ShouldBe(3); ``` - -## Record types - ->[!IMPORTANT] -> Mapster treats Record type as an immutable type. -> Only a Nondestructive mutation - creating a new object with modified properties. -> -> ```csharp -> var result = source.adapt(data) ->//equal var result = data with { X = source.X.Adapt(), ...} ->``` - -### Features and Limitations: - -# [v10.0](#tab/Records-v10) - ->[!NOTE] -> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. -> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. - - -#### Using default value in constuctor param - -If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. - -Example: - -```csharp - -class SourceData -{ - public string MyString {get; set;} -} - -record RecordDestination(int myInt, string myString); - -var result = source.Adapt() - -// equal var result = new RecordDestination (default(int),source.myString) - -``` - -#### MultiConstructor Record types - -If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. - -Example: - -```csharp -record MultiCtorRecord -{ - public MultiCtorRecord(int myInt) - { - MyInt = myInt; - } - - public MultiCtorRecord(int myInt, string myString) // This constructor will be used - : this(myInt) - { - MyString = myString; - } - -} -``` - -# [v7.4.0](#tab/Records-v7-4-0) - ->[!NOTE] ->Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. - -Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). - -Example for record types: - -```csharp -class Person { - public string Name { get; } - public int Age { get; } - - public Person(string name, int age) { - this.Name = name; - this.Age = age; - } -} - -var src = new { Name = "Mapster", Age = 3 }; -var target = src.Adapt(); -``` ---- - -### Support additional mapping features: - -| Mapping features | v7.4.0 | v10.0 | -|:-----------------|:------:|:-----:| -|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | -|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | -|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | diff --git a/docs/articles/mapping/data-types/Mapping-types.md b/docs/articles/mapping/data-types/Mapping-types.md deleted file mode 100644 index c139ee0c..00000000 --- a/docs/articles/mapping/data-types/Mapping-types.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" ---- - -## Primitives - -Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. - -```csharp -decimal i = 123.Adapt(); //equal to (decimal)123; -``` - -## Enums - -Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. -The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. - -In Mapster, flagged enums are also supported. - -```csharp -var e = "Read, Write, Delete".Adapt(); -//FileShare.Read | FileShare.Write | FileShare.Delete -``` - -For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: - -```csharp -TypeAdapterConfig.GlobalSettings.Default - .EnumMappingStrategy(EnumMappingStrategy.ByName); -``` - -## Strings - -When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. - -```csharp -var s = 123.Adapt(); //equal to 123.ToString(); -var i = "123".Adapt(); //equal to int.Parse("123"); -``` - -## Collections - -This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... - -```csharp -var list = db.Pocos.ToList(); -var target = list.Adapt>(); -``` - -## Mappable Objects - -Mapster can map two different objects using the following rules: - -- Source and destination property names are the same. Ex: `dest.Name = src.Name` -- Source has get method. Ex: `dest.Name = src.GetName()` -- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` - -Example: - -```csharp -class Staff { - public string Name { get; set; } - public int GetAge() { - return (DateTime.Now - this.BirthDate).TotalDays / 365.25; - } - public Staff Supervisor { get; set; } - ... -} - -struct StaffDto { - public string Name { get; set; } - public int Age { get; set; } - public string SupervisorName { get; set; } -} - -var dto = staff.Adapt(); -//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name -``` - -**Mappable Object types are included:** - -- POCO classes -- POCO structs -- POCO interfaces -- Dictionary type implement `IDictionary` -- Record types (either class, struct, and interface) - -Example for object to dictionary: - -```csharp -var point = new { X = 2, Y = 3 }; -var dict = point.Adapt>(); -dict["Y"].ShouldBe(3); -``` - -## Record types - ->[!IMPORTANT] -> Mapster treats Record type as an immutable type. -> Only a Nondestructive mutation - creating a new object with modified properties. -> -> ```csharp -> var result = source.adapt(data) ->//equal var result = data with { X = source.X.Adapt(), ...} ->``` - -### Features and Limitations: - -# [v10.0](#tab/Records-v10) - ->[!NOTE] -> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. -> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. - - -#### Using default value in constuctor param - -If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. - -Example: - -```csharp - -class SourceData -{ - public string MyString {get; set;} -} - -record RecordDestination(int myInt, string myString); - -var result = source.Adapt() - -// equal var result = new RecordDestination (default(int),source.myString) - -``` - -#### MultiConstructor Record types - -If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. - -Example: - -```csharp -record MultiCtorRecord -{ - public MultiCtorRecord(int myInt) - { - MyInt = myInt; - } - - public MultiCtorRecord(int myInt, string myString) // This constructor will be used - : this(myInt) - { - MyString = myString; - } - -} -``` - -# [v7.4.0](#tab/Records-v7-4-0) - ->[!NOTE] ->Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. - -Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). - -Example for record types: - -```csharp -class Person { - public string Name { get; } - public int Age { get; } - - public Person(string name, int age) { - this.Name = name; - this.Age = age; - } -} - -var src = new { Name = "Mapster", Age = 3 }; -var target = src.Adapt(); -``` ---- - -### Support additional mapping features: - -| Mapping features | v7.4.0 | v10.0 | -|:-----------------|:------:|:-----:| -|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | -|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | -|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | diff --git a/docs/articles/mapping/data-types/Primitive-types.md b/docs/articles/mapping/data-types/Primitive-types.md index c139ee0c..00750bbe 100644 --- a/docs/articles/mapping/data-types/Primitive-types.md +++ b/docs/articles/mapping/data-types/Primitive-types.md @@ -1,6 +1,6 @@ --- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" +uid: Mapster.Mapping.DataTypes.Primitives +title: "Mapping - Primitive Types" --- ## Primitives @@ -37,156 +37,4 @@ When Mapster maps other types to string, Mapster will use `ToString` method. And ```csharp var s = 123.Adapt(); //equal to 123.ToString(); var i = "123".Adapt(); //equal to int.Parse("123"); -``` - -## Collections - -This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... - -```csharp -var list = db.Pocos.ToList(); -var target = list.Adapt>(); -``` - -## Mappable Objects - -Mapster can map two different objects using the following rules: - -- Source and destination property names are the same. Ex: `dest.Name = src.Name` -- Source has get method. Ex: `dest.Name = src.GetName()` -- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` - -Example: - -```csharp -class Staff { - public string Name { get; set; } - public int GetAge() { - return (DateTime.Now - this.BirthDate).TotalDays / 365.25; - } - public Staff Supervisor { get; set; } - ... -} - -struct StaffDto { - public string Name { get; set; } - public int Age { get; set; } - public string SupervisorName { get; set; } -} - -var dto = staff.Adapt(); -//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name -``` - -**Mappable Object types are included:** - -- POCO classes -- POCO structs -- POCO interfaces -- Dictionary type implement `IDictionary` -- Record types (either class, struct, and interface) - -Example for object to dictionary: - -```csharp -var point = new { X = 2, Y = 3 }; -var dict = point.Adapt>(); -dict["Y"].ShouldBe(3); -``` - -## Record types - ->[!IMPORTANT] -> Mapster treats Record type as an immutable type. -> Only a Nondestructive mutation - creating a new object with modified properties. -> -> ```csharp -> var result = source.adapt(data) ->//equal var result = data with { X = source.X.Adapt(), ...} ->``` - -### Features and Limitations: - -# [v10.0](#tab/Records-v10) - ->[!NOTE] -> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. -> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. - - -#### Using default value in constuctor param - -If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. - -Example: - -```csharp - -class SourceData -{ - public string MyString {get; set;} -} - -record RecordDestination(int myInt, string myString); - -var result = source.Adapt() - -// equal var result = new RecordDestination (default(int),source.myString) - -``` - -#### MultiConstructor Record types - -If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. - -Example: - -```csharp -record MultiCtorRecord -{ - public MultiCtorRecord(int myInt) - { - MyInt = myInt; - } - - public MultiCtorRecord(int myInt, string myString) // This constructor will be used - : this(myInt) - { - MyString = myString; - } - -} -``` - -# [v7.4.0](#tab/Records-v7-4-0) - ->[!NOTE] ->Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. - -Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). - -Example for record types: - -```csharp -class Person { - public string Name { get; } - public int Age { get; } - - public Person(string name, int age) { - this.Name = name; - this.Age = age; - } -} - -var src = new { Name = "Mapster", Age = 3 }; -var target = src.Adapt(); -``` ---- - -### Support additional mapping features: - -| Mapping features | v7.4.0 | v10.0 | -|:-----------------|:------:|:-----:| -|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | -|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | -|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | +``` \ No newline at end of file diff --git a/docs/articles/mapping/data-types/Record-types.md b/docs/articles/mapping/data-types/Record-types.md index c139ee0c..c3c1734a 100644 --- a/docs/articles/mapping/data-types/Record-types.md +++ b/docs/articles/mapping/data-types/Record-types.md @@ -1,99 +1,8 @@ --- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" +uid: Mapster.Mapping.DataTypes.Records +title: "Mapping - Record Types" --- -## Primitives - -Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. - -```csharp -decimal i = 123.Adapt(); //equal to (decimal)123; -``` - -## Enums - -Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. -The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. - -In Mapster, flagged enums are also supported. - -```csharp -var e = "Read, Write, Delete".Adapt(); -//FileShare.Read | FileShare.Write | FileShare.Delete -``` - -For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: - -```csharp -TypeAdapterConfig.GlobalSettings.Default - .EnumMappingStrategy(EnumMappingStrategy.ByName); -``` - -## Strings - -When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. - -```csharp -var s = 123.Adapt(); //equal to 123.ToString(); -var i = "123".Adapt(); //equal to int.Parse("123"); -``` - -## Collections - -This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... - -```csharp -var list = db.Pocos.ToList(); -var target = list.Adapt>(); -``` - -## Mappable Objects - -Mapster can map two different objects using the following rules: - -- Source and destination property names are the same. Ex: `dest.Name = src.Name` -- Source has get method. Ex: `dest.Name = src.GetName()` -- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` - -Example: - -```csharp -class Staff { - public string Name { get; set; } - public int GetAge() { - return (DateTime.Now - this.BirthDate).TotalDays / 365.25; - } - public Staff Supervisor { get; set; } - ... -} - -struct StaffDto { - public string Name { get; set; } - public int Age { get; set; } - public string SupervisorName { get; set; } -} - -var dto = staff.Adapt(); -//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name -``` - -**Mappable Object types are included:** - -- POCO classes -- POCO structs -- POCO interfaces -- Dictionary type implement `IDictionary` -- Record types (either class, struct, and interface) - -Example for object to dictionary: - -```csharp -var point = new { X = 2, Y = 3 }; -var dict = point.Adapt>(); -dict["Y"].ShouldBe(3); -``` - ## Record types >[!IMPORTANT] From d3bc57831df667b8de42a2e1359e956202c17527 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 10:57:28 +0500 Subject: [PATCH 12/13] fix(docs): fix links --- docs/articles/mapping/data-types/toc.yml | 13 +++++++++++++ docs/articles/mapping/toc.yml | 4 ++-- 2 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 docs/articles/mapping/data-types/toc.yml diff --git a/docs/articles/mapping/data-types/toc.yml b/docs/articles/mapping/data-types/toc.yml new file mode 100644 index 00000000..cac93d44 --- /dev/null +++ b/docs/articles/mapping/data-types/toc.yml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/dotnet/docfx/main/schemas/toc.schema.json +- name: Mappable Objects + uid: Mapster.Mapping.DataTypes.Overview + href: Mappable-Objects.md +- name: Primitive Types + uid: Mapster.Mapping.DataTypes.Primitives + href: Primitive-types.md +- name: Collections + uid: Mapster.Mapping.DataTypes.Collections + href: Collections.md +- name: Record Types + uid: Mapster.Mapping.DataTypes.Records + href: Record-types.md \ No newline at end of file diff --git a/docs/articles/mapping/toc.yml b/docs/articles/mapping/toc.yml index ab7e7755..b86d614c 100644 --- a/docs/articles/mapping/toc.yml +++ b/docs/articles/mapping/toc.yml @@ -6,8 +6,8 @@ uid: Mapster.Mapping.Mappers href: Mappers.md - name: Data types - uid: Mapster.Mapping.DataTypes - href: Data-types.md + href: data-types/toc.yml + topicHref: xref:Mapster.Mapping.DataTypes - name: Mapping with interface uid: Mapster.Mapping.IMapFromInterface href: Mapping-Configuration-With-IMapFrom-Interface.md \ No newline at end of file From 966589e82f253ff282c374bbaf1c1836288e9168 Mon Sep 17 00:00:00 2001 From: DocSvartz Date: Wed, 8 Apr 2026 11:09:26 +0500 Subject: [PATCH 13/13] fix(docs): drop Data-types.md and fix links --- docs/api/Reference.md | 4 +- docs/articles/mapping/Data-types.md | 192 ---------------------------- docs/articles/mapping/toc.yml | 1 - 3 files changed, 2 insertions(+), 195 deletions(-) delete mode 100644 docs/articles/mapping/Data-types.md diff --git a/docs/api/Reference.md b/docs/api/Reference.md index 9626ce24..bcfe97ed 100644 --- a/docs/api/Reference.md +++ b/docs/api/Reference.md @@ -11,7 +11,7 @@ uid: Mapster.References | `src.Adapt()` | Mapping to new type | [basic](xref:Mapster.Mapping.BasicUsages) | | `src.Adapt(dest)` | Mapping to existing object | [basic](xref:Mapster.Mapping.BasicUsages) | | `query.ProjectToType()` | Mapping from queryable | [basic](xref:Mapster.Mapping.BasicUsages) | -| | Convention & Data type support | [data types](xref:Mapster.Mapping.DataTypes) | +| | Convention & Data type support | [data types](xref:Mapster.Mapping.DataTypes.Overview) | ### Mapper instance (for dependency injection) @@ -84,7 +84,7 @@ uid: Mapster.References | `BeforeMapping` | Add steps before mapping start | | [before-after](xref:Mapster.Settings.BeforeAfterMapping) | | `ConstructUsing` | Define how to create object | x | [constructor](xref:Mapster.Settings.ConstructorMapping) | | `EnableNonPublicMembers` | Mapping non-public properties | | [non-public](xref:Mapster.Settings.Custom.NonPublicMembers) | -| `EnumMappingStrategy` | Choose whether mapping enum by value or by name | | [data types](xref:Mapster.Mapping.DataTypes) | +| `EnumMappingStrategy` | Choose whether mapping enum by value or by name | | [data types](xref:Mapster.Mapping.DataTypes.Primitives) | | `Fork` | Add new settings without side effect on main config | x | [nested mapping](xref:Mapster.Configuration.NestedMapping) | | `GetMemberName` | Define how to resolve property name | x | [custom naming](xref:Mapster.Settings.Custom.NamingConvention) | | `Ignore` | Ignore specific properties | x | [ignore](xref:Mapster.Settings.Custom.IgnoringMembers) | diff --git a/docs/articles/mapping/Data-types.md b/docs/articles/mapping/Data-types.md deleted file mode 100644 index c139ee0c..00000000 --- a/docs/articles/mapping/Data-types.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -uid: Mapster.Mapping.DataTypes -title: "Mapping - Data Types" ---- - -## Primitives - -Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster. - -```csharp -decimal i = 123.Adapt(); //equal to (decimal)123; -``` - -## Enums - -Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner. -The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included. If the string is null or empty, the enum will initialize to the first enum value. - -In Mapster, flagged enums are also supported. - -```csharp -var e = "Read, Write, Delete".Adapt(); -//FileShare.Read | FileShare.Write | FileShare.Delete -``` - -For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by: - -```csharp -TypeAdapterConfig.GlobalSettings.Default - .EnumMappingStrategy(EnumMappingStrategy.ByName); -``` - -## Strings - -When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method. - -```csharp -var s = 123.Adapt(); //equal to 123.ToString(); -var i = "123".Adapt(); //equal to int.Parse("123"); -``` - -## Collections - -This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList`, `ICollection`, `IEnumerable`, `ISet`, `IDictionary` etc... - -```csharp -var list = db.Pocos.ToList(); -var target = list.Adapt>(); -``` - -## Mappable Objects - -Mapster can map two different objects using the following rules: - -- Source and destination property names are the same. Ex: `dest.Name = src.Name` -- Source has get method. Ex: `dest.Name = src.GetName()` -- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name` - -Example: - -```csharp -class Staff { - public string Name { get; set; } - public int GetAge() { - return (DateTime.Now - this.BirthDate).TotalDays / 365.25; - } - public Staff Supervisor { get; set; } - ... -} - -struct StaffDto { - public string Name { get; set; } - public int Age { get; set; } - public string SupervisorName { get; set; } -} - -var dto = staff.Adapt(); -//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name -``` - -**Mappable Object types are included:** - -- POCO classes -- POCO structs -- POCO interfaces -- Dictionary type implement `IDictionary` -- Record types (either class, struct, and interface) - -Example for object to dictionary: - -```csharp -var point = new { X = 2, Y = 3 }; -var dict = point.Adapt>(); -dict["Y"].ShouldBe(3); -``` - -## Record types - ->[!IMPORTANT] -> Mapster treats Record type as an immutable type. -> Only a Nondestructive mutation - creating a new object with modified properties. -> -> ```csharp -> var result = source.adapt(data) ->//equal var result = data with { X = source.X.Adapt(), ...} ->``` - -### Features and Limitations: - -# [v10.0](#tab/Records-v10) - ->[!NOTE] -> By default, all [C# Records](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record) are defined as a record type. -> Limitations by count of constructors and constructor parameters used in Mapster version 7.4.0 do not apply. - - -#### Using default value in constuctor param - -If the source type does not contain members that can be used as constructor parameters, then will be used the default values ​​for the parameter type. - -Example: - -```csharp - -class SourceData -{ - public string MyString {get; set;} -} - -record RecordDestination(int myInt, string myString); - -var result = source.Adapt() - -// equal var result = new RecordDestination (default(int),source.myString) - -``` - -#### MultiConstructor Record types - -If there is more than one constructor, by default, mapping will be performed on the constructor with the largest number of parameters. - -Example: - -```csharp -record MultiCtorRecord -{ - public MultiCtorRecord(int myInt) - { - MyInt = myInt; - } - - public MultiCtorRecord(int myInt, string myString) // This constructor will be used - : this(myInt) - { - MyString = myString; - } - -} -``` - -# [v7.4.0](#tab/Records-v7-4-0) - ->[!NOTE] ->Record type must not have a setter and have only one non-empty constructor, and all parameter names must match with properties. - -Otherwise you need to add [`MapToConstructor` configuration](xref:Mapster.Settings.ConstructorMapping#map-to-constructor). - -Example for record types: - -```csharp -class Person { - public string Name { get; } - public int Age { get; } - - public Person(string name, int age) { - this.Name = name; - this.Age = age; - } -} - -var src = new { Name = "Mapster", Age = 3 }; -var target = src.Adapt(); -``` ---- - -### Support additional mapping features: - -| Mapping features | v7.4.0 | v10.0 | -|:-----------------|:------:|:-----:| -|[Custom constructor mapping](xref:Mapster.Settings.ConstructorMapping)| - | ✅ | -|[Ignore](xref:Mapster.Settings.Custom.IgnoringMembers#ignore-extension-method)| - | ✅ | -|[IgnoreNullValues](xref:Mapster.Settings.Custom.IgnoringMembers#ignorenullvalues-extension-method)| - | ✅ | diff --git a/docs/articles/mapping/toc.yml b/docs/articles/mapping/toc.yml index b86d614c..a69e162c 100644 --- a/docs/articles/mapping/toc.yml +++ b/docs/articles/mapping/toc.yml @@ -7,7 +7,6 @@ href: Mappers.md - name: Data types href: data-types/toc.yml - topicHref: xref:Mapster.Mapping.DataTypes - name: Mapping with interface uid: Mapster.Mapping.IMapFromInterface href: Mapping-Configuration-With-IMapFrom-Interface.md \ No newline at end of file