Rename the query projection API

* IQueryableMapper pairs with IObjectMapper, CreateEntityQueryAsync with CreateFilteredQueryAsync

Author: maliming

docs/en/framework/architecture/domain-driven-design/application-services.md

@@ -444,7 +444,7 @@ These methods are low level methods that can control how to query entities from
 * `ApplyPaging` is used to make paging on the query. If your `TGetListInput` already implements `IPagedResultRequest`, you don't need to override this since the ABP automatically understands it and performs the paging.
 * `ApplySorting` is used to sort (order by...) the query. If your `TGetListInput` already implements the `ISortedResultRequest`, ABP automatically sorts the query. If not, it fallbacks to the `ApplyDefaultSorting` which tries to sort by creation time, if your entity implements the standard `IHasCreationTime` interface.
 * `GetEntityByIdAsync` is used to get an entity by id, which calls `Repository.GetAsync(id)` by default.
-* `GetEntityByIdQueryOrNullAsync` is used to create a query for a single entity by id, which is only needed for the *Query Projection* explained below. It returns `null` if the application service can not create such a query, then `GetEntityByIdAsync` is used.
+* `CreateEntityQueryAsync` is used to create a query for a single entity by id, which is only needed for the *Query Projection* explained below. It returns `null` if the application service can not create such a query, then `GetEntityByIdAsync` is used.
 * `DeleteByIdAsync` is used to delete an entity by id, which calls `Repository.DeleteAsync(id)` by default.
 
 #### Object to Object Mapping
@@ -461,15 +461,15 @@ These methods are used to convert Entities to DTOs and vice verse. They use the
 
 `GetAsync` and `GetListAsync` get the entities from the database, then map them to DTOs in the memory. If your DTO uses only a few properties of a large entity, you can project the query to the DTO instead, so the database returns only the columns you need.
 
-Implement the `IQueryProjectionMapper<TEntity, TDto>` interface to define a projection:
+Implement the `IQueryableMapper<TEntity, TDto>` interface to define a projection:
 
 ````csharp
 using System.Linq;
 using Volo.Abp.ObjectMapping;
 
 namespace MyProject.Books;
 
