Enhance XML docs for handlers and behaviors

Author: pwelter34

Directory.Packages.props

@@ -5,7 +5,6 @@
     <NoWarn>$(NoWarn);NU1507</NoWarn>
   </PropertyGroup>
   <ItemGroup>
-    <PackageVersion Include="Aspire.Hosting.AppHost" Version="13.3.0" />
     <PackageVersion Include="AspNetCore.SecurityKey" Version="4.3.0" />
     <PackageVersion Include="AssemblyMetadata.Generators" Version="2.2.0" />
     <PackageVersion Include="AutoMapper" Version="[14.0.0]" />
@@ -83,4 +82,4 @@
   <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
     <PackageVersion Update="Microsoft.EntityFrameworkCore" Version="9.0.15" />
   </ItemGroup>
-</Project>
+</Project>

src/Arbiter.CommandQuery.EntityFramework/Handlers/EntityCreateCommandHandler.cs

@@ -9,9 +9,15 @@
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
 /// <summary>
-/// A handler for a request that creates an entity in the specified <see cref="DbContext"/>.
+/// A handler that processes an <see cref="EntityCreateCommand{TCreateModel, TReadModel}"/> by mapping the
+/// create model to a new <typeparamref name="TEntity"/>, applying audit metadata, persisting the entity
+/// via the specified <typeparamref name="TContext"/>, and returning the created entity as a <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <inheritdoc/>
+/// <typeparam name="TContext">The <see cref="DbContext"/> used to persist the entity.</typeparam>
+/// <typeparam name="TEntity">The entity type being created. Must implement <see cref="IHaveIdentifier{TKey}"/> and have a parameterless constructor.</typeparam>
+/// <typeparam name="TKey">The type of the entity's primary key.</typeparam>
+/// <typeparam name="TCreateModel">The input model type containing the data for the new entity.</typeparam>
+/// <typeparam name="TReadModel">The output model type returned after the entity is created.</typeparam>
 public class EntityCreateCommandHandler<TContext, TEntity, TKey, TCreateModel, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityCreateCommand<TCreateModel, TReadModel>, TReadModel>
     where TContext : DbContext
@@ -20,13 +26,22 @@ public class EntityCreateCommandHandler<TContext, TEntity, TKey, TCreateModel, T
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityCreateCommandHandler{TContext, TEntity, TKey, TCreateModel, TReadModel}"/> class.
     /// </summary>
-    /// <inheritdoc/>
+    /// <param name="loggerFactory">The logger factory used to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <typeparamref name="TContext"/> used to persist the entity.</param>
+    /// <param name="mapper">The mapper used to convert between <typeparamref name="TCreateModel"/> and <typeparamref name="TEntity"/>, and to project to <typeparamref name="TReadModel"/>.</param>
+    /// <param name="pipeline">An optional query pipeline applied when reading back the created entity.</param>
     public EntityCreateCommandHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper, IQueryPipeline? pipeline = null)
         : base(loggerFactory, dataContext, mapper, pipeline)
     {
     }
 
     /// <inheritdoc/>
+    /// <remarks>
+    /// Maps <paramref name="request"/>.<c>Model</c> to a new <typeparamref name="TEntity"/>, then sets
+    /// <see cref="ITrackCreated"/> and <see cref="ITrackUpdated"/> audit fields when supported.
+    /// The entity is added to the <see cref="DbSet{TEntity}"/> and saved. The newly created entity
+    /// is then read back and projected to <typeparamref name="TReadModel"/> before being returned.
+    /// </remarks>
     protected override async ValueTask<TReadModel?> Process(
         EntityCreateCommand<TCreateModel, TReadModel> request,
         CancellationToken cancellationToken = default)

src/Arbiter.CommandQuery.EntityFramework/Handlers/EntityDataContextHandlerBase.cs

@@ -39,21 +39,26 @@ public abstract class EntityDataContextHandlerBase<TContext, TEntity, TKey, TRea
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityDataContextHandlerBase{TContext, TEntity, TKey, TReadModel, TRequest, TResponse}"/> class.
     /// </summary>
-    /// <inheritdoc/>
+    /// <param name="loggerFactory">The logger factory used to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <typeparamref name="TContext"/> used to access the data store.</param>
+    /// <param name="mapper">The <see cref="IMapper"/> used to map between entity and model types.</param>
+    /// <param name="pipeline">An optional <see cref="IQueryPipeline"/> applied to queries executed by this handler.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="loggerFactory"/>, <paramref name="dataContext"/>, or <paramref name="mapper"/> is <see langword="null"/>.</exception>
     protected EntityDataContextHandlerBase(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper, IQueryPipeline? pipeline = null)
         : base(loggerFactory, dataContext, mapper, pipeline)
     {
     }
 
     /// <summary>
-    /// Reads the entity from the data context.
+    /// Reads the <typeparamref name="TEntity"/> identified by <paramref name="key"/> from the data context
+    /// and projects it to <typeparamref name="TReadModel"/>.
     /// </summary>
