這篇涵蓋 request、command、query 的手動註冊。Stream 的部分見下方「Stream」小節。若要 改用 source-generated 的方式,見啟用 source generation。 這幾種訊息之間的關係,背景說明見分派模型。
Request
沒有回傳值的 command,用 IRequest:
public sealed record CreateOrder(Guid Id) : IRequest;
public sealed class CreateOrderHandler : IRequestHandler<CreateOrder>
{
public Task HandleAsync(CreateOrder request, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}Request/response 用 IRequest<TResponse>:
public sealed record GetOrder(Guid Id) : IRequest<OrderDto>;
public sealed record OrderDto(Guid Id, string Number);
public sealed class GetOrderHandler : IRequestHandler<GetOrder, OrderDto>
{
public Task<OrderDto> HandleAsync(GetOrder request, CancellationToken cancellationToken = default)
{
return Task.FromResult(new OrderDto(request.Id, "SO-001"));
}
}兩個都註冊好後,透過 ISender 分派:
builder.Services
.AddSendr()
.AddRequestHandler<CreateOrder, CreateOrderHandler>()
.AddRequestHandler<GetOrder, OrderDto, GetOrderHandler>();
var sender = serviceProvider.GetRequiredService<ISender>();
await sender.SendAsync(new CreateOrder(Guid.NewGuid()), cancellationToken);
var order = await sender.SendAsync(new GetOrder(Guid.NewGuid()), cancellationToken);Command 與 query(CQRS)
ICommand/ICommand<TResponse> 與 IQuery<TResponse> 是跟 IRequest 獨立的合約,有
自己的 handler 介面(ICommandHandler、IQueryHandler)與註冊方法
(AddCommandHandler、AddQueryHandler)。當你想在程式碼裡使用明確的 CQRS 語彙,而不
是泛用的 IRequest 時,可以用這一組。
public sealed record CreateOrder(Guid Id) : ICommand;
public sealed class CreateOrderHandler : ICommandHandler<CreateOrder>
{
public Task HandleAsync(CreateOrder command, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}
public sealed record GetOrder(Guid Id) : IQuery<OrderDto>;
public sealed record OrderDto(Guid Id, string Number);
public sealed class GetOrderHandler : IQueryHandler<GetOrder, OrderDto>
{
public Task<OrderDto> HandleAsync(GetOrder query, CancellationToken cancellationToken = default)
{
return Task.FromResult(new OrderDto(query.Id, "SO-001"));
}
}builder.Services
.AddSendr()
.AddCommandHandler<CreateOrder, CreateOrderHandler>()
.AddQueryHandler<GetOrder, OrderDto, GetOrderHandler>();呼叫端一樣使用 ISender.SendAsync,它會依引數的靜態型別選擇 IRequest、ICommand
或 IQuery 的多載,呼叫端不需要追蹤某個訊息屬於哪一種。
Stream
public sealed record ListOrders : IStreamRequest<OrderDto>;
public sealed class ListOrdersHandler : IStreamRequestHandler<ListOrders, OrderDto>
{
public async IAsyncEnumerable<OrderDto> HandleAsync(
ListOrders request,
[System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
{
yield return new OrderDto(Guid.NewGuid(), "SO-001");
await Task.Delay(10, cancellationToken);
yield return new OrderDto(Guid.NewGuid(), "SO-002");
}
}builder.Services
.AddSendr()
.AddStreamRequestHandler<ListOrders, OrderDto, ListOrdersHandler>();
var streamSender = serviceProvider.GetRequiredService<IStreamSender>();
await foreach (var order in streamSender.SendStream(new ListOrders(), cancellationToken))
{
Console.WriteLine(order.Number);
}ISender 本身也實作了 IStreamSender,所以既有的 ISender 實例可以直接分派 stream,
不需要另外再解析一次 IStreamSender。
錯誤情況
- 為同一個 request/response 組合註冊第二個 handler(不論透過
AddRequestHandler、AddCommandHandler、AddQueryHandler,或AddStreamRequestHandler),會丟出InvalidOperationException。 - 分派一個沒有註冊 handler 的 request,會丟出
InvalidOperationException,訊息裡會 指名缺少的那個註冊呼叫。對 stream 來說,這會發生在開始列舉時,而不是呼叫SendStream的時候。
確切的錯誤訊息見例外與診斷。