TaskBatcher 4.0.9

TaskBatcher

TaskBatcher automatically collects incoming requests, groups them into batches, and processes them using a single bulk method. This reduces database load, number of round trips, and improves application throughput.

✨ Features

• Automatic request batching
• Auto-discovery of bulk methods via attribute
• Strongly typed request & response models
• Correlates requests/responses using Guid keys
• Parallel batch workers
• Zero boilerplate for using bulk methods
• Auto-generated batch keys based on service + request/response types

🚀 Quick Start

1) Register TaskBatcher

Must be done after all services are registered.

builder.Services.ConfigureTaskBatchers(typeof(Program).Assembly);

2) Mark your bulk method

Use the [TaskBatchOperation] attribute

[TaskBatchOperation]

3) Implement the bulk method

Your bulk method must:

• accept Dictionary<Guid, TInput>
• return Dictionary<Guid, TResult>
• preserve key order (keys from request → same keys in response)

[TaskBatchOperation]
public async Task<Dictionary<Guid, Result>> MyBulkMethod(Dictionary<Guid, Input> reqs)
{
    return reqs.ToDictionary(
        el => el.Key,
        el => new Result()
    );
}

4) Inject ITaskBatcher and run single request

public class MyService(ITaskBatcher taskBatcher) : IMyService
{
    public async Task<Result> Example(Input req, CancellationToken ct)
    {
        return await taskBatcher.RunAsync<Input, Result>(
            this, // TaskBatcher auto-maps to correct bulk method
            req,
            ct
        );
    }
}

TaskBatcher automatically discovers the appropriate bulk method based on:

• the service type (this)
• the input type (Input)
• the result type (Result)

⚙️ TaskBatcher Options

new TaskBatcherOptions
{
    BatchSize = 50,		// max requests per batch
    WaitForBatchFill = TimeSpan.FromMilliseconds(10),		// how long to wait before execute bulk method
    WorkerCount = 1		// how many batches can run in parallel
};

📌 Bulk Method Requirements

A valid bulk method must:

1. Be annotated with [TaskBatchOperation]
2. Accept: Dictionary<Guid, TInput>
3. Return: Task<Dictionary<Guid, TResult>>
4. Response keys must match request keys
5. The service containing the method must be registered in DI before calling ConfigureTaskBatchers

🧠 Complete Example

public class UserService(
    ITaskBatcher taskBatcher,
    IUserRepository repo
) : IUserService
{
    [TaskBatchOperation(batchSize: 500)]
    public async Task<Dictionary<Guid, UserRes>> BulkGetUsers(
        Dictionary<Guid, UserReq> reqs)
    {
        var ids = reqs.Values.Select(x => x.UserId).ToList();
        var users = await repo.GetUsersByIds(ids);

        return reqs.ToDictionary(
            x => x.Key,
            x => users[x.Value.UserId]
        );
    }

    public Task<UserRes> GetUser(UserReq req, CancellationToken ct)
        => taskBatcher.RunAsync<UserReq, UserRes>(this, req, ct);
}

🛠️ Minimal Setup

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IMyService, MyService>();
// must come after service registrations
builder.Services.ConfigureTaskBatchers(typeof(Program).Assembly);
var app = builder.Build();
app.Run();

❗ Troubleshooting

❌ Error: No TaskBatch operation registered for X Possible causes:

• Service not registered before ConfigureTaskBatchers
• Assembly passed to ConfigureTaskBatchers does not include your services Fix:

builder.Services.AddScoped<IMyService, MyService>();
builder.Services.ConfigureTaskBatchers(typeof(Program).Assembly);

❌ Error: response keys do not match request keys

Correct:

return reqs.ToDictionary(
    x => x.Key,
    x => new Result(...)
);

📄 License

MIT