-    /// <param name="key">The entity key to read</param>
-    /// <param name="pipelineName">The optional pipeline name to apply</param>
-    /// <param name="principal">The optional claims principal</param>
-    /// <param name="cancellationToken">The cancellation token</param>
-    /// <returns>Awaitable task returning the <typeparamref name="TReadModel"/></returns>
-    /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is null</exception>
+    /// <param name="key">The primary key of the entity to read.</param>
+    /// <param name="pipelineName">The optional name of the query pipeline to apply when querying the entity.</param>
+    /// <param name="principal">The optional <see cref="ClaimsPrincipal"/> used by the query pipeline for authorization or filtering.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The <typeparamref name="TReadModel"/> for the entity, or <see langword="null"/> if no matching entity is found.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is <see langword="null"/>.</exception>
     protected virtual async ValueTask<TReadModel?> Read(
         [NotNull] TKey key,
         string? pipelineName = null,

src/Arbiter.CommandQuery.EntityFramework/Handlers/EntityDeleteCommandHandler.cs

@@ -9,9 +9,15 @@
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
 /// <summary>
-/// A handler for a request that deletes an entity in the specified <see cref="DbContext"/>.
+/// A handler that processes an <see cref="EntityDeleteCommand{TKey, TReadModel}"/> by locating the
+/// <typeparamref name="TEntity"/> in the specified <typeparamref name="TContext"/>, reading it back as a
+/// <typeparamref name="TReadModel"/>, then performing a soft delete (via <see cref="ITrackDeleted"/>) or a
+/// hard delete, and finally saving changes.
 /// </summary>
-/// <inheritdoc/>
+/// <typeparam name="TContext">The <see cref="DbContext"/> used to access the data store.</typeparam>
+/// <typeparam name="TEntity">The entity type being deleted. Must implement <see cref="IHaveIdentifier{TKey}"/> and have a parameterless constructor.</typeparam>
+/// <typeparam name="TKey">The type of the entity's primary key.</typeparam>
+/// <typeparam name="TReadModel">The output model type returned after the entity is deleted.</typeparam>
 public class EntityDeleteCommandHandler<TContext, TEntity, TKey, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityDeleteCommand<TKey, TReadModel>, TReadModel>
     where TContext : DbContext
@@ -20,13 +26,34 @@ public class EntityDeleteCommandHandler<TContext, TEntity, TKey, TReadModel>
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityDeleteCommandHandler{TContext, TEntity, TKey, TReadModel}"/> class.
     /// </summary>
-    /// <inheritdoc/>
+    /// <param name="loggerFactory">The logger factory used to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <typeparamref name="TContext"/> used to access the data store.</param>
+    /// <param name="mapper">The <see cref="IMapper"/> used to project <typeparamref name="TEntity"/> to <typeparamref name="TReadModel"/>.</param>
+    /// <param name="pipeline">An optional <see cref="IQueryPipeline"/> applied to queries executed by this handler.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="loggerFactory"/>, <paramref name="dataContext"/>, or <paramref name="mapper"/> is <see langword="null"/>.</exception>
     public EntityDeleteCommandHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper, IQueryPipeline? pipeline = null)
         : base(loggerFactory, dataContext, mapper, pipeline)
     {
     }
 
     /// <inheritdoc/>
+    /// <remarks>
+    /// <para>
+    /// Queries the <see cref="DbSet{TEntity}"/> for the entity matching <c>request.Id</c>, applying any
+    /// optional query pipeline modifiers. If no entity is found, returns <see langword="null"/>.
+    /// </para>
+    /// <para>
+    /// Before deletion, the entity is read back and projected to <typeparamref name="TReadModel"/> so the
+    /// caller receives the state of the entity prior to deletion.
+    /// </para>
+    /// <para>
+    /// The delete strategy is determined by the entity's implemented interfaces:
+    /// <list type="bullet">
+    /// <item><description>If the entity implements <see cref="ITrackDeleted"/>, a soft delete is performed by setting <c>IsDeleted = true</c>.</description></item>
+    /// <item><description>Otherwise, the entity is hard-deleted via <see cref="DbSet{TEntity}.Remove"/>. If the entity also implements <see cref="ITrackHistory"/> and <see cref="ITrackUpdated"/>, update metadata is saved first to preserve history.</description></item>
+    /// </list>
+    /// </para>
+    /// </remarks>
     protected override async ValueTask<TReadModel?> Process(
         EntityDeleteCommand<TKey, TReadModel> request,
         CancellationToken cancellationToken = default)

src/Arbiter.CommandQuery.EntityFramework/Handlers/EntityIdentifierQueryHandler.cs

@@ -9,9 +9,14 @@
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
 /// <summary>
