Merge remote-tracking branch 'origin/dev'

Author: ismcagdas

blog-posts/en/images/Blog/zero-react-release_05bf.webp

@@ -92,33 +92,37 @@ This will allow Elsa to use ASP.NET Zero application for handling HTTP activitie
 
 There are some special configuration points here which doesn't exist in default Elsa document. Let's take a look at those sections one by one;
 
-#### AutoMapper
+#### Object Mapping
+
+ASP.NET Zero uses [Mapperly](https://mapperly.riok.app/) for object-to-object mappings, which generates mapping code at compile-time. Elsa, on the other hand, uses AutoMapper internally for its own mappings.
+
+To allow both to coexist, we configure Elsa to manage its own AutoMapper instance:
 
 ````c#
 elsa.UseAutoMapper(() => { });
 ````
 
-Both Elsa and ASP.NET Boilerplate creates a `MapperConfiguration` and uses it to create an `IMapper`. Because of this, if we don't add this line to Elsa configuration, the app will only use Elsa's **AutoMapper** configuration. But, after making this configuration, we need to configure Elsa's AutoMapper mappings in our app manually. In order to do this, go to `*WebMvcModule` and add below lines to its `PreInitialize` method.
+This configuration tells Elsa to use an empty AutoMapper configuration, allowing it to set up its internal mappings without conflicting with ASP.NET Zero's Mapperly-based mappers.
 
-```
-// ELSA AutoMapper
-Configuration.Modules.AbpAutoMapper().Configurators.Add(config =>
+If you need to create custom mappings for Elsa types in your application, create a dedicated Mapperly mapper:
+
+```csharp
+using Riok.Mapperly.Abstractions;
+using Elsa.Models;
+using Elsa.Services.Models;
+
+[Mapper]
+public partial class ElsaWorkflowMapper
 {
-    // AutoMapperProfile
-    config.CreateMap<IWorkflowBlueprint, WorkflowBlueprintModel>();
-    config.CreateMap<IWorkflowBlueprint, WorkflowBlueprintSummaryModel>();
-    config.CreateMap<IActivityBlueprint, ActivityBlueprintModel>().ConvertUsing<ActivityBlueprintConverter>();
-    config.CreateMap<ICompositeActivityBlueprint, CompositeActivityBlueprintModel>();
-    config.CreateMap<IConnection, ConnectionModel>().ConvertUsing<ConnectionConverter>();
-    config.CreateMap<WorkflowInstance, WorkflowInstanceSummaryModel>();
-    config.CreateMap<WorkflowDefinition, WorkflowDefinitionSummaryModel>();
-    
-    // CloningProfile
-    config.CreateMap<WorkflowDefinition, WorkflowDefinition>();
-    config.CreateMap<WorkflowInstance, WorkflowInstance>();
-});
+    public partial WorkflowBlueprintModel Map(IWorkflowBlueprint source);
+    public partial WorkflowBlueprintSummaryModel MapToSummary(IWorkflowBlueprint source);
+    public partial WorkflowInstanceSummaryModel Map(WorkflowInstance source);
+    public partial WorkflowDefinitionSummaryModel Map(WorkflowDefinition source);
+}
 ```
 
+> **Note:** Elsa's internal operations use its own AutoMapper configuration. The mapper above is only needed if you want to map Elsa types in your own application code.
+
 #### API Versioning
 
 ```

docs/en/Core-Mvc-Elsa-Integration.md

@@ -37,9 +37,32 @@ public class PhoneConsts
 }
 ```
 
+First, create a mapper for the phone operations. Create `AddPhoneInputToPhoneMapper.cs`:
+
+```csharp
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class AddPhoneInputToPhoneMapper
+{
+    public partial Phone Map(AddPhoneInput input);
+}
+```
+
 Now, we can implement these methods:
 
 ```csharp
+private readonly IRepository<Person> _personRepository;
+private readonly IRepository<Phone, long> _phoneRepository;
+
+public PersonAppService(IRepository<Person> personRepository, IRepository<Phone, long> phoneRepository)
+{
+    _personRepository = personRepository;
+    _phoneRepository = phoneRepository;
+}
+
 [AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_EditPerson)]
 public async Task DeletePhone(EntityDto<long> input)
 {
@@ -62,12 +85,6 @@ public async Task<PhoneInPersonListDto> AddPhone(AddPhoneInput input)
 }
 ```
 
-Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
-
-```csharp
-configuration.CreateMap<AddPhoneInput, Phone>();
-```
-
 A permission should have a unique name. We define permission names as constant strings in **AppPermissions** class. It's a simple constant string:
 
 ```csharp

