Xpandables.Net.AspNetCore 6.0.0-rc.4.3

Xpandables.Net

Provides with useful interfaces contracts in .Net 6.0 and some implementations mostly following the spirit of SOLID principles, CQRS... The library is strongly-typed, which means it should be hard to make invalid requests and it also makes it easy to discover available methods and properties though IntelliSense.

Feel free to fork this project, make your own changes and create a pull request.

Here are some examples of use :

Web Api using CQRS and EFCore

Add the following nuget packages to your project :

Xpandables.Net.AspNetCore

Xpandables.Net.EntityFramework

Model Definition

// Entity is the domain object base implementation that provides with an Id,
// key generator for id and some useful state methods.
// You can use Aggregate{TAggregateId} if you're targeting DDD.

public sealed class PersonEntity : Entity
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    
    public static PersonEntity NewPerson(Guid id, string firstName, string lastName)
    {
        // custom check
        return new(id, fistName, lastname);
    }
    
    public void ChangeFirstName(string firstName)
        => FirstName = firstName ?? throw new ArgumentNullException(nameof(firstName));
    
    public void ChangeLastName(string lastName)
        => LastName = lastName ?? throw new ArgumentNullException(nameof(lastName));
    
    private PersonEntity(Guid id, string firstName, string lastName)
        => (Id, FirstName, Lastname) = (id, firstName, lastName);
}

Contract definition

// Contract is decorated with HttpClientAttribute that describes the parameters for a request 
// used with IHttpClientDispatcher, where IHttpClientDispatcher provides with methods to handle HTTP
// Rest client queries and commands using a typed client HTTP Client. It also allows, in a .Net environment,
// to no longer define client actions because they are already included in the contracts, 
// by implementing interfaces such as IHttpRequestPathString, IHttpRequestFormUrlEncoded,
// IHttpRequestMultipart, IHttpRequestString, IHttpRequestStream...
// Without the use of one of those interfaces, the whole class will be serialized.


[HttpClient(Path = "api/person", In = ParameterLocation.Body, Method = ParameterMethod.Post, IsSecured = false)]
public sealed record AddPersonRequest([Required] Guid Id, [Required] string FirstName, [Required] string LastName)
    : IHttpClientRequest<CreatedId>, IHttpRequestString
{
    // You can omit the use of IHttpRequestString, the whole class will be serialised.
    public object GetStringContent() => new { Id, FirstName, LastName };
}

[HttpClient(Path = "api/person/{id}", IsNullable = true, In = ParameterLocation.Path, 
    Method = ParameterMethod.Get, IsSecured = false)]
public sealed record GetPersonRequest([Required] Guid Id) : IHttpClientRequest<Person>,
    IHttpRequestPathString
{
    public IDictionary<string, string> GetPathStringSource()
        => new Dictionary<string, string> { { nameof(Id), Id.ToString() } };
}

public sealed record Person(Guid Id, string FirstName, string LastName);
public sealed record CreatedId(Guid Id);

Command/Query and Handler definitions

// The command must implement the ICommand interface and others to enable their behaviors.
// Such as IValidatorDecorator to apply validation before processing the command,
// IPersistenceDecorator to add persistence to the control flow
// or IInterceptorDecorator to add interception of the command process...

// You can derive from QueryExpression{TClass} to allow command to behave like an expression
// when querying data, and override the target method.

public sealed class AddPersonCommand : QueryExpression<PersonEntity>, ICommand,
    IValidatorDecorator, IPersistenceDecorator
{
    public Guid Id { get; }
    public string FirstName { get; }
    public string LastName { get; }
    
    public override Expression<Func<PersonEntity>, bool>> GetExpression()
        => person => person.Id == Id;
}

public sealed class GetPersonQuery : QueryExpression<PersonEntity>, IQuery<Person>
{
    public Guid Id { get; }
    
    public GetPersonQuery(Guid id) => Id= id;
    
    public override Expression<Func<PersonEntity>, bool>> GetExpression()
        => person => person.Id == Id;    
}


