Add asynchronous hooks and rename the query projection API

* IQueryProjector replaces IQueryableMapper, the hooks can await other queries to join them
* A projection must return one row per entity, the total count and the paging come before it
* Pass the ambient cancellation token and detect the missing entity for value type DTOs

Author: maliming

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

@@ -2,12 +2,14 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Linq.Dynamic.Core;
+using System.Threading;
 using System.Threading.Tasks;
 using Volo.Abp.Application.Dtos;
 using Volo.Abp.Auditing;
 using Volo.Abp.Domain.Entities;
 using Volo.Abp.Domain.Repositories;
 using Volo.Abp.ObjectMapping;
+using Volo.Abp.Threading;
 
 namespace Volo.Abp.Application.Services;
 
@@ -45,20 +47,18 @@ public abstract class AbstractKeyReadOnlyAppService<TEntity, TGetOutputDto, TGet
     protected virtual string? GetListPolicyName { get; set; }
 
     /// <summary>
-    /// 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.
+    /// Used by the <see cref="CreateGetOutputDtoQueryOrNullAsync"/> to project the query to the <typeparamref name="TGetOutputDto"/>.
+    /// The <see cref="GetEntityByIdAsync"/> and the <see cref="MapToGetOutputDtoAsync"/> are not used while the query is projected.
     /// </summary>
-    protected virtual IQueryableMapper<TEntity, TGetOutputDto>? GetQueryableMapper
-        => LazyServiceProvider.LazyGetService<IQueryableMapper<TEntity, TGetOutputDto>>();
+    protected virtual IQueryProjector<TEntity, TGetOutputDto>? GetOutputDtoQueryProjector
+        => LazyServiceProvider.LazyGetService<IQueryProjector<TEntity, TGetOutputDto>>();
 
     /// <summary>
-    /// 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.
+    /// Used by the <see cref="CreateGetListOutputDtoQueryOrNullAsync"/> to project the query to the <typeparamref name="TGetListOutputDto"/>.
+    /// The <see cref="MapToGetListOutputDtosAsync"/> is not used while the query is projected.
     /// </summary>
