Instructor.Core 1.0.0

Instructor

Overview

Instructor is a lightweight, minimalist library focused on one job: dispatching instructions (commands and queries) to their respective handlers.

It integrates seamlessly with your existing IoC container—like Autofac or Microsoft.Extensions.DependencyInjection—without enforcing conventions or adding unnecessary abstractions. All handler resolution is delegated to the container you already use.

Example Usage

A working example can be found in the Instructor GitHub Repository.

Define Commands and Queries (aka Instructions)

Just implement IInstruction<TValue> for each instruction.

public class AddCustomerCommand: IInstruction<None>
{
    public Guid   CustomerID   { get;}
    public string CustomerName { get; } = default!;

    public AddCustomerCommand(CustomerData customerData)

        => (CustomerID, CustomerName) = (customerData.CustomerID, customerData.CustomerName);
}

public class GetCustomerQuery(Guid customerID) : IInstruction<CustomerData>
{
    public Guid CustomerID { get; } = customerID;
}

Define Handlers

Implement IInstructionHandler<TInstruction, TValue> or optionally the marker interfaces ICommandHandler<TInstruction, TValue> or IQueryHandler<TInstruction, TValue>.

public class AddCustomerCommandHandler : ICommandHandler<AddCustomerCommand, None>
{
    public AddCustomerCommandHandler(){ }//TODO: inject database dependencies here

    public async Task<None> Handle(AddCustomerCommand instruction, CancellationToken cancellationToken)
    {
        await Console.Out.WriteLineAsync($"Added customer {instruction.CustomerName} with ID {instruction.CustomerID} to the database (not).");
        return None.Value;
    }
}

public class GetCustomerQueryHandler : IQueryHandler<GetCustomerQuery, CustomerData>
{
    public GetCustomerQueryHandler() { } //TODO: inject dependencies here as usual
    public async Task<CustomerData> Handle(GetCustomerQuery instruction, CancellationToken cancellationToken)
    {
        await Console.Out.WriteLineAsync($"Getting the customer with ID {instruction.CustomerID} from the database (not).");

        return new CustomerData(instruction.CustomerID, "John Doe");
    }
}

Register the InstructionDispatcher and its factory delegate that defers resolution of instruction handlers via the underlying IoC container

Autofcac example:

   /*
       * Scan assemblies or add handlers manually i.e. builder.RegisterType<AddCustomerCommandHandler>().As<IInstructionHandler<AddCustomerCommand, None>>()
   */
   builder.RegisterAssemblyTypes(AppDomain.CurrentDomain.GetAssemblies()).AsClosedTypesOf(typeof(IInstructionHandler<,>));
   builder.Register<InstructionDispatcher>(c =>
   {
       var context = c.Resolve<IComponentContext>();
       return new InstructionDispatcher(type => context.Resolve(type));
   
   }).As<IInstructionDispatcher>().InstancePerLifetimeScope();

Microsoft.Extensions.DependencyInjection example:

   /*
       * Add handlers manually or get a package like Scrutor to scan assemblies
   */
   .Services.AddTransient<IInstructionHandler<AddCustomerCommand, None>, AddCustomerCommandHandler>()
           .AddTransient<IInstructionHandler<GetCustomerQuery, CustomerData>, GetCustomerQueryHandler>()
           .AddSingleton<IInstructionDispatcher>(provider => new InstructionDispatcher(type => provider.GetRequiredService(type)))

Send your instructions via the InstructionDispatcher to be processed by the handlers

   private readonly IInstructionDispatcher _instructionDispatcher;//set by constructor injection

   var newCustomer = new CustomerData(Guid.NewGuid(), "John Doe");//Data recieved from some client

   _ = await __instructionDispatcher.SendInstruction(new AddCustomerCommand(newCustomer));//just dispatch the command (instruction) for handling

   var customerData = await __instructionDispatcher.SendInstruction(new GetCustomerQuery(newCustomer.CustomerID));