public sealed class AddPersonCommandHandler : ICommandHandler<AddPersonCommand>
{
    private readonly PersonContext _personContext;
    public AddPersonCommandHandler(PersonContext personContext)
        => _personContext = personContext;
    
    public async Task<IOperationResult> HandleAsync(AddPersonCommand command, 
        CancellationToken cancellationToken = default)
    {
        // You can check here for data validation or use a specific class for that
        // (see AddPersonCommandValidationDecorator).
        
        var newPerson = Person.NewPerson(
            command.Id,
            command.FirstName,
            command.LastName);
        
        _personContext.People.Add(newPerson);
        
        // You can make a call here to 
        // await _personContext.SaveChangeAsync(canellationToken).ConfigureAwait(false);
        // to persist changes or let the control flow to apply persistence because the command
        // AddPersonCommand is decorated with the IPersistenceDecorator interface.
        // In that case, you may register the persistence command using the
        // delegate PersistenceDecoratorDelegate.
        
        return OperationResult.OkOperation();
        
        // OkOperation, NotFoundOperation are extenion methods that return an IOperationResult that acts like
        // IActionResult in AspNetCore.
        // Note that data will be saved at the end of the control flow
        // if there is no error from other process. The OperationResultFilter will process the output message format.
        // You can add a decorator class to manage the exception.
    }
}

public sealed class GetPersonQueryHandler : IQueryHandler<GetPersonQuery, Person>
{
   private readonly PersonContext _personContext;
    public GetPersonQueryHandler(PersonContext personContext)
        => _personContext = personContext;    
    
    public override async Task<IOperationResult<Person>> HandleAsync(GetPersonQuery query,
        CancellationToken cancellationToken = default)
    {
        var result = await _personContext.People.FirstOrDefaultAsync(
            query,
            cancellationToken)
            .configureAwait(false);
        
        return result switch
        {
            PersonEntity person => OperationResult.OkOperation(new Person(person.Id, person.FirstName, person.LastName)),
            _ => OperationResult.NotFoundOperation<Person>(nameof(query.Id), "Id not found.")
        };
    }        
}

// When using validation decorator.
// Validator{T} defines a method contract used to validate a type-specific argument using a decorator.
// The validator get called during the control flow before the handler.
// If the validator returns a failed operation result, the execution will be interrupted
// and the result of the validator will be returned.
// We consider as best practice to handle common conditions without throwing exceptions
// and to design classes so that exceptions can be avoided.

public sealed class AddPersonCommandValidationDecorator : Validator<AddPersonCommand>
{
    private ready PersonContext _personContext;
    public AddPersonCommandValidationDecorator(PersonContext personContext)
        => _personContext = personContext;
    
    public override async Task<IOperationResult> ValidateAsync(AddPersonCommand argument, 
        CancellationToken cancellationToken)
    {
        return await _personContext.People.FirstOrDefaultAsync(argument, cancellationToken).configureAwait(false) switch
        {
            { } => OperationResult.BadOperation(nameof(argument.Id), "Id already exist"),
            null => OperationResult.OkOperation()
        };
    }    
}

Context definition

// We are using EFCore

public sealed class PersonEntityTypeConfiguration : IEntityTypeConfiguration<PersonEntity>
{
    public void Configure(EntityTypeBuilder<PersonEntity> builder)
    {
        builder.HasKey(p => p.Id);
        builder.Property(p => p.FirstName);
        builder.Property(p => p.LastName);
    }
}

// Context is an abstract class that inherits from DbContext (EFCore)

public sealed class PersonContext : DataContext
{
     public PersonContext(DbContextOptions<PersonContext> contextOptions)
        : base(contextOptions) { }
        
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
         modelBuilder.ApplyConfiguration(new PersonEntityTypeConfiguration());
     }
     
     public DbSet<PersonEntity> People { get; set; } = default!;
}

Controller definition

// IDispatcher provides with methods to discover registered handlers at runtime.
// We consider as best practice to return ValidationProblemDetails/ProblemDetails in case of errors