-    protected virtual IQueryableMapper<TEntity, TGetListOutputDto>? GetListQueryableMapper
-        => LazyServiceProvider.LazyGetService<IQueryableMapper<TEntity, TGetListOutputDto>>();
+    protected virtual IQueryProjector<TEntity, TGetListOutputDto>? GetListOutputDtoQueryProjector
+        => LazyServiceProvider.LazyGetService<IQueryProjector<TEntity, TGetListOutputDto>>();
 
     protected AbstractKeyReadOnlyAppService(IReadOnlyRepository<TEntity> repository)
     {
@@ -69,15 +69,17 @@ public virtual async Task<TGetOutputDto> GetAsync(TKey id)
     {
         await CheckGetPolicyAsync();
 
-        var projectionMapper = GetQueryableMapper;
-        if (projectionMapper != null)
+        var dtoQuery = await CreateGetOutputDtoQueryOrNullAsync(id);
+        if (dtoQuery != null)
         {
-            var query = await CreateEntityQueryAsync(id);
-            if (query != null)
+            //TGetOutputDto has no class constraint, so a default value can not be used to detect the missing entity
+            var dtos = await AsyncExecuter.ToListAsync(dtoQuery.Take(1), GetCancellationToken());
+            if (dtos.Count == 0)
             {
-                return await AsyncExecuter.FirstOrDefaultAsync(projectionMapper.ProjectTo(query))
-                       ?? throw new EntityNotFoundException<TEntity>(id);
+                throw new EntityNotFoundException<TEntity>(id);
             }
+
+            return dtos[0];
         }
 
         var entity = await GetEntityByIdAsync(id);
@@ -90,7 +92,7 @@ public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetLi
         await CheckGetListPolicyAsync();
 
         var query = await CreateFilteredQueryAsync(input);
-        var totalCount = await AsyncExecuter.CountAsync(query);
+        var totalCount = await AsyncExecuter.CountAsync(query, GetCancellationToken());
 
         var entityDtos = new List<TGetListOutputDto>();
 
@@ -99,14 +101,14 @@ public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetLi
             query = ApplySorting(query, input);
             query = ApplyPaging(query, input);
 
-            var projectionMapper = GetListQueryableMapper;
-            if (projectionMapper != null)
+            var dtoQuery = await CreateGetListOutputDtoQueryOrNullAsync(query);
+            if (dtoQuery != null)
             {
-                entityDtos = await AsyncExecuter.ToListAsync(projectionMapper.ProjectTo(query));
+                entityDtos = await AsyncExecuter.ToListAsync(dtoQuery, GetCancellationToken());
             }
             else
             {
-                var entities = await AsyncExecuter.ToListAsync(query);
+                var entities = await AsyncExecuter.ToListAsync(query, GetCancellationToken());
                 entityDtos = await MapToGetListOutputDtosAsync(entities);
             }
         }
@@ -119,16 +121,55 @@ public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetLi
 
     protected abstract Task<TEntity> GetEntityByIdAsync(TKey id);
 
+    protected virtual CancellationToken GetCancellationToken(CancellationToken preferredValue = default)
+    {
+        return CancellationTokenProvider.FallbackToProvider(preferredValue);
+    }
+
     /// <summary>
     /// 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.
+    /// It returns null by default, then the entity is not projected.
     /// </summary>
     /// <param name="id">The id of the entity.</param>
-    protected virtual Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
+    protected virtual Task<IQueryable<TEntity>?> CreateEntityQueryOrNullAsync(TKey id)
     {
         return Task.FromResult<IQueryable<TEntity>?>(null);
     }
 
+    /// <summary>
+    /// Projects the query of the entity with the given <paramref name="id"/> to the <typeparamref name="TGetOutputDto"/>.
+    /// It uses the <see cref="GetOutputDtoQueryProjector"/> and the <see cref="CreateEntityQueryOrNullAsync"/> by default,
+    /// and the <see cref="GetEntityByIdAsync"/> is used when it returns null.
+    /// Override it to await other queries, like the query of another aggregate root to join.
+    /// </summary>
+    /// <param name="id">The id of the entity.</param>
+    protected virtual async Task<IQueryable<TGetOutputDto>?> CreateGetOutputDtoQueryOrNullAsync(TKey id)
+    {
+        var queryProjector = GetOutputDtoQueryProjector;
+        if (queryProjector == null)
+        {
+            return null;
+        }
+
+        var query = await CreateEntityQueryOrNullAsync(id);
+
+        return query == null ? null : queryProjector.ProjectTo(query);
+    }
+
+    /// <summary>
+    /// Projects the given entity query to the <typeparamref name="TGetListOutputDto"/>.
+    /// It uses the <see cref="GetListOutputDtoQueryProjector"/> by default,
+    /// and the <see cref="MapToGetListOutputDtosAsync"/> is used when it returns null.
+    /// Override it to await other queries, like the query of another aggregate root to join.
+    /// The projection must return one row per entity: the total count is already calculated and the paging is
+    /// already applied, so adding or removing rows makes the page inconsistent with the total count.
+    /// </summary>
+    /// <param name="query">The sorted and paged entity query.</param>
+    protected virtual Task<IQueryable<TGetListOutputDto>?> CreateGetListOutputDtoQueryOrNullAsync(IQueryable<TEntity> query)
+    {
+        return Task.FromResult(GetListOutputDtoQueryProjector?.ProjectTo(query));
+    }
+
     protected virtual async Task CheckGetPolicyAsync()
     {
         await CheckPolicyAsync(GetPolicyName);

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

@@ -19,6 +19,7 @@
 using Volo.Abp.MultiTenancy;
 using Volo.Abp.ObjectMapping;
 using Volo.Abp.Settings;
+using Volo.Abp.Threading;
 using Volo.Abp.Timing;
 using Volo.Abp.Uow;
 using Volo.Abp.Users;
@@ -48,6 +49,8 @@ public abstract class ApplicationService :
 
     protected IAsyncQueryableExecuter AsyncExecuter => LazyServiceProvider.LazyGetRequiredService<IAsyncQueryableExecuter>();
 
+    protected ICancellationTokenProvider CancellationTokenProvider => LazyServiceProvider.LazyGetService<ICancellationTokenProvider>(NullCancellationTokenProvider.Instance);
+
     protected Type? ObjectMapperContext { get; set; }
     protected IObjectMapper ObjectMapper => LazyServiceProvider.LazyGetService<IObjectMapper>(provider =>
         ObjectMapperContext == null

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

@@ -84,11 +84,11 @@ protected override async Task<TEntity> GetEntityByIdAsync(TKey id)
         return await Repository.GetAsync(id);
     }
 
-    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
+    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryOrNullAsync(TKey id)
     {
         var query = await Repository.GetQueryableAsync();
 
-        return query.Where(EntityHelper.CreateEqualityExpressionForId<TEntity, TKey>(id));
+        return query.Where(e => e.Id!.Equals(id));
     }
 
     protected override void MapToEntity(TUpdateInput updateInput, TEntity entity)

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

@@ -47,11 +47,11 @@ protected override async Task<TEntity> GetEntityByIdAsync(TKey id)
         return await Repository.GetAsync(id);
     }
 
-    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryAsync(TKey id)
+    protected override async Task<IQueryable<TEntity>?> CreateEntityQueryOrNullAsync(TKey id)
     {
         var query = await Repository.GetQueryableAsync();
 
-        return query.Where(EntityHelper.CreateEqualityExpressionForId<TEntity, TKey>(id));
+        return query.Where(e => e.Id!.Equals(id));
     }
 
     protected override IQueryable<TEntity> ApplyDefaultSorting(IQueryable<TEntity> query)

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

@@ -1,4 +1,5 @@
-using Microsoft.Extensions.DependencyInjection;
+using System.Collections.Generic;
+using Microsoft.Extensions.DependencyInjection;
 using Volo.Abp.DependencyInjection;
 using Volo.Abp.Modularity;
 using Volo.Abp.Reflection;
@@ -19,13 +20,14 @@ public override void PreConfigureServices(ServiceConfigurationContext context)
                 ).ConvertAll(t => new ServiceIdentifier(t))
             );
 