docs/en/Developing-Step-By-Step-Angular-Adding-AddPhone-DeletePhone-Methods.md

@@ -25,14 +25,24 @@ public class PhoneInPersonListDto : CreationAuditedEntityDto<long>
 }
 ```
 
-Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
+Then we create a mapper for Phone to PhoneInPersonListDto. Create a new file `PhoneToPhoneInPersonListDtoMapper.cs`:
 
 ```csharp
-configuration.CreateMap<Phone, PhoneInPersonListDto>();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class PhoneToPhoneInPersonListDtoMapper
+{
+    public partial PhoneInPersonListDto Map(Phone phone);
+    public partial Collection<PhoneInPersonListDto> Map(ICollection<Phone> phones);
+}
 ```
 
-So, added also a DTO to transfer phone numbers and mapped from Phone
-entity. Now, we can change GetPeople method to get Phones from database:
+Mapperly will automatically map the nested `Phones` collection since both the source and target property names match.
+
+Now, we can change GetPeople method to get Phones from database:
 
 ```csharp
 public ListResultDto<PersonListDto> GetPeople(GetPeopleInput input)

docs/en/Developing-Step-By-Step-Angular-Changing-GetPeople-Method.md

@@ -31,14 +31,21 @@ public class CreatePersonInput
 }
 ```
 
-Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
+Then we create a mapper for CreatePersonInput to Person. Create a new file `CreatePersonInputToPersonMapper.cs`:
 
 ```csharp
-configuration.CreateMap<CreatePersonInput, Person>();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class CreatePersonInputToPersonMapper
+{
+    public partial Person Map(CreatePersonInput input);
+}
 ```
 
-**CreatePersonInput** is mapped to **Person** entity (comment out
-related line in CustomDtoMapper.cs and we will use mapping below).
+**CreatePersonInput** is mapped to **Person** entity using Mapperly.
 All properties are decorated with **data annotation attributes**
 to provide automatic
 **[validation](https://aspnetboilerplate.com/Pages/Documents/Validating-Data-Transfer-Objects)**.
@@ -67,7 +74,7 @@ public async Task CreatePerson(CreatePersonInput input)
 ```
 
 A Person entity is created by mapping given input, then inserted to
-database. We used **async/await** pattern here. All methods in ASP.NET
+database. The `ObjectMapper` uses the Mapperly-generated mapper internally. We used **async/await** pattern here. All methods in ASP.NET
 Zero startup project is **async**. It's advised to use async/await
 wherever possible.
 

docs/en/Developing-Step-By-Step-Angular-Creating-New-Person.md

@@ -34,18 +34,25 @@ public class PersonListDto : FullAuditedEntityDto
 }
 ```
 
-**CustomDtoMapper.cs** is used to create mapping from **Person** to **PersonListDto**. **FullAuditedEntityDto** is inherited to implement audit properties automatically. See [application service](https://aspnetboilerplate.com/Pages/Documents/Application-Services) and [DTO](https://aspnetboilerplate.com/Pages/Documents/Data-Transfer-Objects) documentations for more information. We are adding the following mappings.
+We need to create a mapper to convert **Person** to **PersonListDto**. **FullAuditedEntityDto** is inherited to implement audit properties automatically. See [application service](https://aspnetboilerplate.com/Pages/Documents/Application-Services) and [DTO](https://aspnetboilerplate.com/Pages/Documents/Data-Transfer-Objects) documentations for more information.
+
+Create a new file `PersonToPersonListDtoMapper.cs` in the **.Application** project:
 
 ```csharp
-...
-// PhoneBook (we will comment out other lines when the new DTOs are added)
-configuration.CreateMap<Person, PersonListDto>();
-//configuration.CreateMap<AddPhoneInput, Phone>();
-//configuration.CreateMap<CreatePersonInput, Person>();
-//configuration.CreateMap<Person, GetPersonForEditOutput>();
-//configuration.CreateMap<Phone, PhoneInPersonListDto>();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class PersonToPersonListDtoMapper
+{
+    public partial PersonListDto Map(Person person);
+    public partial List<PersonListDto> Map(List<Person> persons);
+}
 ```
 
+ASP.NET Zero automatically discovers and registers this mapper class.
+
 After defining interface, we can implement it as shown below: (in **.Application** project)
 
 ```csharp