-/// A handler for a request that reads an entity in the specified <see cref="DbContext"/>.
+/// A handler that processes an <see cref="EntityIdentifierQuery{TKey, TReadModel}"/> by reading a single
+/// <typeparamref name="TEntity"/> by its primary key from the specified <typeparamref name="TContext"/>
+/// and projecting it to a <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <inheritdoc/>
+/// <typeparam name="TContext">The <see cref="DbContext"/> used to access the data store.</typeparam>
+/// <typeparam name="TEntity">The entity type being queried. Must implement <see cref="IHaveIdentifier{TKey}"/> and have a parameterless constructor.</typeparam>
+/// <typeparam name="TKey">The type of the entity's primary key.</typeparam>
+/// <typeparam name="TReadModel">The output model type returned after the entity is read.</typeparam>
 public class EntityIdentifierQueryHandler<TContext, TEntity, TKey, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityIdentifierQuery<TKey, TReadModel>, TReadModel>
     where TContext : DbContext
@@ -21,13 +26,22 @@ public class EntityIdentifierQueryHandler<TContext, TEntity, TKey, TReadModel>
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifierQueryHandler{TContext, TEntity, TKey, TReadModel}"/> class.
     /// </summary>
-    /// <inheritdoc/>
+    /// <param name="loggerFactory">The logger factory used to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <typeparamref name="TContext"/> used to access the data store.</param>
+    /// <param name="mapper">The <see cref="IMapper"/> used to project <typeparamref name="TEntity"/> to <typeparamref name="TReadModel"/>.</param>
+    /// <param name="pipeline">An optional <see cref="IQueryPipeline"/> applied to queries executed by this handler.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="loggerFactory"/>, <paramref name="dataContext"/>, or <paramref name="mapper"/> is <see langword="null"/>.</exception>
     public EntityIdentifierQueryHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper, IQueryPipeline? pipeline = null)
         : base(loggerFactory, dataContext, mapper, pipeline)
     {
     }
 
     /// <inheritdoc/>
+    /// <remarks>
+    /// Delegates to <see cref="EntityDataContextHandlerBase{TContext, TEntity, TKey, TReadModel, TRequest, TResponse}.Read"/>
+    /// using <c>request.Id</c>, <c>request.FilterName</c>, and <c>request.Principal</c>.
+    /// Returns <see langword="null"/> if no matching entity is found.
+    /// </remarks>
     protected override async ValueTask<TReadModel?> Process(
         EntityIdentifierQuery<TKey, TReadModel> request,
         CancellationToken cancellationToken = default)

src/Arbiter.CommandQuery.EntityFramework/Handlers/EntityIdentifiersQueryHandler.cs

@@ -9,9 +9,15 @@
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
 /// <summary>
-/// A handler for a request that reads a collection of entities in the specified <see cref="DbContext"/>.
+/// A handler that processes an <see cref="EntityIdentifiersQuery{TKey, TReadModel}"/> by querying the
+/// specified <typeparamref name="TContext"/> for all <typeparamref name="TEntity"/> instances whose primary
+/// key is contained in the request's identifier list, and projecting the results to
+/// <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <inheritdoc/>
+/// <typeparam name="TContext">The <see cref="DbContext"/> used to access the data store.</typeparam>
+/// <typeparam name="TEntity">The entity type being queried. Must implement <see cref="IHaveIdentifier{TKey}"/> and have a parameterless constructor.</typeparam>
+/// <typeparam name="TKey">The type of the entity's primary key.</typeparam>
+/// <typeparam name="TReadModel">The output model type returned for each matched entity.</typeparam>
 public class EntityIdentifiersQueryHandler<TContext, TEntity, TKey, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityIdentifiersQuery<TKey, TReadModel>, IReadOnlyList<TReadModel>>
     where TContext : DbContext
@@ -21,13 +27,24 @@ public class EntityIdentifiersQueryHandler<TContext, TEntity, TKey, TReadModel>
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifiersQueryHandler{TContext, TEntity, TKey, TReadModel}"/> class.
     /// </summary>
-    /// <inheritdoc/>
+    /// <param name="loggerFactory">The logger factory used to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <typeparamref name="TContext"/> used to access the data store.</param>
+    /// <param name="mapper">The <see cref="IMapper"/> used to project <typeparamref name="TEntity"/> to <typeparamref name="TReadModel"/>.</param>
+    /// <param name="pipeline">An optional <see cref="IQueryPipeline"/> applied to queries executed by this handler.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="loggerFactory"/>, <paramref name="dataContext"/>, or <paramref name="mapper"/> is <see langword="null"/>.</exception>
     public EntityIdentifiersQueryHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper, IQueryPipeline? pipeline = null)
         : base(loggerFactory, dataContext, mapper, pipeline)
     {
     }
 
     /// <inheritdoc/>
+    /// <remarks>
+    /// Applies any optional query pipeline modifiers, then filters the <see cref="DbSet{TEntity}"/>
+    /// to entities whose <c>Id</c> is contained in <c>request.Ids</c>. The matched entities are
+    /// projected to <typeparamref name="TReadModel"/> and returned as an
+    /// <see cref="IReadOnlyList{T}"/>. Returns an empty list when no identifiers match;
+    /// returns <see langword="null"/> only if the underlying query returns <see langword="null"/>.
+    /// </remarks>
     protected override async ValueTask<IReadOnlyList<TReadModel>?> Process(
         EntityIdentifiersQuery<TKey, TReadModel> request,
         CancellationToken cancellationToken = default)