[Route("api/[controller]")]
[ApiController]
[AllowAnonymous]
public class PersonController : ControllerBase
{
    private readonly IDispatcher _dispatcher;
    
    public PersonController(IDispatcher dispatcher) 
       => _dispatcher = dispatcher ?? throw new ArgumentNullException(nameof(dispatcher));

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(ValidationProblemDetails))]
    [ProducesResponseType(StatusCodes.Status201Created, Type = typeof(CreatedId))]
    public async Task<IActionResult> AddPersonAsync(
        [FromBody] AddPersonRequest request, CancellationToken cancellationToken = default)
    {
        var command = new AddPersonCommand(request.Id, request.FirstName, request.LastName);
        await _dispatcher.SendAsync(command, cancellationToken).ConfigureAwait(false);
        return Created($"api/person/{command.Id}", new CreatdId(command.Id));
    }
    
    [HttpGet]
    [Route("{id}")]
    [ProducesResponseType(StatusCodes.Status404NotFound, Type = typeof(ValidationProblemDetails))]
    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Person))]
    public async Task<IActonResult> GetPersonAsync(
        [FromRoute] GetPersonRequest request, cancellationToken cancellationToken = default)
    {
        var query = new GetPersonQuery(request.Id);
        IOperationResult<Person> personResult = await _dispatcher.FetchAsync(query, cancellationToken)
            .ConfigureAwait(false));
        return Ok(personResult);
    }    

    // ...
        
}

// The startup class
// We will register handlers, context, validators and decorators.

public sealed class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddOptions();
        
        // common registrations...
        
        services.AddXpandableServices()
            .AddXOperationResultExceptionMiddleware()
            .AddXOperationResultConfigureJsonOptions()
            .AddXOperationResultConfigureMvcOptions()
            .AddXDataContext<PersonContext>(options => options.UseInMemoryDatabase(nameof(PersonContext))
            .AddXDispatcher()
            .AddXHandlerAccessor()
            .AddXHandlers(
                options =>
                {
                    options.UsePersistenceDecorator();
                    options.UseValidatorDecorator();
                },
                typeof(AddPersonCommandHandler).Assembly)
            .Build()
            .AddScoped<PersistenceDecoratorDelegate>(provider =>
            {
                var context = provider.GetRequiredService<PersonContext>();
                return context.SaveChangesAsync;
            })
            .AddControllers();

        // AddXpandableServices() will make available methods for registration
        // AddXOperationResultExceptionMiddleware() handles the OperationResult exception
        // AddXOperationResultConfigureJsonOptions() will add operation result converters
        // AddXOperationResultConfigureMvcOptions() will add operation result filers        
        // AddXDataContext{TContext} registers the TContext
        // AddXDispatcher() registers the dispatcher
        // AddXHandlerAccessor() registers a handlers accessor
        // AddXHandlers(options, assemblies) registers all handlers and associated classes (validators, decorators...)
        // according to the options set.
        
        // ...
    }
    
    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
        app.UseXpandableApplications()
            .UseXOperationResultExceptionMiddleware();
        
        ... 
    }
}

Wep Api Test class

We are using the MSTest template project. You can use another one. Add this package to your test project : Microsoft.AspNetCore.Mvc.Testing reference to your api test project.