@@ -85,9 +92,9 @@ public class PersonAppService : PhoneBookDemoAppServiceBase, IPersonAppService
 }
 ```
 
-We're injecting **person repository** (it's automatically created by ABP) and using it to filter and get people from database. 
+We're injecting **person repository** (it's automatically created by ABP).
 
-**WhereIf** is an extension method here (defined in Abp.Linq.Extensions namespace). It performs Where condition, only if filter is not null or empty. **IsNullOrEmpty** is also an extension method (defined in Abp.Extensions namespace). ABP has many similar shortcut extension methods. **ObjectMapper.Map** method automatically converts list of Person entities to list of PersonListDto objects with using configurations in **CustomDtoMapper.cs** in **.Application** project.
+**WhereIf** is an extension method here (defined in Abp.Linq.Extensions namespace). It performs Where condition, only if filter is not null or empty. **IsNullOrEmpty** is also an extension method (defined in Abp.Extensions namespace). ABP has many similar shortcut extension methods. **ObjectMapper.Map** automatically converts list of Person entities to list of PersonListDto objects using the Mapperly-generated mapping code internally.
 
 ### Connection & Transaction Management
 

docs/en/Developing-Step-By-Step-Angular-Creating-Person-Application-Service.md

@@ -31,14 +31,21 @@ public class CreatePersonInput
 }
 ```
 
-Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
+Then we create a mapper for CreatePersonInput to Person. Create a new file `CreatePersonInputToPersonMapper.cs`:
 
 ```csharp
-configuration.CreateMap<CreatePersonInput, Person>();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class CreatePersonInputToPersonMapper
+{
+    public partial Person Map(CreatePersonInput input);
+}
 ```
 
