以片段包住選取範圍
本頁包含以片段包住選取範圍的操作與預覽、錨點、縮排、選取處理、命令入口、插入路徑與驗證。 按鍵怎麼接見包夾按鍵。
操作
- 選取 T-SQL 後按
Ctrl+Alt+S，或從右鍵／工具選單選「以片段包住選取範圍」。 - 直接輸入捷徑、標題或說明搜尋，例如
be、交易；空白分隔的關鍵字必須全部相符。 - 用 ↑／↓ 或單擊選取片段，右側先看包入這段 SQL 的實際展開預覽。
- Enter、雙擊項目或「套用」才會改動查詢；Esc、「取消」或點到清單外面不套用。
- 套用後剩餘欄位以 Tab／Shift+Tab 導航；沒有欄位就直接移至樣板的最後落點。
清單不是 Completion，也不是模態對話框，搜尋不會改到 SQL。Tab 用來在搜尋框、清單、 唯讀預覽與按鈕間移動，不再直接套用；Ctrl+F 返回搜尋框。預覽可選取複製。 沒有相符項目時清空預覽並停用套用；長 SQL 只截短預覽，實際插入保留完整內容。 第一列說明實際會被包住的行數與字數。清單預設 1040×620，右下角握把可拖出更大的 預覽，關閉時把尺寸記在行程記憶體，下一次沿用；最小 640×380，開啟時再收進螢幕工作區。
預覽分兩色：選取的 SQL 用一般前景加淡底，片段新增的外框用淡色，一眼就看得出 這次會多出什麼。範圍不用字串比對找——SqlSnippetExpansion.Render 在展開時就記下 包夾內容的位置，換行正規化與補縮排都跟著同一次計算搬移（SqlSnippetIndentation.Apply 的多位置多載）。行首縮排留在外框那一色，底色才不會看起來像連縮排都選走了。 預覽是唯讀的 RichTextBox（SqlAssistChrome.CreateCodeViewer）：TextBox 只有一種 前景色，TextBlock 不能選取複製。
清單開著時 Tab、↑↓、Enter、Esc 為什麼會改到編輯器、以及為什麼留在 Popup， 見包夾按鍵。
清單維持設定檔順序，預選上一次成功套用的片段，取消或寫入失敗不記錄。 搜尋完整捷徑時優先選它，清除搜尋回到原預選。SqlSnippetSurroundHistory 以識別碼 記在行程記憶體，修改捷徑仍認得；原項目刪除、停用或不再可包夾時退回第一筆。
錨點是 $surround$，不是 $selected$
Surround With 與一般程式碼片段共用同一份樣板，不必建立第二份包夾設定。 從 工具 → SqlAssist → 程式碼片段… 複製 be 或 ifb，修改捷徑及程式碼，例如：
IF $condition$
BEGIN
$surround$
END$end$$surround$：放選取 SQL，必須剛好一個。管理員會從程式碼推導欄位。$condition$：一般可填寫欄位，可在下方設定預設值與說明。$end$：結束欄位導覽後的游標落點。- 展開模式選「依序按 Tab 跳轉」，儲存後立即出現在包夾清單。
沒有選取、直接輸入捷徑展開時，surround 就是一格普通的 Tab Stop，使用設定的 預設值；包夾時改填 SQL 並退出導航，避免下一個按鍵把剛包入的內容覆蓋掉。 其餘欄位仍可導航，例如 wl 套用後先填條件。
刻意不用 $selected$：那是 SSMS 原生引擎的保留字，不能當成一般 Literal 宣告。 這是 SqlAssist 自己的片段庫，不是 SSMS 內建「程式碼片段管理員」的 .snippet 檔； 存放、自訂與重新載入規則見片段存放。
可以包夾的內建片段
| 用途 | 捷徑 |
|---|---|
| BEGIN／END、條件與迴圈 | be、ifb、ife、ifne、wl |
| TRY／CATCH、交易、交易試跑 | tc、trn、trr |
| 程序本體、游標的逐筆處理內容 | cp、cur |
| CTE、衍生資料表 | wcte、wdt |
共 12 筆，由 SqlSnippetDefaultsTests 守住清單與錨點範圍。trr 的外框是交易， 不要求 BlockMatcher 把 BEGIN TRANSACTION 誤認成 BEGIN／END 區塊。 片段不執行 SQL，也不是 SQL 語法驗證器；例如 CTE／衍生資料表需要合法子查詢， 包入多個語句或帶結尾分號的查詢仍需自行調整。
CanSurround 同時確認欄位已宣告、錨點實際存在且只有一個。 管理員存檔與載入共用 ValidateSurroundAnchor；手改檔案的違規項目仍在管理員顯示 原因，但不進包夾清單。直接呼叫 WithSurroundText 也會拒絕，以免 SQL 遺失或複製兩份。
縮排分三段
| 這一段 | 誰負責 |
|---|---|
| 選取 SQL 自己的相對縮排 | 保留 |
| 多行內容原本的共同縮排與樣板錨點縮排 | SqlSnippetSurround.Reindent |
| 插入點的基準縮排 | SqlSnippetIndentation，預覽、原生與游標模式共用 |
共同縮排按字元比對，不猜 Tab 寬度。第一行的基準縮排留在緩衝區，後續非空行才補； 原生 FormatSpan 逐點插入保住欄位標記，游標模式在一次文字替換中完成，復原仍是一格。
選取範圍的處理
純文字規則由 Core 的 SqlSnippetSurroundSelection 計算，平台只轉成追蹤範圍：
- 跨行選取擴成整行；若多包到未選文字，清單上方明示並讓預覽呈現實際內容。
- 終點在下一行第 0 欄時，不包入下一行；原行尾保留在外框之後，支援 LF／CRLF／CR。
- 完整單行也把前導縮排留在緩衝區，不重複包入；局部單行運算式維持原選取。
- 第一行為空白行時不把插入點推到行尾。
- 框選不支援；只有空白、唯讀範圍會顯示原因而不開清單。
- 非模態清單開著時內容可能變動；套用前重新檢查追蹤範圍與原文，不覆蓋新輸入。
- 同一編輯器只開一份清單；點到其他查詢頁或工具窗關閉時不搶回焦點。
入口
| 入口 | 接線 |
|---|---|
Ctrl+Alt+S | 命令表的全域鍵繫結 |
| 查詢視窗右鍵，自成一段 | IDM_SQLWB_SQLSCRIPT_CONTEXT（選單 ID 80） |
| 工具 → SqlAssist | 同一命令的 CommandPlacement |
自訂綁在 Edit.SurroundWith 的鍵 | SqlShellCommandFilter 攔 VSStd2K/SURROUNDWITH |
Ctrl+K, Ctrl+S 不綁：SSMS 解析成內建行為搶不到，預設鍵才取 Ctrl+Alt+S。 除錯中或 SQL 物件文件改走 IDM_VS_CTXT_CODEWIN，那裡不會出現這段右鍵選單。
沒有 SQL 編輯器、沒有一般選取或沒有候選時，選單停用但不隱藏；濾鏡不認領，留給 SSMS 原本行為。選單失敗用狀態列說明，濾鏡失敗往下轉。見殼層命令。
插入走的是同一條路
預覽與插入都由 WithSurroundText 取得衍生片段，再走片段導航 的原生 session 與同一份降級。沒有剩餘欄位（be、trn、trr）直接一次替換； 原生引擎已改動文字卻回報失敗時不再降級重插，並提示檢查內容及必要時復原。
驗證
自動回歸與 WPF 面板測試的逐項斷言在測試專案裡，不在這裡重列。 仍須在 SSMS 實機驗收右鍵、搜尋輸入、Tab／↑↓／Enter／Esc／Delete 不再改到編輯器、 握把拖拉與下次沿用、原生 Tab 欄位、一次復原、跨查詢焦點及多螢幕定位；WPF 渲染不代表 殼層命令與 COM 引擎已驗證。按鍵這一項只有紀錄檔說了算：清單開著時按下去若仍出現 「未處理的殼層命令」，那個命令就是還沒接上。