AppChirp 0.1.0

AppChirp

專案簡介

AppChirp 是一個用於程式內訊息傳遞的 .NET 套件，支援事件型態的即時訊息發送與接收，適合應用於模組間解耦、訊息推播等場景。

主要功能

• 註冊與管理事件源（Event Source）
• 即時訊息傳送與接收
• 支援 DI（相依性注入）
• 易於擴充與整合

安裝方式

請透過 NuGet 安裝 AppChirp 套件： dotnet add package AppChirp 或於 Visual Studio 的 NuGet 管理器搜尋 AppChirp 進行安裝。

用法說明

1. 註冊 AppChirp 與事件源

在 Program.cs 或 DI 註冊階段加入：

services.AddAppChirp(config =>
    config.RegisterEventSource<string>("demo"));

2. 取得事件發送者並發送訊息

var eventBus = serviceProvider.GetRequiredService<IEventBus>();
var publisher = eventBus.GetEventPublisher<string>("demo");
await publisher?.PublishAsync("Hello, AppChirp!");

3. 監聽事件訊息

var observable = eventBus.GetEventObserable<string>("demo");
observable?.Subscribe(msg => Console.WriteLine($"Received: {msg}"));

4. 在 ASP.NET Core 專案中使用（範例）

builder.Services.AddAppChirp(config => config.RegisterEventSource<string>("demo"));
builder.Services.AddKeyedSingleton(
    "demo",
    (sp, _) => sp.GetRequiredService<IEventBus>().GetEventPublisher<string>("demo")!);

進階示範

下面展示幾個進階應用場景，協助整合 AppChirp 到複雜的 DI 流程中：

• 在 AddKeyedSingleton 中注入事件發佈者（示範已在上方 Program.cs）：

  builder.Services.AddAppChirp(cfg => cfg.RegisterEventSource<string>("demo"));
  
  builder.Services.AddKeyedSingleton(
      "demo",
      (sp, _) => sp.GetRequiredService<IEventBus>().GetEventPublisher<string>("demo")!);
  

• 在 minimal API 或 Controller 中透過 FromKeyedServices 取得 keyed service（範例）：

  app.MapPut("/demo", ([FromKeyedServices("demo")] IEventPublisher<string> eventPublisher, CancellationToken ct) =>
      eventPublisher.PublishAsync("msg", ct));
  

如果你需要以相同 id 支援多個型別，請不要自行修改，應先討論 and 增加對應測試；預設行為是單一 id 對應單一型別。

Telemetry（OpenTelemetry）

AppChirp 會將 Activity.Current?.Context 傳遞到 EventData 中，並可與 OpenTelemetry 整合。 預設的 OpenTelemetry 設定可在 AppChirp.ServiceDefaults/Extensions.cs 中找到。

如果需要啟用 OTLP exporter，設定範例（PowerShell）如下：

$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
dotnet run --project AppChirpDemo\AppChirpDemo.csproj

測試變更時，請檢查 AppChirpDemo 與單元測試以確保 trace 能正確被傳遞與導出。

建置 / 測試 / 執行

在專案根目錄執行：

dotnet build AppChirp.slnx
dotnet test AppChirp.UnitTests

# 啟動示範專案（AppChirpDemo）
dotnet run --project AppChirpDemo\AppChirpDemo.csproj

# 或啟動 AppHost
dotnet run --project AppChirp.AppHost\AppChirp.AppHost.csproj

Packaging / Release

建立 NuGet パッケージ（本機）：

dotnet pack AppChirp\AppChirp.csproj -c Release -o ./nupkg

發布到 nuget.org 或內部 feed 之前，請確認版本與 LICENSE。

常見陷阱

• id 必須唯一：重複註冊會導致 Dictionary.Add 拋例外。
• 型別必須對應：RegisterEventSource<T>(id) 註冊後，用不同型別查詢同一 id 會回傳 null。
• 當你變更與 Activity 相關的行為時，一定要更新測試（單元測試 + AppChirpDemo）以驗證 trace 是否透過事件傳遞。

參與貢獻

建議遵循 .github/style.instructions.md 內的規範（命名、測試、PR 大小），並在提交 PR 時確保單元測試全部通過。

貢獻方式

歡迎提出 issue 或 pull request，請遵循專案的貢獻指南。

授權

本專案採用 MIT 授權。