建置、測試與工具

本頁包含環境需求、建置與測試、push 前的自動測試、SSMS 升版後的編譯診斷，以及工具腳本入口。 文字檔格式的檢查見文字與編碼。

環境需求

• Windows x64
• PowerShell 7+
• SQL Server Management Studio 22.9.x
• Visual Studio 18／2026 或相容的 MSBuild
• .NET SDK 10.0.400

建置與測試

Set-Location 'D:\GitProject\SqlAssist.Ssms22'
.\tools\Run-CoreTests.ps1
.\tools\Build-Extension.ps1

預期輸出：

src\SqlAssist.Ssms22\bin\x64\Release\net48\SqlAssist.Ssms22.vsix

測試執行器由 global.json 的 test.runner 指定為 Microsoft.Testing.Platform （.NET 10 SDK 不再支援 VSTest 轉接層）。

方案也包含 net48 的 SqlAssist.Ssms22.Tests，直接編譯產品的純 WPF 元件並在 STA 執行主題回歸測試；不需要啟動 SSMS。實機驗收範圍見主題連動。

push 前自動跑測試

版本庫附了一個 pre-push hook。git 不會自動套用版控裡的 hook，clone 之後要手動 指一次：

git config core.hooksPath .githooks

之後每次 git push 都會依序跑 Check-TextFiles.ps1、Check-Docs.ps1 與 Run-CoreTests.ps1，任何一個失敗就擋下來。推送的 commit 只改到 docs/、*.md、 LICENSE、NOTICE、.github/ 或 .claude/ 時略過單元測試。 真的要略過時用 git push --no-verify。

UTF-8／LF 規則與 PowerShell 子程序編碼見文字檔與編碼。

SSMS 更新後突然編譯失敗

參考組件是 SSMS 安裝目錄裡的那一份（SsmsInstallDir），SSMS 自動更新之後那些 組件也跟著換。22.10 就是這樣：編輯器介面新增了可為 NULL 的註解，git 沒有任何 變更的程式碼也開始出現 CS8766／CS8604。判斷方式是先把工作區存起來，用未修改的 master 建置一次；還是失敗就與本次修改無關。

處理原則照序：先看能不能照新契約寫（例如工廠改成一定回得出東西、取不到分類型別 就不上色並記一行），做不到才用單一成員的 #pragma warning disable 並在文件註解 寫清楚為什麼——目前只有 SqlPreviewPopupAgent.PositionAndDisplay 是這一類：null 與 Geometry.Empty 在空間管理員眼裡是兩件事，跟著改型別是行為變更而不是修警告。 不要用 ! 把可為 NULL 的值硬塞進不可為 NULL 的位置，那只是把 NRE 推到執行期。

Ssms22 另外掛了 Microsoft.VisualStudio.Threading.Analyzers，只開真的有訊號的那幾條； 關掉的三條與每一條的理由寫在 .editorconfig 的那一節，動它之前先讀那裡。

也不要用 dotnet build 建置本方案：它不會帶 SsmsInstallDir，還會覆寫 obj 裡的 解析結果，症狀與 SSMS 更新一模一樣。一律走 tools\Build-Extension.ps1。

工具腳本的共用設定

SSMS 的安裝路徑、擴充的 Identity Id 與「已安裝的 SqlAssist 在哪裡」全部在 tools\SqlAssist.Tools.psm1，每支腳本都從那裡取。SSMS 裝在別的位置時不必改腳本， 傳 -SsmsInstallDir 就好：

.\tools\Build-Extension.ps1 -SsmsInstallDir 'D:\SSMS 22\Release'

Install-Extension.ps1、Uninstall-Extension.ps1、Deploy-DebugExtension.ps1、 Generate-Keywords.ps1 與 Audit-Completions.ps1 收同一個參數。專案檔的 SsmsInstallDir 屬性另有一份預設值， 因為 MSBuild 讀不到 PowerShell 模組；Build-Extension.ps1 一律把解析後的路徑 以 /p:SsmsInstallDir= 傳進去，不靠專案檔那份。

工具腳本

腳本	做什麼
Run-CoreTests.ps1	以方案為目標跑單元測試（執行器由 global.json 指定）
Build-Extension.ps1	建置並產出 VSIX
Install-Extension.ps1	以官方 VSIXInstaller 安裝
Uninstall-Extension.ps1	解除安裝（保留使用者設定與紀錄）
Deploy-DebugExtension.ps1	部署 Debug 組件並清除 MEF 快取，供 F5 偵錯
Show-Diagnostics.ps1	顯示安裝狀態與最近的診斷紀錄
Audit-Completions.ps1	建議清單的召回稽核：建置執行器、跑語料、寫報告到 artifacts/completion-audit/
Set-CompletionAuditConnection.ps1	設定稽核直連的伺服器（版控外，密碼以 DPAPI 加密）
Generate-Keywords.ps1	以 ScriptDom 重新產生 SqlKeywordCatalog.Generated.cs；剖析快取在 artifacts/cache/，途中定期與失敗時都會存，-NoCache 重建
Publish-Release.ps1	建置、驗證並建立 GitHub 草稿 Release
Test-VsixPackage.ps1	檢查 VSIX 套件結構
Test-DebugDeployment.ps1	以隔離 fixture 驗證 Debug 部署完整性與 Install 門檻
Test-CommandTable.ps1	交叉驗證 VSCT、CommandIds 與註冊檔的命令識別碼
Check-TextFiles.ps1	將 CR／CRLF 自動轉成 LF，檢查文字檔皆為 UTF-8（除 .sln 外無 BOM）且有檔尾換行，並確認每支腳本先初始化 UTF-8 輸出
Check-Docs.ps1	檢查文件的大小預算與所有 Markdown 連結和錨點
Check-DocLinks.ps1	核對內建說明的線上文件位址是否還回得了 200（要連外，單獨執行）
SqlAssist.Tools.psm1	共用 UTF-8 輸出、SSMS 路徑與擴充 Id 探索