-**CreatePersonInput** is mapped to **Person** entity (comment out
-related line in CustomDtoMapper.cs and we will use mapping below).
+**CreatePersonInput** is mapped to **Person** entity using Mapperly.
 All properties are decorated with **data annotation attributes**
 to provide automatic
 **[validation](https://aspnetboilerplate.com/Pages/Documents/Validating-Data-Transfer-Objects)**.
@@ -67,7 +74,7 @@ public async Task CreatePerson(CreatePersonInput input)
 ```
 
 A Person entity is created by mapping given input, then inserted to
-database. We used **async/await** pattern here. All methods in ASP.NET
+database. The `ObjectMapper` uses the Mapperly-generated mapper internally. We used **async/await** pattern here. All methods in ASP.NET
 Zero startup project is **async**. It's advised to use async/await
 wherever possible.
 

docs/en/Developing-Step-By-Step-Angular-DevExtreme-Creating-New-Person.md

@@ -35,18 +35,25 @@ public class PersonListDto : FullAuditedEntityDto
 }
 ```
 
-**CustomDtoMapper.cs** is used to create mapping from **Person** to **PersonListDto**. **FullAuditedEntityDto** is inherited to implement audit properties automatically. See [application service](https://aspnetboilerplate.com/Pages/Documents/Application-Services) and [DTO](https://aspnetboilerplate.com/Pages/Documents/Data-Transfer-Objects) documentations for more information. We are adding the following mappings.
+We need to create a mapper to convert **Person** to **PersonListDto**. **FullAuditedEntityDto** is inherited to implement audit properties automatically. See [application service](https://aspnetboilerplate.com/Pages/Documents/Application-Services) and [DTO](https://aspnetboilerplate.com/Pages/Documents/Data-Transfer-Objects) documentations for more information.
+
+Create a new file `PersonToPersonListDtoMapper.cs` in the **.Application** project:
 
 ```csharp
-...
-// PhoneBook (we will comment out other lines when the new DTOs are added)
-configuration.CreateMap<Person, PersonListDto>();
-//configuration.CreateMap<AddPhoneInput, Phone>();
-//configuration.CreateMap<CreatePersonInput, Person>();
-//configuration.CreateMap<Person, GetPersonForEditOutput>();
-//configuration.CreateMap<Phone, PhoneInPersonListDto>();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class PersonToPersonListDtoMapper
+{
+    public partial PersonListDto Map(Person person);
+    public partial List<PersonListDto> Map(List<Person> persons);
+}
 ```
 
+ASP.NET Zero automatically discovers and registers this mapper class.
+
 After defining interface, we can implement it as shown below: (in **.Application** project)
 
 ```csharp
@@ -78,9 +85,9 @@ public class PersonAppService : PhoneBookDemoAppServiceBase, IPersonAppService
 }
 ```
 
-We're injecting **person repository** (it's automatically created by ABP) and using it to filter and get people from database. 
+We're injecting **person repository** (it's automatically created by ABP).
 
-**WhereIf** is an extension method here (defined in Abp.Linq.Extensions namespace). It performs Where condition, only if filter is not null or empty. **IsNullOrEmpty** is also an extension method (defined in Abp.Extensions namespace). ABP has many similar shortcut extension methods. **ObjectMapper.Map** method automatically converts list of Person entities to list of PersonListDto objects with using configurations in **CustomDtoMapper.cs** in **.Application** project.
+**WhereIf** is an extension method here (defined in Abp.Linq.Extensions namespace). It performs Where condition, only if filter is not null or empty. **IsNullOrEmpty** is also an extension method (defined in Abp.Extensions namespace). ABP has many similar shortcut extension methods. **ObjectMapper.Map** automatically converts list of Person entities to list of PersonListDto objects using the Mapperly-generated mapping code internally.
 
 ### Connection & Transaction Management
 

docs/en/Developing-Step-By-Step-Angular-DevExtreme-Creating-Person-Application-Service.md

@@ -5,24 +5,10 @@ Now we want to edit name, surname and e-mail of people:
 <img src="images/edit-person-core1.png" alt="Edit Person" class="img-thumbnail" />  
 
 First of all, we create the necessary DTOs to transfer people's id, name,
-surname and e-mail. We can optionally configure auto-mapper, but this is not necessary because all properties match automatically. Then we create the functions in PersonAppService for
+surname and e-mail. Then we create the functions in PersonAppService for
 editing people:  
 
-```csharp 
-[AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_EditPerson)]
-public async Task<GetPersonForEditOutput> GetPersonForEdit( EntityDto<int> input)
-{
-    var person = await _personRepository.GetAsync(input.Id);
-    return ObjectMapper.Map<GetPersonForEditOutput>(person);
-}
-
- [AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_EditPerson)]
- public async Task EditPerson(EditPersonInput input)
- {
-     var person = await _personRepository.FirstOrDefaultAsync(input.Id);
-     ObjectMapper.Map(input, person);
- }
-
+```csharp
 public class GetPersonForEditOutput : EntityDto<int>
 {
     public string Name { get; set; }
@@ -38,11 +24,48 @@ public class EditPersonInput : EntityDto<int>
 }
 ```
 
-Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
+Then we create mappers for the edit operations. Create `PersonToGetPersonForEditOutputMapper.cs`:
+
+```csharp
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class PersonToGetPersonForEditOutputMapper
+{
+    public partial GetPersonForEditOutput Map(Person person);
+}
+```
+
+Create `EditPersonInputToPersonMapper.cs` for updating existing persons:
 
 ```csharp
-configuration.CreateMap<Person, GetPersonForEditOutput>();
-configuration.CreateMap<EditPersonInput, Person>().ReverseMap();
+using Riok.Mapperly.Abstractions;
+
+namespace Acme.PhoneBookDemo.PhoneBook.Mapper;
+
+[Mapper]
+public partial class EditPersonInputToPersonMapper
+{
+    public partial void Map(EditPersonInput input, Person person);
+}
+```
+
+Then use ObjectMapper in the PersonAppService methods:
+
+```csharp
+public async Task<GetPersonForEditOutput> GetPersonForEdit(EntityDto input)
+{
+    var person = await _personRepository.GetAsync(input.Id);
+    return ObjectMapper.Map<GetPersonForEditOutput>(person);
+}
+
+public async Task EditPerson(EditPersonInput input)
+{
+    var person = await _personRepository.GetAsync(input.Id);
+    ObjectMapper.Map(input, person);
+}
 ```
 
 ## View