-            //Register types for IQueryableMapper<TSource, TDestination> if implements
-            onServiceExposingContext.ExposedTypes.AddRange(
-                ReflectionHelper.GetImplementedGenericTypes(
-                    onServiceExposingContext.ImplementationType,
-                    typeof(IQueryableMapper<,>)
-                ).ConvertAll(t => new ServiceIdentifier(t))
-            );
+            //Register types for IQueryProjector<TSource, TDestination> if implements
+            //The class name convention may have already exposed them, so they are not added twice
+            foreach (var serviceType in ReflectionHelper.GetImplementedGenericTypes(
+                         onServiceExposingContext.ImplementationType,
+                         typeof(IQueryProjector<,>)))
+            {
+                onServiceExposingContext.ExposedTypes.AddIfNotContains(new ServiceIdentifier(serviceType));
+            }
         });
     }
 

…lo/Abp/ObjectMapping/IQueryableMapper.cs …olo/Abp/ObjectMapping/IQueryProjector.csframework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryableMapper.cs renamed to framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryProjector.cs framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryableMapper.cs renamed to framework/src/Volo.Abp.ObjectMapping/Volo/Abp/ObjectMapping/IQueryProjector.cs

@@ -7,14 +7,16 @@ namespace Volo.Abp.ObjectMapping;
 /// 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.
+/// Implement it once for a source and destination pair, the last registered one is used otherwise.
 /// </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
