@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/22-/344/272/213/344/273/266/345/214/257/346/265/201/346/216/222EventBus.md

@@ -0,0 +1,448 @@
+# 22. 事件匯流排（EventBus）
+
+---
+
+## 22.1 概述
+
+事件匯流排是對**發佈-訂閱模式**的一種實作，允許不同元件之間彼此通訊而不需要相互依賴，達到解耦的目的。
+
+> Furion 框架已內建此功能。非 Furion 框架可安裝 `Jaina` 套件：`dotnet add package Jaina`
+
+---
+
+## 22.2 快速入門
+
+### 22.2.1 定義事件處理程式
+
+```csharp
+public class ToDoEventSubscriber : IEventSubscriber
+{
+    private readonly ILogger<ToDoEventSubscriber> _logger;
+    public ToDoEventSubscriber(ILogger<ToDoEventSubscriber> logger) => _logger = logger;
+
+    [EventSubscribe("ToDo:Create")]
+    public async Task CreateToDo(EventHandlerExecutingContext context)
+    {
+        _logger.LogInformation("建立 ToDo：{Name}", context.Source.Payload);
+        // 4.9.5.24+ 支援 context.GetPayload<string>()
+        await Task.CompletedTask;
+    }
+
+    // 支援多個事件 Id
+    [EventSubscribe("ToDo:Create")]
+    [EventSubscribe("ToDo:Update")]
+    public async Task CreateOrUpdateToDo(EventHandlerExecutingContext context) { }
+
+    // 支援列舉型別（3.4.3+）
+    [EventSubscribe(YourEnum.Some)]
+    public async Task EnumHandler(EventHandlerExecutingContext context)
+    {
+        var eventEnum = context.Source.EventId.ParseToEnum();
+    }
+
+    // 支援正則表達式匹配（4.2.10+）
+    [EventSubscribe("正則表達式", FuzzyMatch = true)]
+    public async Task RegexHandler(EventHandlerExecutingContext context) { }
+
+    // 異常重試設定（4.2.10+）
+    [EventSubscribe("test:error", NumRetries = 3)]
+    [EventSubscribe("test:error", NumRetries = 3, RetryTimeout = 1000)]
+    [EventSubscribe("test:error", NumRetries = 3, ExceptionTypes = new[] { typeof(ArgumentException) })]
+    public async Task ExceptionHandler(EventHandlerExecutingContext context) { }
+
+    // Order 編排（4.8.0+）
+    [EventSubscribe("test:order", Order = 1)]
+    public async Task OrderedHandler(EventHandlerExecutingContext context) { }
+}
+```
+
+### 22.2.2 發佈事件訊息
+
+```csharp
+public class ToDoController : ControllerBase
+{
+    private readonly IEventPublisher _eventPublisher;
+    public ToDoController(IEventPublisher eventPublisher) => _eventPublisher = eventPublisher;
+
+    public async Task CreateDoTo(string name)
+    {
+        // 發佈
+        await _eventPublisher.PublishAsync(new ChannelEventSource("ToDo:Create", name));
+
+        // 延遲發佈（3 秒後）
+        await _eventPublisher.PublishDelayAsync(new ChannelEventSource("ToDo:Create", name), 3000);
+
+        // 簡化方式（3.4.3+）
+        await _eventPublisher.PublishAsync("ToDo:Create", name);
+        await _eventPublisher.PublishDelayAsync("ToDo:Create", 3000, name);
+        await _eventPublisher.PublishAsync(YourEnum.Some); // 列舉
+    }
+}
+```
+
+### 22.2.3 註冊事件服務
+
+```csharp
+services.AddEventBus(builder =>
+{
+    builder.AddSubscriber<ToDoEventSubscriber>();
+    builder.AddSubscriber(typeof(ToDoEventSubscriber));
+    builder.AddSubscribers(ass1, ass2);
+});
+```
+
+> **懶人方式**：實作 `ISingleton` 介面即可自動註冊，無需 `AddSubscriber`：
+> ```csharp
+> public class ToDoEventSubscriber : IEventSubscriber, ISingleton { }
+> ```
+
+---
+
+## 22.3 自訂事件源
+
+實作 `IEventSource` 介面：
+
+```csharp
+public class ToDoEventSource : IEventSource
+{
+    public string ToDoName { get; set; }        // 自訂屬性
+    public string EventId { get; set; }
+    public object Payload { get; set; }
+    public DateTime CreatedTime { get; set; } = DateTime.UtcNow;
+    public bool ConsumeOnce { get; set; }       // 4.9.1.24+：僅消費一次
+
+    [JsonIgnore]
+    public CancellationToken CancellationToken { get; set; }
+}
+
+// 使用
+await _eventPublisher.PublishAsync(new ToDoEventSource("ToDo:Create", "我的 ToDo"));
+```
+
+---
+
+## 22.4 自訂事件源儲存器
+
+預設使用 `Channel`，可替換為 Redis、RabbitMQ、Kafka 等。實作 `IEventSourceStorer` 介面即可。
+
+### 22.4.1 Redis
+
+```bash
+Install-Package Microsoft.Extensions.Caching.StackExchangeRedis
+```
+
+核心邏輯：Redis Pub/Sub 接收訊息 → 反序列化為 `ChannelEventSource` → 寫入記憶體 `Channel`；發佈時序列化後透過 Redis Publish 傳送。
+
+```csharp
+services.AddEventBus(options =>
+{
+    var conn = ConnectionMultiplexer.Connect("localhost");
+    var storer = new RedisEventSourceStorer(conn, "routeKey", 12000);
+    options.ReplaceStorer(sp => storer);
+});
+```
+
+### 22.4.2 RabbitMQ
+
+```bash
+Install-Package RabbitMQ.Client
+```
+
+核心邏輯：RabbitMQ Consumer 接收訊息 → 反序列化 → 寫入記憶體 Channel + BasicAck；發佈時序列化後 BasicPublish。
+
+```csharp
+services.AddEventBus(options =>
+{
+    var factory = new ConnectionFactory { UserName = "admin", Password = "q1w2e3" };
+    var storer = new RabbitMQEventSourceStorer(factory, "routeKey", 12000);
+    options.ReplaceStorer(sp => storer);
+});
+```
+
+### 22.4.3 Kafka
+
+```bash
+Install-Package Confluent.Kafka
+```
+
+核心邏輯：Kafka Consumer 訂閱 Topic → 反序列化 → 寫入記憶體 Channel；發佈時透過 Producer 非同步發送。
+
+```csharp
+services.AddEventBus(options =>
+{
+    var consumerConf = new ConsumerConfig { BootstrapServers = "xxx:9092", GroupId = "Consumer", AutoOffsetReset = AutoOffsetReset.Earliest };
+    var producerConf = new ProducerConfig { BootstrapServers = "xxx:9092" };
+    var storer = new KafkaEventSourceStore(consumerConf, producerConf, "topic", 12000);
+    options.ReplaceStorer(sp => storer);
+});
+```
+
+> 完整 Redis / RabbitMQ / Kafka 儲存器原始碼請參閱 Furion 官方文件。
+
+---
+
+## 22.5 自訂事件發佈者
+
+```csharp
+public class ToDoEventPublisher : IEventPublisher
+{
+    private readonly IEventSourceStorer _storer;
+    public ToDoEventPublisher(IEventSourceStorer storer) => _storer = storer;
+
+    public async Task PublishAsync(IEventSource eventSource)
+        => await _storer.WriteAsync(eventSource, eventSource.CancellationToken);
+}
+
+services.AddEventBus(builder => builder.ReplacePublisher<ToDoEventPublisher>());
+```
+
+---
+
+## 22.6 事件執行監視器
+
+```csharp
+public class ToDoEventHandlerMonitor : IEventHandlerMonitor
+{
+    private readonly ILogger<ToDoEventHandlerMonitor> _logger;
+    public ToDoEventHandlerMonitor(ILogger<ToDoEventHandlerMonitor> logger) => _logger = logger;
+
+    public Task OnExecutingAsync(EventHandlerExecutingContext context)
+    {
+        _logger.LogInformation("執行之前：{EventId}", context.Source.EventId);
+        return Task.CompletedTask;
+    }
+
+    public Task OnExecutedAsync(EventHandlerExecutedContext context)
+    {
+        _logger.LogInformation("執行之後：{EventId}", context.Source.EventId);
+        if (context.Exception != null)
+            _logger.LogError(context.Exception, "執行出錯：{EventId}", context.Source.EventId);
+        return Task.CompletedTask;
+    }
+}
+
+services.AddEventBus(builder => builder.AddMonitor<ToDoEventHandlerMonitor>());
+```
+
+---
+
+## 22.7 事件執行器
+
+自訂執行策略（逾時控制、失敗重試、熔斷等）：
+
+```csharp
+public class RetryEventHandlerExecutor : IEventHandlerExecutor
+{
+    public async Task ExecuteAsync(EventHandlerExecutingContext context, Func<EventHandlerExecutingContext, Task> handler)
+    {
+        await Retry.InvokeAsync(async () => await handler(context), 3, 1000);
+    }
+}
+
+services.AddEventBus(builder => builder.AddExecutor<RetryEventHandlerExecutor>());
+```
+
+---
+
+## 22.8 使用有作用域的服務
+
+EventBus 所有服務均為**單例**，需使用作用域服務時：
+
+```csharp
+public class ToDoEventSubscriber : IEventSubscriber
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+    public ToDoEventSubscriber(IServiceScopeFactory scopeFactory) => _scopeFactory = scopeFactory;
+
+    [EventSubscribe("ToDo:Create")]
+    public async Task CreateToDo(EventHandlerExecutingContext context)
+    {
+        using var scope = _scopeFactory.CreateScope();
+        var service = scope.ServiceProvider.GetRequiredService<IScopedProcessingService>();
+    }
+}
+```
+
+> ⚠️ 避免在建構子中解析非單例服務。
+
+---
+
+## 22.9 訂閱未察覺異常
+
+```csharp
+services.AddEventBus(builder =>
+{
+    builder.UnobservedTaskExceptionHandler = (obj, args) => { /* 處理 */ };
+});
+```
+
+---
+
+## 22.10 事件匯流排工廠（4.2.10+）
+
+```csharp
+// 動態新增訂閱
+await _eventBusFactory.Subscribe("xxx", async ctx => { Console.WriteLine("動態訂閱"); });
+
+// 動態移除訂閱
+await _eventBusFactory.Unsubscribe(eventId);
+```
+
+---
+
+## 22.11 MessageCenter 靜態類（4.3.3+）
+
+```csharp
+await MessageCenter.PublishAsync("messageId", new {});
+
+MessageCenter.Subscribe("messageId", async ctx => { });
+
+MessageCenter.Unsubscribe("messageId");
+```
+
+---
+
+## 22.12 重試失敗回呼（4.6.1+）
+
+```csharp
+public class EventFallbackPolicy : IEventFallbackPolicy
+{
+    public async Task CallbackAsync(EventHandlerExecutingContext context, Exception ex)
+    {
+        // 重試多次仍失敗時的處理
+    }
+}
+
+services.AddEventBus(options => options.AddFallbackPolicy<EventFallbackPolicy>());
+
+[EventSubscribe("test:error", NumRetries = 3, FallbackPolicy = typeof(EventFallbackPolicy))]
+public async Task TestError(EventHandlerExecutingContext context) { throw new NotImplementedException(); }
+```
+
+---
+
+## 22.13 儲存器不可用時回退
+
+```csharp
+services.AddEventBus(options =>
+{
+    options.ReplaceStorerOrFallback(sp => new RedisEventSourceStorer(...));
+});
+```
+
+> 僅支援啟動時檢查，不支援執行階段故障轉移。
+
+---
+
+## 22.14 EventBusOptionsBuilder 設定
+
+| 屬性 / 方法 | 說明 |
+|-------------|------|
+| `ChannelCapacity` | 記憶體通道容量，預設 `12000` |
+| `UnobservedTaskExceptionHandler` | 未察覺異常處理 |
+| `UseUtcTimestamp` | 使用 UTC 時間，預設 `false` |
+| `FuzzyMatch` | 全域模糊匹配（正則），預設 `false` |
+| `LogEnabled` | 啟用日誌，預設 `true` |
+| `AddSubscriber<T>()` | 新增訂閱者 |
+| `ReplacePublisher<T>()` | 替換發佈者 |
+| `ReplaceStorer(Func<...>)` | 替換儲存器 |
+| `ReplaceStorerOrFallback(Func<...>)` | 替換儲存器（失敗回退預設） |
+| `AddMonitor<T>()` | 新增監視器 |
+| `AddExecutor<T>()` | 新增執行器 |
+| `AddFallbackPolicy<T>()` | 新增重試失敗回呼策略 |
+
+---
+
+## 22.15 高頻訊息處理
+
+IoT、日誌記錄等高頻場景，使用**類全域作用域**避免頻繁建立/銷毀：
+
+```csharp
+public class ToDoEventSubscriber : IEventSubscriber, IDisposable
+{
+    private readonly IServiceScope _serviceScope;
+
+    public ToDoEventSubscriber(IServiceScopeFactory scopeFactory)
+        => _serviceScope = scopeFactory.CreateScope();
+
+    [EventSubscribe("iot:log")]
+    public async Task LogFromIoT(EventHandlerExecutingContext context)
+    {
+        var service = _serviceScope.ServiceProvider.GetRequiredService<IScopedProcessingService>();
+    }
+
+    public void Dispose() => _serviceScope.Dispose();
+}
+```
+
+---
+
+## 22.16 事件執行結果訂閱（4.9.1.47+）
+
+```csharp
+_eventPublisher.OnExecuted += (sender, args) =>
+{
+    Console.WriteLine($"事件 {args.Source.EventId} 狀態：{args.Status}，例外：{args.Exception}，結果：{args.Result}");
+    // args.Result 為 4.9.7.61+ 新增
+};
+```
+
+> 推薦在 `Startup.cs` 的 `Configure` 中或**單例服務**中訂閱，避免重複多播訂閱。非單例服務中訂閱後需在 `Dispose` 中移除。
+
+---
+
+## 22.17 IIS 部署
+
+部署到 IIS 時需**停用應用程式集區回收**，避免事件匯流排服務進入休眠。
+
+---
+
+## 22.18 第三方 CAP 整合
+
+```csharp
+builder.Services.AddCap(options =>
+{
+    options.UseInMemoryStorage();
+    options.UseInMemoryMessageQueue();
+}).AddSubscriberAssembly(App.Assemblies.ToArray());
+```
+
+---
+
+## 22.19 在 WinForm / WPF 中使用
+
+```csharp
+// 發送事件（將控制項作為 Payload）
+await _eventPublisher.PublishAsync("update.textbox", textBox1);
+
+// 訂閱並更新 UI
+[EventSubscribe("update.textbox")]
+public async Task UpdateTextBox(EventHandlerExecutingContext context)
+{
+    var textbox = context.GetPayload<TextBox>(); // 4.9.5.24+
+
+    // WinForm
+    textbox?.BeginInvoke(() => textbox.Text = "事件匯流排更新");
+
+    // WPF
+    textbox?.Dispatcher?.BeginInvoke(() => textbox.Content = "事件匯流排更新");
+}
+```
+
+---
+
+## 更新日誌摘要
+
+| 版本 | 日期 | 內容 |
+|------|------|------|
+| 4.9.8.13 | 2026.02.06 | `IsConsumOnce` 更名為 `ConsumeOnce` |
+| 4.9.7.243 | 2026.01.07 | 支援取得 `RunId` |
+| 4.9.7.83 | 2025.06.10 | 支援 `GetPayload<Clay>`、修復主機停止異常 |
+| 4.9.7.61 | 2025.05.12 | 支援 `context.SetResult(object)` |
+| 4.9.5.24 | 2024.11.20 | 新增 `context.GetPayload<T>()` |
+| 4.9.1.47 | 2024.03.13 | 執行結果訂閱 `OnExecuted` |
+| 4.9.1.24 | 2024.01.19 | 支援僅消費一次 `ConsumeOnce` |
+| 4.8.0 | — | 簡單 Order 編排 |
+| 4.6.1 | — | 重試失敗回呼 |
+| 4.3.3 | — | `MessageCenter` 靜態類 |
+| 4.2.10 | — | 事件工廠動態訂閱/移除、正則匹配、局部重試 |