update documentation

Author: pwelter34

Arbiter.sln

@@ -0,0 +1,16 @@
+<Solution>
+  <Folder Name="/Build/">
+    <File Path=".github/workflows/dotnet.yml" />
+    <File Path="README.md" />
+    <File Path="src/Directory.Build.props" />
+  </Folder>
+  <Folder Name="/Tests/">
+    <Project Path="test/Arbiter.Benchmarks/Arbiter.Benchmarks.csproj" />
+    <Project Path="test/Arbiter.Tests/Arbiter.Tests.csproj" />
+  </Folder>
+  <Project Path="src/Arbiter.CommandQuery.Endpoints/Arbiter.CommandQuery.Endpoints.csproj" />
+  <Project Path="src/Arbiter.CommandQuery.EntityFramework/Arbiter.CommandQuery.EntityFramework.csproj" />
+  <Project Path="src/Arbiter.CommandQuery.MongoDB/Arbiter.CommandQuery.MongoDB.csproj" />
+  <Project Path="src/Arbiter.CommandQuery/Arbiter.CommandQuery.csproj" />
+  <Project Path="src/Arbiter/Arbiter.csproj" />
+</Solution>

Arbiter.slnx

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Arbiter.CommandQuery\Arbiter.CommandQuery.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+</Project>

src/Arbiter.CommandQuery.Endpoints/Arbiter.CommandQuery.Endpoints.csproj

@@ -12,8 +12,20 @@
 
 namespace Arbiter.CommandQuery.EntityFramework;
 
+/// <summary>
+/// Extensions for adding Entity Framework Core support to the command/query pipeline.
+/// </summary>
 public static class DomainServiceExtensions
 {
+    /// <summary>
+    /// Registers entity queries with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityQueries<TContext, TEntity, TKey, TReadModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -35,6 +47,17 @@ public static IServiceCollection AddEntityQueries<TContext, TEntity, TKey, TRead
     }
 
 
+    /// <summary>
+    /// Registers entity create, update and delete commands with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <typeparam name="TCreateModel">The type of the create model</typeparam>
+    /// <typeparam name="TUpdateModel">The type of the update model</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityCommands<TContext, TEntity, TKey, TReadModel, TCreateModel, TUpdateModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -58,6 +81,16 @@ public static IServiceCollection AddEntityCommands<TContext, TEntity, TKey, TRea
     }
 
 
+    /// <summary>
+    /// Registers entity create command with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <typeparam name="TCreateModel">The type of the create model</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityCreateCommand<TContext, TEntity, TKey, TReadModel, TCreateModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -73,6 +106,16 @@ public static IServiceCollection AddEntityCreateCommand<TContext, TEntity, TKey,
         return services;
     }
 
+    /// <summary>
+    /// Registers entity update command with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <typeparam name="TUpdateModel">The type of the update model</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityUpdateCommand<TContext, TEntity, TKey, TReadModel, TUpdateModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -92,6 +135,16 @@ public static IServiceCollection AddEntityUpdateCommand<TContext, TEntity, TKey,
         return services;
     }
 
+    /// <summary>
+    /// Registers entity update or insert command with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <typeparam name="TUpdateModel">The type of the update model</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityUpsertCommand<TContext, TEntity, TKey, TReadModel, TUpdateModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -107,6 +160,15 @@ public static IServiceCollection AddEntityUpsertCommand<TContext, TEntity, TKey,
         return services;
     }
 
+    /// <summary>
+    /// Registers entity patch command with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityPatchCommand<TContext, TEntity, TKey, TReadModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()
@@ -121,6 +183,15 @@ public static IServiceCollection AddEntityPatchCommand<TContext, TEntity, TKey,
         return services;
     }
 
+    /// <summary>
+    /// Registers entity delete command with pipeline behaviors in the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+    /// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+    /// <typeparam name="TKey">The key type for the data context entity</typeparam>
+    /// <typeparam name="TReadModel">The type of the read model.</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+    /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     public static IServiceCollection AddEntityDeleteCommand<TContext, TEntity, TKey, TReadModel>(this IServiceCollection services)
         where TContext : DbContext
         where TEntity : class, IHaveIdentifier<TKey>, new()

src/Arbiter.CommandQuery.EntityFramework/DomainServiceExtensions.cs

@@ -6,19 +6,37 @@
 
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
+/// <summary>
+/// A base handler for a request that requires the specified <see cref="DbContext"/>.
+/// </summary>
+/// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+/// <typeparam name="TRequest">The type of request being handled.</typeparam>
+/// <typeparam name="TResponse">The type of response from the handler.</typeparam>
 public abstract class DataContextHandlerBase<TContext, TRequest, TResponse>
     : RequestHandlerBase<TRequest, TResponse>
     where TContext : DbContext
     where TRequest : IRequest<TResponse>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DataContextHandlerBase{TContext, TRequest, TResponse}"/> class.
+    /// </summary>
+    /// <param name="loggerFactory">The logger factory to create an <see cref="ILogger"/> for this handler.</param>
+    /// <param name="dataContext">The <see cref="DbContext"/> for this handler.</param>
+    /// <param name="mapper"> The <see cref="IMapper"/> for this handler.</param>
     protected DataContextHandlerBase(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper)
         : base(loggerFactory)
     {
         DataContext = dataContext ?? throw new ArgumentNullException(nameof(dataContext));
         Mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
     }
 