+public interface IQueryProjector<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.
+    /// Projects the given query. The returned query must be built on top of it and must keep its order,
+    /// with a single destination object for each source object, using expressions the query provider can
+    /// translate. The caller may have already sorted, paged or counted the source query.
     /// </summary>
     /// <param name="source">The query to project</param>
     IQueryable<TDestination> ProjectTo(IQueryable<TSource> source);

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

@@ -0,0 +1,35 @@
+#nullable enable
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using Volo.Abp.Domain.Repositories;
+
+namespace Volo.Abp.Application.Services.QueryProjection;
+
+public class BookAbstractKeyProjectingAppService : AbstractKeyReadOnlyAppService<Book, BookDto, Guid>
+{
+    public BookAbstractKeyProjectingAppService(IReadOnlyRepository<Book> repository)
+        : base(repository)
+    {
+
+    }
+
+    protected override async Task<Book> GetEntityByIdAsync(Guid id)
+    {
+        var query = await ReadOnlyRepository.GetQueryableAsync();
+
+        return await AsyncExecuter.FirstAsync(query, book => book.Id == id);
+    }
+
+    protected override async Task<IQueryable<Book>?> CreateEntityQueryOrNullAsync(Guid id)
+    {
+        var query = await ReadOnlyRepository.GetQueryableAsync();
+
+        return query.Where(book => book.Id == id);
+    }
+
+    protected override IQueryable<Book> ApplyDefaultSorting(IQueryable<Book> query)
+    {
+        return query.OrderBy(book => book.Id);
+    }
+}

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

@@ -0,0 +1,46 @@
+#nullable enable
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using Volo.Abp.Application.Dtos;
+using Volo.Abp.Domain.Repositories;
+
+namespace Volo.Abp.Application.Services.QueryProjection;
+
+public class BookAsyncProjectionAppService : CrudAppService<Book, BookDto, Guid>
+{
+    public const string Marker = "-async";
+
+    private readonly IBookNameSuffixProvider _suffixProvider;
+
+    public BookAsyncProjectionAppService(
+        IRepository<Book, Guid> repository,
+        IBookNameSuffixProvider suffixProvider)
+        : base(repository)
+    {
+        _suffixProvider = suffixProvider;
+    }
+
+    protected override async Task<IQueryable<BookDto>?> CreateGetOutputDtoQueryOrNullAsync(Guid id)
+    {
+        var query = await Repository.GetQueryableAsync();
+
+        return await ProjectAsync(query.Where(book => book.Id == id));
+    }
+
+    protected override async Task<IQueryable<BookDto>?> CreateGetListOutputDtoQueryOrNullAsync(IQueryable<Book> query)
+    {
+        return await ProjectAsync(query);
+    }
+
+    private async Task<IQueryable<BookDto>> ProjectAsync(IQueryable<Book> query)
+    {
+        var suffix = await _suffixProvider.GetAsync();
+
+        return query.Select(book => new BookDto
+        {
+            Id = book.Id,
+            Name = book.Name + suffix
+        });
+    }
+}

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

@@ -0,0 +1,15 @@
+using System;
+using Volo.Abp.Application.Dtos;
+using Volo.Abp.Domain.Repositories;
+
+namespace Volo.Abp.Application.Services.QueryProjection;
+
+public class BookDetailAppService :
+    ReadOnlyAppService<Book, BookDetailDto, BookDto, Guid, PagedAndSortedResultRequestDto>
+{
+    public BookDetailAppService(IReadOnlyRepository<Book, Guid> repository)
+        : base(repository)
+    {
+
+    }
+}

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

@@ -0,0 +1,9 @@
+using System;
+using Volo.Abp.Application.Dtos;
+
+namespace Volo.Abp.Application.Services.QueryProjection;
+
+public class BookDetailDto : EntityDto<Guid>
+{
+    public string Name { get; set; } = default!;
+}