Metalama 技術指南
範圍：所有使用 GST 框架（
GST.Core.Aspects）的開發人員對象：新進開發人員、合作夥伴，以及所有學習 Metalama AOP 的人
先備知識：基本的 C# 與 .NET 知識
預估閱讀時間：2–3 小時（完整指南）
版本：1.0
最後更新：2026-03-31
Metalama 版本：2025.1.17 (GST) / 2026.1 (最新)
本指南涵蓋內容
本指南是 Metalama 的完整入門介紹，Metalama 是一個用於 C# 的編譯時期 Aspect-Oriented Programming (AOP) 框架。本指南是為剛接觸 AOP 或 Metalama 的開發人員所設計，希望從基礎概念到 GST 框架中的實際應用，深入理解這項技術。
指南結構
| 章節 | 主題 | 說明 |
|---|---|---|
| 1 | 總覽（本頁） | 本指南的內容與使用方式 |
| 2 | AOP 基礎 | 什麼是 AOP、為什麼重要、關鍵術語 |
| 3 | 快速開始 | 安裝、設定，以及你的第一個 Aspect |
| 4 | 核心概念 | Aspect 的運作方式、生命週期、排序與組合 |
| 5 | T# 範本語言 | 驅動 Metalama 的編譯時期範本系統 |
| 6 | Aspect 基底類別 | 所有基底類別的說明與範例 |
| 7 | Fabrics | 不使用 Attribute 的批次 Aspect 套用方式 |
| 8 | 模式庫 | 內建模式：Contracts、Caching、Observability |
| 9 | GST 實際範例 | GST 框架如何在正式環境中使用 Metalama |
| 10 | 進階主題 | Advising、成員導入、Eligibility、診斷 |
| 11 | 測試與除錯 | 如何測試與除錯 Aspect 及轉換後的程式碼 |
| 12 | 優缺點分析 | 誠實評估何時該用（及不該用）Metalama |
| 13 | 最佳實踐 | 設計原則、常見陷阱與指導方針 |
如何閱讀本指南
完全初學者
從第 2 章（AOP 基礎）開始，了解 AOP 解決的問題。然後依序閱讀第 3 章（快速開始）和第 4 章（核心概念），再探索其餘內容。
有經驗的 C# 開發人員，但初次接觸 AOP
快速瀏覽第 2 章的術語，然後直接進入第 3 章和第 5 章（T# 範本）——範本語言是 Metalama 最獨特的部分，也是掌握它的關鍵。
已熟悉 PostSharp 或其他 AOP 框架的開發人員
直接跳到第 5 章（T# 範本）、第 6 章（基底類別）和第 12 章（優缺點），與其他框架進行比較。
GST 框架使用者
**第 9 章（GST 實際範例）**是必讀內容。它說明了架構、慣例，以及 GST.Core.Aspects 中全部 32 個 Aspect。搭配 GST Aspect 使用指南 閱讀，了解專案層級的規則。
相關文件
| 文件 | 說明 |
|---|---|
| GST Aspect 使用指南 | 在應用程式專案中使用 GST Aspect 的規則與慣例 |
| GST 框架指南 | GST 框架整體架構與概念 |
| Metalama 官方文件 | Metalama 官方文件 |
| Metalama GitHub | 原始碼儲存庫 |
版本歷程
| 版本 | 日期 | 變更內容 |
|---|---|---|
| 1.0 | 2026-03-31 | 初次發布——涵蓋 Metalama 2025.1/2026.1 的完整指南 |