-public class BookProjector : IQueryProjectionMapper<Book, BookDto>
+public class BookProjector : IQueryableMapper<Book, BookDto>
 {
     public IQueryable<BookDto> ProjectTo(IQueryable<Book> source)
     {
@@ -486,12 +486,12 @@ You don't have to write the `Select` by hand. Both [Mapperly](https://mapperly.r
 
 ABP registers the projection mappers by convention, you don't need to configure anything else. Filters (like soft delete and multi-tenancy), sorting and paging are still applied to the query before the projection.
 
-> The projection replaces the entity based extension points. `GetAsync` doesn't use `GetEntityByIdAsync` and `MapToGetOutputDtoAsync`, `GetListAsync` doesn't use `MapToGetListOutputDtosAsync` anymore. If an application service needs to keep using them, override the `GetProjectionMapper` or `GetListProjectionMapper` property and return `null`:
+> The projection replaces the entity based extension points. `GetAsync` doesn't use `GetEntityByIdAsync` and `MapToGetOutputDtoAsync`, `GetListAsync` doesn't use `MapToGetListOutputDtosAsync` anymore. If an application service needs to keep using them, override the `GetQueryableMapper` or `GetListQueryableMapper` property and return `null`:
 
 ````csharp
 public class BookAppService : CrudAppService<Book, BookDto, Guid>
 {
-    protected override IQueryProjectionMapper<Book, BookDto>? GetProjectionMapper => null;
+    protected override IQueryableMapper<Book, BookDto>? GetQueryableMapper => null;
 
     //...
 }

framework/src/Volo.Abp.Ddd.Application/Volo/Abp/Application/Services/AbstractKeyReadOnlyAppService.cs

@@ -45,18 +45,20 @@ public abstract class AbstractKeyReadOnlyAppService<TEntity, TGetOutputDto, TGet
     protected virtual string? GetListPolicyName { get; set; }
 
     /// <summary>
-    /// <see cref="GetEntityByIdAsync"/> and <see cref="MapToGetOutputDtoAsync"/> are not used
-    /// while a projection mapper is available. Override and return null to keep using them.
+    /// Used by the <see cref="GetAsync"/> to project the query to the <typeparamref name="TGetOutputDto"/>.
+    /// It returns the registered mapper or null by default.
+    /// The <see cref="GetEntityByIdAsync"/> and the <see cref="MapToGetOutputDtoAsync"/> are not used when it returns a mapper.
     /// </summary>
-    protected virtual IQueryProjectionMapper<TEntity, TGetOutputDto>? GetProjectionMapper
-        => LazyServiceProvider.LazyGetService<IQueryProjectionMapper<TEntity, TGetOutputDto>>();
+    protected virtual IQueryableMapper<TEntity, TGetOutputDto>? GetQueryableMapper
+        => LazyServiceProvider.LazyGetService<IQueryableMapper<TEntity, TGetOutputDto>>();
 
     /// <summary>
-    /// <see cref="MapToGetListOutputDtosAsync"/> is not used while a projection mapper is
-    /// available. Override and return null to keep using it.
+    /// Used by the <see cref="GetListAsync"/> to project the query to the <typeparamref name="TGetListOutputDto"/>.
+    /// It returns the registered mapper or null by default.
+    /// The <see cref="MapToGetListOutputDtosAsync"/> is not used when it returns a mapper.
     /// </summary>
-    protected virtual IQueryProjectionMapper<TEntity, TGetListOutputDto>? GetListProjectionMapper
-        => LazyServiceProvider.LazyGetService<IQueryProjectionMapper<TEntity, TGetListOutputDto>>();
+    protected virtual IQueryableMapper<TEntity, TGetListOutputDto>? GetListQueryableMapper
+        => LazyServiceProvider.LazyGetService<IQueryableMapper<TEntity, TGetListOutputDto>>();
 
     protected AbstractKeyReadOnlyAppService(IReadOnlyRepository<TEntity> repository)
     {
@@ -67,10 +69,10 @@ public virtual async Task<TGetOutputDto> GetAsync(TKey id)
     {
         await CheckGetPolicyAsync();
 
-        var projectionMapper = GetProjectionMapper;
+        var projectionMapper = GetQueryableMapper;
         if (projectionMapper != null)
         {
-            var query = await GetEntityByIdQueryOrNullAsync(id);
+            var query = await CreateEntityQueryAsync(id);
             if (query != null)
             {
                 return await AsyncExecuter.FirstOrDefaultAsync(projectionMapper.ProjectTo(query))
@@ -97,7 +99,7 @@ public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetLi
             query = ApplySorting(query, input);
             query = ApplyPaging(query, input);
 
-            var projectionMapper = GetListProjectionMapper;
+            var projectionMapper = GetListQueryableMapper;
             if (projectionMapper != null)
             {
                 entityDtos = await AsyncExecuter.ToListAsync(projectionMapper.ProjectTo(query));
@@ -118,10 +120,11 @@ public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetLi
     protected abstract Task<TEntity> GetEntityByIdAsync(TKey id);
 
     /// <summary>
-    /// Returns null if this application service can not create a query for a single entity.
-    /// <see cref="GetEntityByIdAsync"/> is used in that case.
+    /// Should create a query that selects the entity with the given <paramref name="id"/>.
+    /// It returns null by default, then the <see cref="GetEntityByIdAsync"/> is used instead of the projection.
     /// </summary>
-    protected virtual Task<IQueryable<TEntity>?> GetEntityByIdQueryOrNullAsync(TKey id)
+    /// <param name="id">The id of the entity.</param>
+    protected virtual Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
     {
         return Task.FromResult<IQueryable<TEntity>?>(null);
     }

framework/src/Volo.Abp.Ddd.Application/Volo/Abp/Application/Services/CrudAppService.cs

@@ -84,7 +84,7 @@ protected override async Task<TEntity> GetEntityByIdAsync(TKey id)
         return await Repository.GetAsync(id);
     }
 
-    protected override async Task<IQueryable<TEntity>?> GetEntityByIdQueryOrNullAsync(TKey id)
+    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
     {
         var query = await Repository.GetQueryableAsync();
 

framework/src/Volo.Abp.Ddd.Application/Volo/Abp/Application/Services/ReadOnlyAppService.cs

@@ -47,7 +47,7 @@ protected override async Task<TEntity> GetEntityByIdAsync(TKey id)
         return await Repository.GetAsync(id);
     }
 
-    protected override async Task<IQueryable<TEntity>?> GetEntityByIdQueryOrNullAsync(TKey id)
+    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
     {
         var query = await Repository.GetQueryableAsync();
 

framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/AbpObjectMappingModule.cs

@@ -19,11 +19,11 @@ public override void PreConfigureServices(ServiceConfigurationContext context)
                 ).ConvertAll(t => new ServiceIdentifier(t))
             );
 
-            //Register types for IQueryProjectionMapper<TSource, TDestination> if implements
+            //Register types for IQueryableMapper<TSource, TDestination> if implements
             onServiceExposingContext.ExposedTypes.AddRange(
                 ReflectionHelper.GetImplementedGenericTypes(
                     onServiceExposingContext.ImplementationType,
-                    typeof(IQueryProjectionMapper<,>)
+                    typeof(IQueryableMapper<,>)
                 ).ConvertAll(t => new ServiceIdentifier(t))
             );
         });

framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryProjectionMapper.cs

@@ -0,0 +1,21 @@
+using System.Linq;
+using Volo.Abp.DependencyInjection;
+
+namespace Volo.Abp.ObjectMapping;
+
+/// <summary>
+/// Maps a query to another.
+/// Implement this interface to project a query on the data store side, instead of loading the
+/// source objects into the memory and mapping them one by one.
+/// </summary>
+/// <typeparam name="TSource">Type of the source objects</typeparam>
+/// <typeparam name="TDestination">Type of the destination objects</typeparam>
+public interface IQueryableMapper<TSource, TDestination> : ITransientDependency
+{
+    /// <summary>
+    /// Projects the given query. The returned query must be built on top of it, otherwise the
+    /// query provider can not translate the projection.
+    /// </summary>
+    /// <param name="source">The query to project</param>
+    IQueryable<TDestination> ProjectTo(IQueryable<TSource> source);
+}

framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryableMapper.cs

@@ -3,7 +3,7 @@
 
 namespace Volo.Abp.Application.Services.QueryProjection;
 
-public class BookProjector : IQueryProjectionMapper<Book, BookDto>
+public class BookProjector : IQueryableMapper<Book, BookDto>
 {
     public const string Marker = "-projected";
 

framework/test/Volo.Abp.Ddd.Application.Tests/Volo/Abp/Application/Services/QueryProjection/BookProjector.cs

@@ -6,9 +6,9 @@ namespace Volo.Abp.Application.Services.QueryProjection;
 
 public class BookWithoutProjectionAppService : CrudAppService<Book, BookDto, Guid>
 {
-    protected override IQueryProjectionMapper<Book, BookDto> GetProjectionMapper => null;
+    protected override IQueryableMapper<Book, BookDto> GetQueryableMapper => null;
 
-    protected override IQueryProjectionMapper<Book, BookDto> GetListProjectionMapper => null;
+    protected override IQueryableMapper<Book, BookDto> GetListQueryableMapper => null;
 
     public BookWithoutProjectionAppService(IRepository<Book, Guid> repository)
         : base(repository)

framework/test/Volo.Abp.Ddd.Application.Tests/Volo/Abp/Application/Services/QueryProjection/BookWithoutProjectionAppService.cs

@@ -23,7 +23,7 @@ public QueryProjection_Tests()
     [Fact]
     public void Should_Resolve_Projection_Mapper_Independent_From_The_Class_Name()
     {
-        ServiceProvider.GetService<IQueryProjectionMapper<Book, BookDto>>()
+        ServiceProvider.GetService<IQueryableMapper<Book, BookDto>>()
             .ShouldBeOfType<BookProjector>();
     }
 
@@ -80,8 +80,6 @@ public async Task Should_Not_Use_The_Entity_Based_Overrides_While_Projecting()
     {
         var appService = GetRequiredService<BookCustomizedAppService>();
 
-        //A projection mapper is registered for <Book, BookDto>, so GetEntityByIdAsync and
-        //MapToGetOutputDtoAsync of this application service are skipped by design.
         var dto = await appService.GetAsync(_bookId);
 
         dto.Name.ShouldEndWith(BookProjector.Marker);