Source generator 做了什麼、為什麼要用它,背景說明見 編譯期發現。
安裝
<PackageReference Include="Davish.Sendr" Version="3.5.0" />
<PackageReference Include="Davish.Sendr.Generators" Version="2.1.0" PrivateAssets="all" />PrivateAssets="all" 讓這個 generator 本身(一個 analyzer 類型的套件)不會流到下游、
參照這個專案的其他專案。
開啟它
builder.Services.AddSendr(o => o.UseGenerators());
builder.Services.AddSendrNotification(o => o.UseGenerators());單純呼叫 AddSendr()/AddSendrNotification()(不帶 UseGenerators())會維持預設的
反射式 sender/publisher。一旦用了 UseGenerators(),同一個 sender/publisher 的手動
AddXHandler/AddNotificationHandler 呼叫就不會擴充它的分派表。每個 sender、每個
publisher 都只能選一種註冊方式。
發現另一個專案裡的 handler
預設只會發現呼叫 UseGenerators() 那個專案自己的 handler。要納入被參照的專案或套件:
// assembly 裡任何一個型別都可以當這個 marker,它不需要實作任何特定介面。
public sealed class ApplicationAssemblyMarker;
builder.Services.AddSendr(o => o.UseGenerators(g => g.IncludeAssemblyOf<ApplicationAssemblyMarker>()));要納入不只一個 assembly,就串接起來:
o.UseGenerators(g => g
.IncludeAssemblyOf<ApplicationAssemblyMarker>()
.IncludeAssemblyOf<InfrastructureAssemblyMarker>());這對應到 repo 自己 sample 裡一個實際可運作的範例:samples/ConsoleApp 參照了
samples/ConsoleLib,並在 AddSendr 與 AddSendrNotification 兩邊都透過
IncludeAssemblyOf<IAssemblyMarker>() 把它納入,而 ConsoleLib 本身完全沒有呼叫
UseGenerators()。
IncludeAssemblyOf<TMarker>() 呼叫要直接寫在 UseGenerators(g => ...) 這個
lambda 裡,不論是串接寫法還是區塊內的個別陳述式都行,因為 source generator 是直接從
原始碼讀出這個宣告的,不是在執行期掃描。如果放在 delegate 變數、method group、迴圈、
條件式,或包一層 helper/extension method 裡,會在編譯期被拒絕(SENDR005)。
用這種方式發現的 handler,必須是呼叫端專案可以存取到的:public(包含每一層外層型別,
如果是巢狀 handler 的話),或是 internal 但搭配該函式庫宣告的
[assembly: InternalsVisibleTo("...")],否則會是編譯錯誤(SENDR007)。
Sender/stream-sender 的 assembly 集合跟 publisher 的 assembly 集合是彼此獨立的;同一個
函式庫如果同時有兩種 handler,也可以同時被納入兩邊。同一次編譯裡,多次設定同一個
sender 或 publisher 的 UseGenerators() 呼叫,必須宣告完全相同的 assembly 集合,不然
就是編譯錯誤(SENDR006)。
Source generator 不會發現的情況
- Struct/record struct 的 handler — 編譯錯誤
SENDR004。請改用class/record class。 - Open generic 的 handler 類別 — 資訊等級的診斷
SENDR003;請針對這個型別改用 手動註冊一個封閉建構的 handler 型別,不要對它用UseGenerators()。
完整的診斷清單見例外與診斷。