目錄 / Table of Contents

OdfKit 套件目錄與選型指南

本文件以「套件目錄 + 使用情境」格式整理 OdfKit 可交付的 核心套件、擴充套件與開發工具。

1. 可封裝套件

套件 ID 類型 目標框架 主要用途 注意事項
OdfKit 核心 SDK net10.0;netstandard2.0 ODF 文件建立、載入、儲存、驗證與 round-trip 所有擴充套件的共同基礎
OdfKit.Extensions.Html 匯出擴充 net10.0;netstandard2.0 HTML / Markdown / RTF 匯出 適合 Web 預覽或內容轉出
OdfKit.Extensions.Imaging 渲染擴充 net10.0;netstandard2.0 影像渲染、圖表 fallback 與精確文字版面量測 依賴 SkiaSharp / HarfBuzzSharp
OdfKit.Extensions.Ooxml 互通擴充 net10.0;netstandard2.0 DOCX / XLSX 轉換與互通 依賴 ClosedXML 與 Open XML SDK
OdfKit.Extensions.Pdf 匯出擴充 net10.0;netstandard2.0 PDF 匯出 依賴 PDFsharp-MigraDoc
OdfKit.Extensions.Rendering 後端渲染擴充 net10.0;netstandard2.0 以 LibreOffice 後端產生視覺輸出 需外部 LibreOffice 或相容程序
OdfKit.Extensions.Rdf 中繼資料擴充 net10.0;netstandard2.0 manifest.rdf、RDF 圖形與 SPARQL 查詢橋接 依賴 dotNetRdf
OdfKit.Extensions.Collaboration 協作擴充 net10.0;netstandard2.0 ODF Toolkit 相容 JSON operations 匯出 適合協作編輯流程整合
OdfKit.Extensions.Scripting 指令碼擴充 net10.0;netstandard2.0 ODF 1.0～1.4 script／event CRUD、LibreOffice Basic／Python 管理、巨集簽章、信任、掃描 provider、能力政策與語法診斷 管理路徑不執行巨集；Basic headless probe 為 Indeterminate；憑證信任不等於安全
OdfKit.WebFonts.Abstractions WebFont 契約 net10.0;netstandard2.0 Unicode sequence、manifest、Profile 與子集引擎契約 不相依 Web 或 ORM
OdfKit.WebFonts.Encoding.Legacy 編碼擴充 net10.0;netstandard2.0 嚴格 Big5、明確 Big5E 與 PUA mapping 不猜測來源 code page
OdfKit.WebFonts.Data.SqlServer 資料存取橋接 net10.0;netstandard2.0 有界讀取 SQL Unicode／legacy bytes 可搭配 ADO.NET、Dapper 或 ORM
OdfKit.WebFonts.OpenType 字型引擎 net10.0;netstandard2.0 純 .NET TTF／OTF／TTC／OTC／TTE／WOFF 輸入、執行期具 Brotli 時的 transformed／collection WOFF2 指定 face、compact CID-keyed／名稱式 CFF、seac closure、variable／非變動 CFF2 與 color correctness-first 路徑；輸出 TTF／OTF／WOFF，執行期具 Brotli 時輸出 WOFF2 只承諾鎖定 corpus 的有界格式矩陣；EBDT／EBLC 與 SVG 不作細粒度 pruning，AAT／Graphite、非法 seac／CFF2 及直接 collection 輸出明確拒絕
OdfKit.WebFonts.Worker 背景工作 net10.0 有界 queue、timeout 與 single-flight 不提供公開同步 generation endpoint
OdfKit.WebFonts.Sidecar 舊 Runtime 橋接 net10.0;net48 經驗證的具名 pipe 用戶端，將 WOFF2 產字委派至本機 NativeAOT Host NuGet 不含 Host；須部署同版 Release ZIP、共同資產目錄與高熵權杖
OdfKit.WebFonts.Profiles Profile 擴充 net10.0;netstandard2.0 有界、版本化 JSON mapping PUA 必須明確選擇 Profile
OdfKit.WebFonts.Hosting.AspNetCore Web 託管 net10.0 須經授權及限流的動態產生、唯讀 hash 資產、CSP/CDN URL、CORS 與 cache headers 大規模部署應置於 CDN 後方
OdfKit.WebFonts.Hosting.SystemWeb Web Forms 託管 net48 API key、allowlist、有界並行、開發用 Sidecar 自動啟動、不可變資產、靜態 fallback 及 HTML helper 處理程序內支援 TTF／WOFF；選用 NativeAOT Sidecar 可產生 WOFF2
OdfKit.WebFonts.Windows Windows EUDC 來源 net10.0;netstandard2.0 唯讀解析目前使用者 EUDC 登錄關聯與 .tte／.ttf 路徑；相容 ASP.NET Core 與 net48 consumer 不寫登錄、不從 HTTP request 接受來源
OdfKit.Extensions.Html.WebFonts HTML 整合 net10.0;netstandard2.0 ODF 文字需求收集與外部 CSS link 不掃描瀏覽器 DOM

