Euonia.Bus.Abstract
2026.5.0
dotnet add package Euonia.Bus.Abstract --version 2026.5.0
NuGet\Install-Package Euonia.Bus.Abstract -Version 2026.5.0
<PackageReference Include="Euonia.Bus.Abstract" Version="2026.5.0" />
<PackageVersion Include="Euonia.Bus.Abstract" Version="2026.5.0" />
<PackageReference Include="Euonia.Bus.Abstract" />
paket add Euonia.Bus.Abstract --version 2026.5.0
#r "nuget: Euonia.Bus.Abstract, 2026.5.0"
#:package Euonia.Bus.Abstract@2026.5.0
#addin nuget:?package=Euonia.Bus.Abstract&version=2026.5.0
#tool nuget:?package=Euonia.Bus.Abstract&version=2026.5.0
Euonia.Bus.Abstract
Euonia 消息总线的抽象契约层:消息信封与上下文、消息分类约定、传输策略、注解、序列化、可靠性存储(发件箱 / 收件箱 / 死信)以及事件体系。它是所有总线传输与 Euonia.Bus 引擎的扩展基础。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Bus - NuGet 包:
Euonia.Bus.Abstract
安装
dotnet add package Euonia.Bus.Abstract
主要功能
- 消息分类:标记接口
IUnicast、IMulticast、IRequest<TResponse>,或对应的[Unicast]、[Multicast]、[Request]特性。 - 信封与上下文:
IMessageEnvelope<T>携带 MessageId、CorrelationId、ConversationId、Channel、Authorization、User、Metadata 与 Payload;IMessageContext暴露同样的元数据与请求头,并提供Response、Failure回复入口。 - 传输契约:
ITransporter定义PublishAsync(多播)、SendAsync(单播,可返回响应)与CallAsync(请求-响应)。 - 约定与策略:
IMessageConvention、ITransportStrategy及其组合构建器,决定消息走本地还是分布式传输。 - 可靠性:
IOutboxStore、IInboxStore、IDeadLetterStore、IDeadLetterService与对应条目类型。 - 接收者契约:
IRecipientRegistrar、IRecipient、IConsumer、ISubscriber、IExecutor。 - 事件与异常:投递、接收、确认、回复、处理等事件参数,以及分层异常类型。
快速开始
定义消息并声明其分类:
using Nerosoft.Euonia.Bus;
// 发布-订阅(多播)
[Multicast]
public sealed class OrderCreated
{
public long OrderId { get; init; }
}
// 点对点(单播)
[Unicast]
public sealed class CancelOrder
{
public long OrderId { get; init; }
}
// 请求-响应
[Request(typeof(OrderStatus))]
public sealed class GetOrderStatus
{
public long OrderId { get; init; }
}
public sealed class OrderStatus
{
public long OrderId { get; init; }
public string State { get; init; } = null!;
}
也可以使用标记接口:
public sealed class PaymentReceived : IMulticast
{
public long OrderId { get; init; }
}
自定义传输器时实现 ITransporter:
public sealed class MyTransporter : ITransporter
{
public string Name => "my-transport";
public event EventHandler<MessageDeliveredEventArgs>? Delivered;
public Task PublishAsync<TMessage>(IMessageEnvelope<TMessage> message, CancellationToken cancellationToken = default)
=> throw new NotImplementedException();
public Task<TResponse> SendAsync<TMessage, TResponse>(IMessageEnvelope<TMessage> message, CancellationToken cancellationToken = default)
=> throw new NotImplementedException();
public Task<TResponse> CallAsync<TRequest, TResponse>(IMessageEnvelope<TRequest> message, CancellationToken cancellationToken = default)
=> throw new NotImplementedException();
}
核心类型
| 类型 | 作用 |
|---|---|
ITransporter |
传输抽象:发布、发送、调用 |
IMessageEnvelope / IMessageEnvelope<T> |
消息信封与元数据 |
IMessageContext / MessageContext |
处理器执行上下文与响应/失败回调 |
RoutedMessage / RoutedMessage<T> / RoutedMessage<T, TResponse> |
路由消息基类与泛型消息(定义于 Euonia.Bus) |
IMessageSerializer |
序列化契约 |
IMessageConvention / IMessageConventionBuilder |
消息分类约定及其构建器 |
ITransportStrategy / ITransportStrategyBuilder |
出站/入站传输选择策略及其构建器 |
IOutboxStore / IInboxStore / IDeadLetterStore |
可靠性存储契约 |
IDeadLetterService |
死信查询、重放与丢弃 |
IRecipientRegistrar / IRecipient / IConsumer / ISubscriber / IExecutor |
接收者契约 |
ChannelAttribute / SubscribeAttribute / EnqueueAttribute |
通道、订阅与队列注解 |
约定与策略的默认实现或基类(如
AnnotationMessageConvention、BaseTransportStrategy)位于Euonia.Bus。
使用示例
自定义消息约定与传输策略,并交给 IConfigurator 组合:
using Nerosoft.Euonia.Bus;
// 自定义约定:按类型名后缀分类,与内置默认约定按「任一命中」组合
public sealed class SuffixMessageConvention : IMessageConvention
{
public string Name => "Suffix convention";
public bool IsUnicast(string channel, Type type)
=> type.Name.EndsWith("Command", StringComparison.Ordinal);
public bool IsMulticast(string channel, Type type)
=> type.Name.EndsWith("Event", StringComparison.Ordinal);
public bool IsRequest(string channel, Type type)
=> type.Name.EndsWith("Query", StringComparison.Ordinal);
}
// 自定义策略:只允许指定命名空间下的消息走该传输
public sealed class NamespaceTransportStrategy : ITransportStrategy
{
public string Name => "Namespace strategy";
public bool Outgoing(string channel, Type type)
=> type.Namespace?.StartsWith("MyApp.Contracts", StringComparison.Ordinal) == true;
public bool Incoming(string channel, Type type) => Outgoing(channel, type);
}
services.AddConfiguratorBuilder(config => config
.SetConvention(convention =>
{
convention.Add<SuffixMessageConvention>();
convention.EvaluateMulticast((_, type) => type.Name.EndsWith("IntegrationEvent", StringComparison.Ordinal));
})
.SetStrategy("RabbitMq", strategy =>
{
strategy.Add<NamespaceTransportStrategy>();
strategy.Add(new AnnotationTransportStrategy(["RabbitMq"]));
strategy.EvaluateOutgoing((channel, type) => !string.IsNullOrWhiteSpace(channel));
strategy.EvaluateIncoming((channel, type) => !string.IsNullOrWhiteSpace(channel));
})
.SetChannelResolver(type => type.FullName!, replaceDefault: true)
.RegisterChannel(typeof(Program).Assembly));
实现自定义可靠性存储时按契约补齐必选成员即可(IOutboxStore 另有带默认实现的 GetAndCache、GetPendingMessages(DateTime)、Cleanup(DateTime)):
using Nerosoft.Euonia.Bus;
public sealed class MyOutboxStore : IOutboxStore
{
public bool Insert(OutboxEntry entry) => throw new NotImplementedException();
public void MarkAsSuccess(string messageId, string transport) => throw new NotImplementedException();
public void MarkAsFailed(string messageId, string transport, string errorMessage) => throw new NotImplementedException();
public void MarkAsDeadLettered(string messageId, string transport, string errorMessage) => throw new NotImplementedException();
public OutboxEntry? Get(string messageId) => throw new NotImplementedException();
public IReadOnlyList<OutboxTransport> GetFailedMessages() => throw new NotImplementedException();
}
Insert(IMessageEnvelope, IReadOnlyList<string>)、GetAndCache、ClearCache、GetPendingMessages(DateTime) 与 Cleanup(DateTime) 都有默认实现,可按需覆盖。
注意事项 / 限制
- 与
Euonia.Bus共用根命名空间:两个程序集都是Nerosoft.Euonia.Bus,using Nerosoft.Euonia.Bus;会同时导入二者;但类型归属仍按程序集区分,例如RoutedMessage只在Euonia.Bus中,仅引用本包时不可用。 - 本包不含传输器与默认约定/策略:
MessageContext等少数类型是具体实现,但传输器、序列化器、发件箱/收件箱/死信存储的可用实现位于Euonia.Bus或具体传输包。 - 约定与策略会被并发调用:
StrategicDispatcher与BaseMessageConvention会缓存判定结果,自定义实现必须线程安全且避免在求值中做阻塞 I/O。 IMessageContext是IDisposable:处理器不应把上下文保存到字段或缓存中,处理结束后其生命周期由总线管理。- 信封字段可能为空:
Authorization、User、RequestTraceId在请求作用域外为null,消费端必须判空后再使用。 - 可靠性存储需自行保证幂等:
IOutboxStore.Insert对重复MessageId应返回false,IInboxStore需按消息标识去重,否则 at-least-once 语义会退化为重复处理。
常见问题与故障排查
只引用 Euonia.Bus.Abstract 时找不到 RoutedMessage
原因:RoutedMessage / RoutedMessage<T> / RoutedMessage<T, TResponse> 定义在 Euonia.Bus,抽象包只声明 IMessageEnvelope 契约。
解决:引用 Euonia.Bus,或只面向 IMessageEnvelope<T> 编程。
自定义 IHandler<T> 没有被调用
原因:只把处理器注册进 DI(AddMessageHandler)还不够,通道注册来自 RegisterChannel(...) 或 Euonia:Bus:AutoLoadAssemblies;方法签名也必须是 HandleAsync(TMessage, IMessageContext, CancellationToken)。
解决:在 AddConfiguratorBuilder 中调用 config.RegisterChannel(typeof(Program).Assembly);确认处理器实现了 IHandler<,> 且不是抽象类。
自定义 IMessageConvention 不生效
原因:约定未通过 SetConvention 加入构建器;或首次判定后直接替换了字段而没有经过 IMessageConventionBuilder(构建器才会重置判定缓存)。
解决:统一用 convention.Add<TConvention>() 或 Evaluate* 注册(BaseMessageConvention.cs:137-165)。
自定义 IOutboxStore 编译不通过
原因:Insert(OutboxEntry)、MarkAsSuccess、MarkAsFailed、MarkAsDeadLettered、Get、GetFailedMessages 是抽象成员;Insert(IMessageEnvelope, IReadOnlyList<string>) 等只是带默认实现的便捷重载。
解决:按 IOutboxStore 的必选成员补齐;重复 MessageId 的 Insert 返回 false,终态必须走 MarkAsDeadLettered。
消费端读到的 Authorization / User 为 null
原因:请求作用域外(后台任务、定时任务)没有这些信息,接口声明为可空。
解决:判空后再使用;需要跨进程身份时由发送端显式写入 Metadata 或自定义头。
最佳实践
- 把消息契约放进独立程序集:生产端与消费端共享同一份消息类型与
[Channel]定义,避免通道名/类型名漂移。 - 约定与策略写成纯函数:
IsUnicast/Outgoing会在分发热路径上被调用并缓存,不要在其中做 I/O 或依赖可变全局状态。 - 自定义存储必须幂等且可清理:
Insert对重复键返回false,并实现Cleanup(DateTime)防止存储无界增长。 - 不要缓存
IMessageContext:它实现IDisposable,生命周期由总线管理,处理结束即失效。 - 序列化器按名称解析:内置键为
SystemTestJson与NewtonsoftJson,传输器通过SerializerProvider选择,自定义序列化器需用相同键注册。
版本与兼容
- 目标框架:
net10.0、net11.0。 - 关键依赖:
Euonia.Core、Microsoft.Extensions.DependencyInjection.Abstractions。 - 版本策略:随仓库
project.props统一管理,本文不固定版本号。 - 升级注意:与
Euonia.Bus共用根命名空间,类型归属按程序集区分;仅引用本包不会得到传输器、默认约定/策略或可靠性存储实现。
相关包
Euonia.Bus—— 总线运行时引擎Euonia.Bus.InMemory—— 进程内传输Euonia.Bus.RabbitMq—— RabbitMQ 传输Euonia.Bus.ActiveMq—— ActiveMQ 传输Euonia.Bus.Http/Euonia.Bus.Grpc—— 远程调用传输
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Euonia.Core (>= 2026.5.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0.0)
-
net11.0
- Euonia.Core (>= 2026.5.0)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Euonia.Bus.Abstract:
| Package | Downloads |
|---|---|
|
Euonia.Bus.RabbitMq
Euonia 总线 RabbitMQ 传输:分布式发布/订阅与请求-响应消息,支持持久连接、fanout 交换机、优先级队列、死信与 Polly 重试。 / RabbitMQ transport for Euonia Bus: distributed publish/subscribe and request-response messaging with persistent connections, fanout exchanges, priority queues, dead lettering and Polly-based retries. |
|
|
Euonia.Bus
Euonia 消息总线引擎:处理器发现与注册、约定与传输策略分发、Publish/Send/Call API、中间件管道、序列化、Outbox/Inbox 可靠性及 OpenTelemetry 遥测。 / Message bus engine for Euonia: handler discovery and registration, convention and transport-strategy dispatch, publish/send/call APIs, middleware pipelines, serialization, outbox/inbox reliability and OpenTelemetry instrumentation. |
|
|
Euonia.Bus.InMemory
Euonia 总线进程内内存传输:完整的 ITransporter 实现,无需外部基础设施,适用于开发、测试与单进程消息场景。 / In-process memory transport for Euonia Bus: a complete ITransporter implementation for development, testing and single-process messaging without external infrastructure. |
|
|
Euonia.Bus.ActiveMq
Euonia 总线 Apache ActiveMQ 传输:基于 NMS 的 Topic 与 Queue 消息,通过临时回复队列和关联 ID 完成请求-响应,支持持久连接与 Polly 重试。 / Apache ActiveMQ transport for Euonia Bus: topic and queue messaging over NMS, request-response via temporary reply queues and correlation ids, persistent connections and Polly-based retries. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 249 | 11/13/2026 |
| 2026.4.7 | 185 | 11/3/2026 |
| 2026.4.6 | 187 | 10/28/2026 |
| 2026.4.5 | 212 | 10/19/2026 |
| 2026.4.4 | 172 | 10/19/2026 |
| 2026.4.3 | 184 | 10/1/2026 |
| 2026.4.1 | 176 | 9/24/2026 |
| 2026.4.0 | 180 | 9/22/2026 |
| 2026.3.16 | 240 | 9/8/2026 |
| 2026.3.15 | 244 | 9/2/2026 |
| 2026.3.14 | 189 | 8/30/2026 |
| 2026.3.13 | 190 | 8/29/2026 |
| 2026.3.12 | 193 | 8/28/2026 |
| 2026.3.11 | 187 | 8/27/2026 |
| 2026.3.10 | 194 | 8/26/2026 |
| 2026.3.9 | 195 | 8/25/2026 |
| 2026.3.8 | 194 | 8/24/2026 |
| 2026.3.7 | 221 | 8/20/2026 |
| 2026.3.6 | 200 | 8/20/2026 |
| 2026.3.5 | 215 | 8/19/2026 |