+    /// <summary>
+    /// Gets the <see cref="DbContext"/> for this handler.
+    /// </summary>
     protected TContext DataContext { get; }
 
+    /// <summary>
+    /// Gets the <see cref="IMapper"/> for this handler.
+    /// </summary>
     protected IMapper Mapper { get; }
 }

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

@@ -6,17 +6,28 @@
 
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
+/// <summary>
+/// A handler for a request that creates an entity in the specified <see cref="DbContext"/>.
+/// </summary>
+/// <inheritdoc/>
 public class EntityCreateCommandHandler<TContext, TEntity, TKey, TCreateModel, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityCreateCommand<TCreateModel, TReadModel>, TReadModel>
     where TContext : DbContext
     where TEntity : class, IHaveIdentifier<TKey>, new()
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EntityCreateCommandHandler{TContext, TEntity, TKey, TCreateModel, TReadModel}"/> class.
+    /// </summary>
+    /// <inheritdoc/>
     public EntityCreateCommandHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper)
         : base(loggerFactory, dataContext, mapper)
     {
     }
 
-    protected override async ValueTask<TReadModel?> Process(EntityCreateCommand<TCreateModel, TReadModel> request, CancellationToken cancellationToken = default)
+    /// <inheritdoc/>
+    protected override async ValueTask<TReadModel?> Process(
+        EntityCreateCommand<TCreateModel, TReadModel> request,
+        CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(request);
 

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

@@ -7,26 +7,51 @@
 
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
+/// <summary>
+/// A base handler for a request that requires the specified <see cref="DbContext"/>.
+/// </summary>
+/// <typeparam name="TContext">The type of <see cref="DbContext"/>.</typeparam>
+/// <typeparam name="TEntity">The type of entity being operated on by the <see cref="DbContext"/></typeparam>
+/// <typeparam name="TKey">The key type for the data context entity</typeparam>
+/// <typeparam name="TReadModel">The type of the read model.</typeparam>
+/// <typeparam name="TRequest">The type of request being handled.</typeparam>
+/// <typeparam name="TResponse">The type of response from the handler.</typeparam>
 public abstract class EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, TRequest, TResponse>
     : DataContextHandlerBase<TContext, TRequest, TResponse>
     where TContext : DbContext
     where TEntity : class, IHaveIdentifier<TKey>, new()
     where TRequest : IRequest<TResponse>
 {
+
+    private static readonly string _contextName = typeof(TContext).Name;
+    private static readonly string _entityName = typeof(TEntity).Name;
+    private static readonly string _modelName = typeof(TReadModel).Name;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EntityDataContextHandlerBase{TContext, TEntity, TKey, TReadModel, TRequest, TResponse}"/> class.
+    /// </summary>
+    /// <inheritdoc/>
     protected EntityDataContextHandlerBase(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper)
         : base(loggerFactory, dataContext, mapper)
     {
     }
 
+    /// <summary>
+    /// Reads the entity from the data context.
+    /// </summary>
+    /// <param name="key">The entity key to read</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>
     protected virtual async ValueTask<TReadModel?> Read([NotNull] TKey key, CancellationToken cancellationToken = default)
     {
-        if (key == null)
+        if (key is null)
             throw new ArgumentNullException(nameof(key));
 
         var query = DataContext
             .Set<TEntity>()
             .AsNoTracking()
-            .TagWith($"EntityDataContextHandlerBase; Context:{typeof(TContext).Name}, Entity:{typeof(TEntity).Name}, Model:{typeof(TReadModel).Name}")
+            .TagWith($"Read(); Context:{_contextName}, Entity:{_entityName}, Model:{_modelName}")
             .TagWithCallSite()
             .Where(p => Equals(p.Id, key));
 

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

@@ -6,17 +6,28 @@
 
 namespace Arbiter.CommandQuery.EntityFramework.Handlers;
 
+/// <summary>
+/// A handler for a request that deletes an entity in the specified <see cref="DbContext"/>.
+/// </summary>
+/// <inheritdoc/>
 public class EntityDeleteCommandHandler<TContext, TEntity, TKey, TReadModel>
     : EntityDataContextHandlerBase<TContext, TEntity, TKey, TReadModel, EntityDeleteCommand<TKey, TReadModel>, TReadModel>
     where TContext : DbContext
     where TEntity : class, IHaveIdentifier<TKey>, new()
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EntityDeleteCommandHandler{TContext, TEntity, TKey, TReadModel}"/> class.
+    /// </summary>
+    /// <inheritdoc/>
     public EntityDeleteCommandHandler(ILoggerFactory loggerFactory, TContext dataContext, IMapper mapper)
         : base(loggerFactory, dataContext, mapper)
     {
     }
 
-    protected override async ValueTask<TReadModel?> Process(EntityDeleteCommand<TKey, TReadModel> request, CancellationToken cancellationToken = default)
+    /// <inheritdoc/>
+    protected override async ValueTask<TReadModel?> Process(
+        EntityDeleteCommand<TKey, TReadModel> request,
+        CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(request);