[TestMethod]
[DataRow("My FirstName", "My LastName")
public async Task AddPersonTestAsync(string firstName, string lastName)
{
    // Build the api client
    
    Environment.SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development");
    var factory = new WebApplicationFactory<Program>(); // from the api
    var client = factory.CreateClient();
    
    // if you get serialization error (due to System.Text.Json), you can
    // set the serialization options by using an extension method or by globally
    // setting the IHttpClientDispatcher.SerializerOptions property.
    
    using var httpClientDispatcher = new HttpClientDispatcher(
        new HttpClientRequestBuilder(),
        new HttpClientResponseBuilder(),
        client);

    var addPersonRequest = new AddPersonRequest(GuidGuid.NewGuid(), firstName, lastName);
    using var response = await httpClientDispatcher.SendAsync(addPersonRequest).ConfigureAwait(false);

    if (!response.IsValid())
    {
         Trace.WriteLine($"{response.StatusCode}");
         IOperationResult operationResult = response.ToOperationResult().Errors;
         
         // ToOperationResult() is an extension method for HttpRestClientResponse that returns
         // an IOperationResult from the response.
         
         foreach (OperationError error in errors)         
         {
            Trace.WriteLine($"Key : {error.Key}");
            Trace.WriteLine(error.ErrorMessages.StringJoin(";"));
         }         
    }
    else
    {
        CreatedId createdId = response.Result;
        Trace.WriteLine($"Added person : {createdId.Id}");
    }
}

Blazor WebAss with Web Api using IHttpClientDispatcher

Blazor WebAss project

Add the following nuget packages : Xpandables.Net.BlazorExtended

In the Program file, replace the default code with this.

public class Program
{
    public static async Task Main(string[] args)
    {
       var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.RootComponents.Add<App>("#app");
        
        builder.Services
            .AddOptions()
            .AddXpandableServices()
                .AddXHttpClientDispatcher(httpClient =>
                {
                    httpClient.BaseAddress = new Uri("https://localhost:44396"); // your api url
                    httpClient.DefaultRequestHeaders
                        .Accept
                        .Add(new MediaTypeWithQualityHeaderValue(ContentType.Json));
                })
            .Build();
        
        // AddXHttpClientDispatcher(httpClient) will add the IHttpClientDispatcher
        // implementation using the HttpClient with your configuration.
        // if you get errors with System.Text.Json, you can use IHttpClientDispatcher.SerializerOptions
        // property to globally set the serializer options or use extension methods in your code.
                
        // custom code...
        
        await builder.Build().RunAsync();
    }
}

AddPerson.razor

<EditForm Model="@model" OnValidSubmit="AddSubmitAsync">

    <DataAnnotationsValidatorExtended @ref="@Validator" />

    <div class="form-group">
        <label for="FirstName" class="-form-label">First Name</label>
        <InputTextOnInput @bind-Value="model.FirstName" type="text" class="form-control" />
        <ValidationMessage For="@(() => model.FirstName)" />
    </div>

    <div class="form-group">
        <label for="LastName" class="col-form-label">Last Name</label>
        <InputTextOnInput @bind-Value="model.LastName" type="text" class="form-control" />
        <ValidationMessage For="@(() => model.LastName)" />
    </div>

    <div class="form-group">
        <div class="col-md-12 text-center">
            <button class="col-md-12 btn btn-primary">
                Add
            </button>
        </div>
    </div>

</EditForm>

InputTextOnInput is a component that allows text to be validated on input.

DataAnnotationsValidatorExtended is a DataAnnotationsValidator derived class that allows insertion of external errors to the edit context.

AddPerson.razor.cs

public sealed class PersonModel
{
    [Required]
    public string FirstName { get; set; } = default!;
    [Required]
    public string LastName { get; set; } = default!;
}

public partial class AddPerson
{
    protected DataAnnotationsValidatorExtended Validator { get; set; } = default!;
    [Inject]
    protected IHttpClientDispatcher HttpClientDispatcher { get; set; } = default!;
    
    private readonly PersonModel model = new();
    
    protected async Task AddSubmitAsync()
    {
        // You can use the AddPersonRequest from the api or create another class
        // We do not specify the action here because the AddPersonRequest definition
        // already hold all the necessary information.
        
        var addRequest = new AddPersonRequest(Guid.NewGuid(), model.FirstName, model.LastName);
        using var addResponse = await HttpClientDispatcher.SendAsync(addRrequest).ConfigureAwait(false);

        IOperationResult operationResult = addResponse.ToOperationResult<CreatedId>();
        Validator.ValidateModel(operationResult);

        if (addResponse.IsValid()) // or operationResult.IsSuccess
        {
            // custom code like displaying the result
            var createdId = operationResult.Value;
        }
    }    
}

Features

Usually, when registering types, we are forced to reference the libraries concerned and we end up with a very coupled set. To avoid this, you can register these types by calling an export extension method, which uses MEF: Managed Extensibility Framework.

In your api startup class

// AddXServiceExport(IConfiguration, Action{ExportServiceOptions}) adds and configures registration of services using 
// the IAddServiceExport interface implementation found in the target libraries according to the export options.
// You can use configuration file to set up the libraries to be scanned.

public class Startup
{
    ....
    services
        .AddXpandableServices()
            .AddXServiceExport(Configuration, options => options.SearchPattern = "your-search-pattern-dll")
        .Build();
    ...
}

In the library you want types to be registered

[Export(typeof(IAddServiceExport))]
public sealed class RegisterServiceExport : IAddServiceExport
{
    public void AddServices(IServiceCollection services, IConfiguration configuration)
    {
        services
            .AddXpandableServices()
                .AddXDispatcher()
                .AddXTokenEngine<TokenEngine>()
            .Build();
        ....
    }
}

Decorator pattern

You can use the extension methods to apply the decorator pattern to your types.

// This method and its extensions ensure that the supplied TDecorator" decorator is returned, wrapping the original 
// registered "TService", by injecting that service type into the constructor of the supplied "TDecorator". 
// Multiple decorators may be applied to the same "TService". By default, a new "TDecorator" instance 
// will be returned on each request, 
// independently of the lifestyle of the wrapped service. Multiple decorators can be applied to the same service type. 
// The order in which they are registered is the order they get applied in. This means that the decorator 
// that gets registered first, gets applied first, which means that the next registered decorator, 
// will wrap the first decorator, which wraps the original service type.

 services
    .AddXpandableServices()
        .XTryDecorate<TService, TDecorator>()
    .Build();
   

Suppose you want to add logging for the AddPersonCommand ...

// The AddPersonCommand decorator for logging

public sealed class AddPersonCommandHandlerLoggingDecorator : 
    ICommandHandler<AddPersonCommand>
{
    private readonly ICommandHandler<AddPersonCommand> _ decoratee;
    private readonly ILogger<AddPersonCommandHandler> _logger;
    
    public AddPersonCommandHandlerLoggingDecorator(
        ILogger<AddPersonCommandHandler> logger,
        ICommandHandler<AddPersonCommand> decoratee)
        => (_logger, _ decoratee) = (logger, decoratee);

    public async Task<IOperationResult> HandleAsync(
        AddPersonCommand command, CancellationToken cancellationToken = default)
    {
        _logger.Information(...);
        
        var response = await _decoratee.HandleAsync(command, cancellationToken).configureAwait(false);
        
        _logger.Information(...)
        
        return response;
    }
}

// Registration

services
    .AddXpandableServices()
        .XTryDecorate<AddPersonCommandHandler, AddPersonCommandHandlerLoggingDecorator>()
    .Build();

// or you can define the generic model, for all commands that implement ICommand 
// interface or something else.

public sealed class CommandLoggingDecorator<TCommand> : ICommandHandler<TCommand>
    where TCommand : class, ICommand // you can add more constraints
{
    private readonly ICommandHandler<TCommand> _ decoratee;
    private readonly ILogger<TCommand> _logger;
    
    public CommandLoggingDecorator(ILogger<TCommand> logger, ICommandHandler<TCommand> decoratee)
        => (_logger, _ decoratee) = (logger, decoratee);

    public async Task<IOperationResult<TResult>> HandleAsync(
         TCommand command, CancellationToken cancellationToken = default)
    {
        _logger.Information(...);
        
        var response = await _decoratee.HandleAsync(command, cancellationToken).configureAwait(false);
        
        _logger.Information(...)
        
        return response;
    }
}

// and for registration

// The CommandLoggingDecorator will be applied to all command handlers whose commands meet 
// the decorator's constraints : 
// To be a class and implement ICommand{TResult} interface

services
    .AddXpandableServices()
        .XTryDecorate(typeof(ICommandHandler<>), typeof(CommandLoggingDecorator<>))
    .Build();

Others

Libraries also provide with Aggregate model implementation using event sourcing and out-box pattern.