XperienceCommunity.CQRS.Web 1.0.0-prerelease-7-1

Xperience Community - CQRS

A CQRS implementation influenced by https://github.com/jbogard/MediatR/ combined with https://github.com/vkhorikov/CSharpFunctionalExtensions for Kentico Xperience applications.

Dependencies

This package is compatible with ASP.NET Core 6+ and is designed to be used with .NET Core / .NET 6 applications integrated with Kentico Xperience 13.0.

How to Use?

1. This library is separated into (3) NuGet packages. Each package is associated with a different part of the Onion Architecture. You can install all of these into your web application project or isolate your Kentico Xperience types behind abstractions.

   • XperienceCommunity.CQRS.Core

     • Abstractions and implementations for the Domain, Persistence, and Presentation layers to implement.
     • Typically the project consuming this package doesn't have any reference to Kentico Xperience packages or APIs.

   • XperienceCommunity.CQRS.Data

     • Decorators and base classes for data access implementations.
     • The project consuming this package also uses Kentico Xperience data access APIs.

   • XperienceCommunity.CQRS.Web

     • Presentation layer cache and service collection registration utilities.
     • The project consuming this package is where your presentation logic is located (Razor/View Components/Controllers).

2. First, install the NuGet package(s) in your ASP.NET Core projects (see the example project under /samples)

   dotnet add package XperienceCommunity.CQRS.Core
   dotnet add package XperienceCommunity.CQRS.Data
   dotnet add package XperienceCommunity.CQRS.Web
   

3. Create a new implementation of IQuery<T>

   public record HomePageQuery : IQuery<HomePageQueryData>;
   public record HomePageQueryData(string Title, Maybe<string> BodyHTML);
   

4. Create a new implementation of IQueryHandler<TQuery, TResponse>

   public class HomePageQueryHandler : CacheableQueryHandler<HomePageQuery, HomePageQueryData>
   {
       private readonly IPageRetriever retriever;
   
       public HomePageQueryHandler(IPageRetriever retriever) => this.retriever = retriever;
   
       public override Task<Result<HomePageQueryData>> Execute(HomePageQuery query, CancellationToken token) =>
           pageRetriever.RetrieveAsync<HomePage>(q => q.TopN(1), cancellationToken: token)
               .TryFirst()
               .ToResult($"Could not find any [{HomePage.CLASS_NAME}]")
               .Map(homePage =>
               {
                   var bodyHTML = string.IsNullOrWhiteSpace(p.Fields.BodyHTML)
                       ? Maybe<string>.None
                       : p.Fields.BodyHTML;
   
                   return new HomePageQueryData(homePage.Fields.Title, bodyHTML);
               });
   
       protected override ICacheDependencyKeysBuilder AddDependencyKeys(
           HomePageQuery query,
           HomePageQueryData response,
           ICacheDependencyKeysBuilder builder) =>
           builder.PageType(HomePage.CLASS_NAME);
   }
   

5. Register the library's dependencies with the service collection

   public class Startup
   {
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddCQRS(typeof(HomePageQueryHandler).Assembly);
   
           // ...
       }
   }
   

6. Use queries in your MVC Controllers, application services, or View Components

   public class HomePageViewComponent : ViewComponent
   {
       private readonly IQueryDispatcher dispatcher;
   
       public HomePageViewComponent(IQueryDispatcher dispatcher) =>
           this.dispatcher = dispatcher;
   
       public Task<IViewComponentResult> Invoke() =>
           dispatcher.Dispatch(new HomePageQuery(), HttpContext.RequestAborted)
               .ViewWithFallbackOnFailure(this, "_HomePage", data => new HomePageViewModel(data));
   }
   

   @using Microsoft.AspNetCore.Html
   @using XperienceCommunity.Sandbox.Web.Features.Home.Components
   @model HomePageViewModel
   
   <h1>@Model.Title</h1>
   
   @Model.BodyHTML.GetValueOrDefault(HtmlString.Empty)
   
   @if (Model.ImagePath.HasValue)
   {
       <img src="@Model.ImagePath.GetValueOrThrow()" alt="@Model.Title" />
   }
   

How Does It Work?

• TODO

Contributing

To build this project, you must have v6.0.300 or higher of the .NET SDK installed.

References

Kentico Xperience

• Kentico 12: Design Patterns Part 12 - Database Query Caching Patterns
• Kentico Xperience Design Patterns: MVC is Dead, Long Live PTVC