在 SSMS 中格式化 Transact-SQL

適用於：SQL Server、Azure SQL Database、Azure SQL 受控執行個體、Azure Synapse Analytics、Analytics Platform System (PDW)、Microsoft Fabric 中的 SQL 分析端點、倉儲 (Warehouse)、SQL 資料庫

一致的格式能讓 Transact-SQL（T-SQL）更容易閱讀、審查和維護，尤其當多人共同貢獻同一程式碼庫時。 SQL Server Management Studio（SSMS）內建 SQL 格式化器（預覽版），您可以隨時執行，並在儲存時設定自動格式化，並透過 SSMS 設定或.editorconfig檔案自訂。

SSMS 的 SQL 格式化功能建立在 ScriptDOM 之上，ScriptDOM 是一個開源的 .NET 函式庫，能解析 T-SQL，並根據抽象語法樹產生腳本。

先決條件

依需求格式化

你可以在任何查詢編輯器視窗中格式化 T-SQL。 格式化器可套用於整份文件，或僅適用於特定部分文字。

若要按需格式化 SQL，請使用以下方法之一：

  • 右鍵選單：在 T-SQL 編輯器視窗中右鍵點擊，選擇格式化 SQL（預覽）。
  • 編輯選單：選擇編輯>進階>格式 SQL（預覽）。
  • 鍵盤快捷鍵：按 Ctrl+K、Ctrl+Q。

當你選擇文字時，格式化器只會套用在選取的內容上。 當你沒有選擇文字時，格式化器會套用到整個文件。

存檔時的格式

當你開啟「 儲存格式化 」選項時，格式化器會自動套用你設定的格式選項，每次儲存 .sql 檔案時都會自動套用。 儲存時格式化適用於已命名或已儲存的查詢編輯器視窗，以及 SQL 資料庫專案中的檔案。 存檔格式化能讓你的 SQL 檔案在 pull request 和程式碼審查中保持一致。

若要為所有檔案啟用儲存時格式化：

  1. 選擇 工具>選項。
  2. 請前往 SQL Formatter （Preview）>Formatting。
  3. 將 Format on Save 設定為 true。
  4. 請選擇 [確定]。

你也可以在 .editorconfig 檔案中設定 format_on_save = true，為你的專案或資料夾中的所有 .sql 檔案啟用儲存時格式化。 更多資訊請參閱 .editorconfig 檔案。

設定格式選項

格式化器支援一系列可控制 SQL 樣式的選項，例如關鍵字大小寫、縮排大小、陳述式後的分號，以及像是 FROM、WHERE 和 JOIN 這類子句的換行。 你可以用兩種方式設定這些選項：透過 SSMS 設定或透過檔案 .editorconfig 。

當同一選項同時存在 SSMS 設定與值 .editorconfig 時， .editorconfig 值會優先。 這種優先順序可讓你在 SSMS 中設定你偏好的預設值，並使用 .editorconfig 檔案，針對每個專案或每個資料夾加以覆寫。

SSMS 設定

要在 SSMS 中設定格式選項：

  1. 選擇 工具>選項。
  2. 請前往 SQL Formatter（預覽版）。
  3. 調整子類別中的設定：一般、對齊、路徑、格式、縮排、多行、新行和間距。
  4. 請選擇 [確定]。

.editorconfig 檔案

你可以在 .editorconfig 專案或資料夾中的檔案中定義格式選項。 SSMS 會讀取這些值，並將其作為覆蓋套用到 SSMS 設定之上。

所有 SQL 格式化工具鍵都位於 .editorconfig 中的 [*.sql] 之下。

一般

Key 類型 價值 預設
sql_version 列舉 Sql80 Sql90 Sql100 Sql110 Sql120 Sql130 Sql140 Sql150 Sql160 Sql170 Sql170
sql_engine_type 列舉 All Standalone SqlAzure All

對準

Key 類型 預設 說明
align_clause_bodies bool true 對齊 FROM、WHERE、GROUP BY 及其他類似子句的主體部分。
align_column_definition_fields bool true 對齊欄位定義中的欄位，例如名稱、類型和限制條件。
align_set_clause_item bool true 在 UPDATE 陳述式中對齊 SET 子句項目。

Paths

Key 類型 預設
allow_external_language_paths bool true
allow_external_library_paths bool true

Formatting

Key 類型 價值 預設 說明
format_on_save bool false 儲存時自動格式化（僅 SSMS，非 ScriptDOM 格式）。
as_keyword_on_own_line bool true 將 AS 另起一行。
include_semicolons bool false 在陳述後加上分號。
keyword_casing 列舉 Uppercase Lowercase PascalCase Uppercase 關鍵字是外殼風格。
preserve_comments bool true 格式化時請保留評論。

縮排

Key 類型 預設 說明
indent_set_clause bool false 在 UPDATE 陳述式中縮排 SET 子句。
indentation_size 整數（1–8） 4 每個縮排層級的空格數。
indent_view_body bool false 將 VIEW 本文縮排。

多行

Key 類型 預設 說明
multiline_insert_sources_list bool true INSERT 將資料來源設為多行。
multiline_insert_targets_list bool true 將 INSERT 欄設為多行。
multiline_select_elements_list bool true SELECT 欄位為多線。
multiline_set_clause_items bool true SET 項目以多行形式。
multiline_view_columns_list bool true VIEW 欄位為多線。
multiline_where_predicates_list bool true WHERE 判定為多行。

新線

Key 類型 預設
new_line_before_close_parenthesis_in_multiline_list bool true
new_line_before_from_clause bool true
new_line_before_group_by_clause bool true
new_line_before_having_clause bool true
new_line_before_join_clause bool true
new_line_before_offset_clause bool true
new_line_before_open_parenthesis_in_multiline_list bool false
new_line_before_order_by_clause bool true
new_line_before_output_clause bool true
new_line_before_where_clause bool true
new_line_before_window_clause bool true
newline_formatted_check_constraint bool false
newline_formatted_index_definition bool false
num_newlines_after_statement 整數（0–5） 1

間距

Key 類型 預設 說明
space_between_data_type_and_parameters bool true 例如資料型別與parens之間的空格 VARCHAR (255)
space_between_parameters_in_data_type bool true 資料型態中參數之間的空間

範例 .editorconfig

以下範例展示了一個 .editorconfig 設定幾個常見自訂選項的檔案。 檔案中未指定的屬性會回退到 SSMS 設定。

[*.sql]
keyword_casing                                      = lowercase
include_semicolons                                  = true
indentation_size                                    = 2
multiline_select_elements_list                      = true
new_line_before_from_clause                         = true

分享意見反應

SSMS 的 SQL 格式化功能建立在開源的 .NET 函式庫 ScriptDOM 之上，用於 T-SQL 解析。 使用 ScriptDOM 倉庫中的 GitHub 議題系統來討論想法與挑戰。 歡迎提交拉取請求。

請透過 SSMS 中的 Help>Send Feedback 或 開發人員社群 回饋頻道提交 SSMS 回饋。

相關內容

  • Last updated on