2. 非封裝工具與工程元件

專案 類型 用途
OdfKit.Cli CLI 工具 驗證、資訊查詢、sanitize、flat XML / CSV 轉換
samples/Sample.cs 範例 單檔 Script 展示主要功能
OdfCorpusGenerator 開發工具 產生 corpus 與測試資料
OdfSchemaGenerator 開發工具 schema 衍生與 DOM wrapper 產生
OdfKit.TrimSmoke 開發工具 trimming / Native AOT API 根煙霧測試
OdfKit.Tests 測試套件 單元、整合、互通與 packaging 驗證
OdfKit.Benchmarks 基準測試 效能與資源使用量量測
OdfKit.WebFonts.Build .NET Tool／MSBuild 自動掃描受信任內容並產生 content-addressed WebFont 資產
OdfKit.WebFonts.Sidecar.Host NativeAOT 部署工具 Windows x64／ARM64 self-contained WOFF2 產字服務；支援主控台、IIS Express 自動啟動與原生 Windows Service，不要求安裝 .NET Runtime

3. 依情境選型

如果您的需求是… 建議組合
純 ODF 建檔、讀寫與驗證 OdfKit
ODF 匯出成 PDF 或 HTML OdfKit + OdfKit.Extensions.Pdf / OdfKit.Extensions.Html
產生圖片預覽或圖表 fallback OdfKit + OdfKit.Extensions.Imaging
與 Office 生態互通 OdfKit + OdfKit.Extensions.Ooxml
必須依賴 LibreOffice 視覺後端 OdfKit + OdfKit.Extensions.Rendering
要保留或查詢 RDF 中繼資料 OdfKit + OdfKit.Extensions.Rdf
協作編輯或操作序列輸出 OdfKit + OdfKit.Extensions.Collaboration
管理 ODF 指令碼或 LibreOffice 文件巨集 OdfKit + OdfKit.Extensions.Scripting
在 CI / 批次流程中做驗證或轉檔 OdfKit.Cli
將資料庫查詢（含 Entity Framework Core）或任意物件序列匯出成 ODS，或反向以 DbDataReader 邊界串流灌入 SqlBulkCopy 等 bulk copy API OdfKit（核心即可，透過 ObjectDataReader<T> 與 OdsStreamWriter.WriteDataAsync<T>，無需額外擴充套件）
在 ASP.NET Core／Web Forms 顯示多國罕用字、IVS 或機構 PUA OdfKit.WebFonts.Build + OdfKit.WebFonts.Hosting.AspNetCore／OdfKit.WebFonts.Hosting.SystemWeb；Big5／Big5E 或 SQL bytes 再加入對應 Encoding／Data 套件

4. 選型原則

  1. 若需求只涵蓋 ODF 建立、載入、儲存、驗證，先從 OdfKit 開始。
  2. 只有在需求涉及匯出、渲染、互通或協作時，再加入對應擴充套件。
  3. 若部署環境禁止外部程序，避免將 OdfKit.Extensions.Rendering 視為核心依賴。
  4. 若需要最穩定的相依面，優先依據 NuGet 相容矩陣 鎖定固定版本與目標框架。

5. 相關文件