共用方式為

使用 EditorConfig 定義一致的編碼樣式

  • 發行項

若要針對在程式代碼基底中運作的每個人強制執行一致的編碼樣式，您可以將 .editorConfig 檔案新增至您的方案或專案。 EditorConfig 檔案設定會遵循 EditorConfig.org所維護的檔格式規格。許多程式代碼編輯器和應用程式都支援 EditorConfig 檔案，包括 Visual Studio。 因為這些設定位於檔案中，所以它們會隨附您的程序代碼，而且即使在Visual Studio之外也能使用。

在 Visual Studio 中，EditorConfig 檔案設定優先於 Tools>Options>Text Editor>C/C++>Code Style下可用的各種全域文本編輯器設定。 您可以使用 EditorConfig 檔案來量身打造每個程式代碼基底，以使用該專案特有的文字編輯器設定。

您可以手動填入 EditorConfig 檔案，或根據您在 Visual Studio 中選擇的程式代碼樣式設定自動產生它。 若要根據您目前的 Visual Studio 設定建立新的 .editorconfig 檔案，請從 Visual Studio 主選單選擇 [工具] [工具]>[選項]>[文本編輯器]>C/C++>[程式代碼樣式]。 然後選擇 從設定產生 .editorconfig 檔案。 選擇專案所在的資料夾，然後選擇 [選取資料夾]，以儲存 .editorconfig 檔案。

當您使用 EditorConfig 檔案時，您仍然可以繼續在 Visual Studio 文字編輯器中設定自己的個人編輯器喜好設定。 當您在沒有EditorConfig檔案的程式代碼基底中工作時，或當EditorConfig檔案未覆寫特定設定時，就會套用這些文本編輯器設定。 這類喜好設定的範例是選擇使用 Tab 鍵或空格作為程式碼縮排的樣式。

當您在 Visual Studio 中將 EditorConfig 檔案新增至專案時，只會根據 EditorConfig 設定來格式化新的程式代碼行。 除非您執行下列其中一個命令，否則不會變更現有程式碼的格式設定：

  • 程式碼整理。

    在 Visual Studio 編輯器中選取 程式代碼清理，或按 Ctrl+K， Ctrl+E。 此命令適用於空格符設定，例如縮排樣式，以及選取的程式代碼樣式設定，例如括號喜好設定。

  • 格式化文件。

    選取 [編輯]>[進階>格式化文件] 或在預設配置文件中按 Ctrl+K，Ctrl+D。 此命令僅適用於空格符設定，例如縮排樣式。

程序代碼一致性

EditorConfig 檔案設定可讓您在程式代碼基底中維護一致的編碼樣式和慣例，不論您使用的編輯器或 IDE 為何。 您可以控制的一些編碼樣式是縮排樣式、製表元寬度、行尾字元和編碼。 例如，如果您的 C# 程式代碼基底有縮排使用五個空格字元的慣例，檔會使用 UTF-8 編碼，而行結尾為 CR/LF，您可以將 EditorConfig 檔案設定為使用此慣例。

當您在個人專案上使用的程式代碼慣例與小組專案所使用的慣例不同時，EditorConfig 檔案很有用。 例如，您可能偏好讓縮排在代碼中新增製表符。 不過，您的小組可能會偏好縮排新增四個空間。 EditorConfig 檔案可讓您為每個案例設定，以解決此問題。

因為程式代碼基底中的 .editorconfig 檔案包含 EditorConfig 設定，所以它們會與該程式代碼基底一起移動。 只要在符合 EditorConfig 規範的編輯器中開啟程式代碼檔案，就會啟動文字編輯器設定。

注意

您在 EditorConfig 檔案中設定的慣例無法在 CI/CD 流程中被視為建置錯誤或警告來強制執行。 任何樣式偏差只會出現在 Visual Studio 編輯器及錯誤清單中。

支援的設定

Visual Studio 中的編輯器支援 EditorConfig 屬性的核心設置：

  • 縮排風格（indent_style）
  • 縮排大小
  • Tab寬度
  • 行尾
  • 字符集
  • 刪除尾端空白
  • insert_final_newline
  • 根

EditorConfig 支援所有 Visual Studio 支援的語言，但 XML 支援 EditorConfig 編輯器設定除外。

EditorConfig 支援 程式代碼樣式 慣例，包括 語言、格式設定，以及 C# 和 Visual Basic 命名 慣例。

新增和移除 EditorConfig 檔案

當您將 EditorConfig 檔案新增至專案或程式代碼基底時，Visual Studio 會根據 EditorConfig 檔案設定來格式化您撰寫的任何新程式碼行。 不過，在您格式化檔或執行 程式代碼清除之前，Visual Studio 不會將現有的樣式轉換成新的樣式。 例如，如果檔案中的縮排是使用索引標籤格式化，而且您新增了使用空格格式化縮排的EditorConfig檔案，則縮排字元不會自動轉換成空格。 當您格式化檔時（選取 [編輯]>[進階]>[格式化檔]，或 按 Ctrl+K、Ctrl+D），EditorConfig 檔案中的空格符設定會套用至現有的程式代碼行。

如果您從專案或代碼庫移除 EditorConfig 檔案，就必須關閉並重新開啟所有已開啟的程式代碼檔案，才能讓全域編輯器設定影響新的程式碼行。

將 EditorConfig 檔案新增至專案

若要將EditorConfig檔案新增至專案或方案，請遵循下列步驟：

  1. 在 Visual Studio 中開啟專案或方案。 視您的EditorConfig設定是否應該套用至方案中的所有專案，或只套用一個專案而定，選取方案或項目節點。 您也可以選擇項目或專案中的資料夾，將 .editorconfig 檔案新增至 。

  2. 從功能表中，選擇 [專案]>[新增項目]，或按 Ctrl+Shift+A。

    新增專案 對話框隨即開啟。

  3. 在搜尋方塊中，輸入 editorconfig。

    搜尋結果中會顯示兩個 編輯器配置檔 項目範本。

    顯示 Visual Studio 中 EditorConfig 檔案專案範本的螢幕快照。

  4. 選取 editorconfig File （空白） 範本，以針對空格符、程式代碼樣式和命名慣例預先填入預設 EditorConfig 選項來新增 EditorConfig 檔案。 或者，選取 editorconfig File （.NET） 範本，以預先填入預設 .NET 空格符、程式代碼樣式和命名慣例的 EditorConfig 檔案，。

    新的 .editorconfig 檔案會出現在 [方案總管] 中，並以新的索引標籤在編輯器中開啟。

    顯示 [方案總管] 和編輯器中 .editorconfig 檔案的螢幕快照。

  5. 可以編輯檔案，然後儲存它。

新增 EditorConfig 檔案的其他方式

有幾種其他方式可將EditorConfig檔案新增至您的專案：

檔案階層和優先順序

當您將 .editorconfig 檔案新增至檔案階層中的資料夾時，其設定會套用至該層級和較低層級的所有適用檔案。 您也可以覆寫特定專案、程式代碼基底或程式代碼基底部分的EditorConfig設定，使其使用與程式代碼基底其他部分不同的慣例。 當您將程式代碼從別處併入，且不想變更其慣例時，這樣做會很有用。

請遵循下列指導方針：

  • 若要覆寫部分或所有EditorConfig設定，請在您想要套用這些覆寫設定的檔案階層層級新增 .editorconfig 檔案。 新的EditorConfig檔案設定會套用至相同層級的檔案，以及任何子目錄中的檔案。

    顯示 EditorConfig 階層的螢幕快照。

  • 如果您想要覆寫某些設定，但並非所有設定，只需在 .editorconfig 檔案中指定這些設定。 只有在較低層級 .editorconfig 檔案中明確列出的屬性才會被覆寫。 任何較高層級 .editorconfig 檔案的其他設定會繼續套用。

  • 如果您想要確保沒有任何較高層級 .editorconfig 檔案的設定套用至程式代碼基底的這個部分，請將 root=true 屬性新增至較低層級的 .editorconfig 檔案。

    # top-most EditorConfig file for this level
root = true

EditorConfig 檔案會從上到下讀取。 如果有多個屬性具有相同名稱，則最晚找到的具有相同名稱的屬性會優先。

編輯 EditorConfig 檔案

Visual Studio 2022 提供 EditorConfig 檔案的可視化編輯器。

編輯 EditorConfig 檔案之後，您必須重載程式代碼檔案，新的設定才會生效。

Visual Studio 提供 IntelliSense 完成列表，協助您編輯 EditorConfig 檔案。 例如：

顯示 EditorConfig 檔案中 IntelliSense 的螢幕快照。

如果您編輯許多 EditorConfig 檔案，您可能會發現 EditorConfig 語言服務擴充功能 有幫助。 此延伸模組的一些功能包括語法醒目提示、改善的 IntelliSense、驗證和程式代碼格式設定。

顯示 IntelliSense 與 EditorConfig Language Service 延伸模組的螢幕快照。

例

下列範例顯示 C# 代碼段在將 EditorConfig 檔案新增至專案之前和之後的縮排狀態：

  1. 在 [工具>選項] 對話框中，將 [文字編輯器]>[C#]>索引標籤 設定，讓 Visual Studio 文字編輯器在按下 [Tab] 鍵時產生四個空格符。

    顯示 [文字編輯器] 索引標籤設定的螢幕快照。

  2. 如預期般，當您在下一行按下 Tab 鍵 鍵時，它會新增四個空格符來縮排該行。

    顯示 Tab 鍵在程式代碼中新增空格的螢幕快照。

    顯示 Tab 鍵在程式代碼中新增空格的螢幕快照。

  3. 使用 EditorConfig 切換索引標籤設定以使用索引標籤。

    選取 [EditorConfig 檔案中的 [使用索引標籤]。

    顯示設定 Tab 鍵索引標籤使用方式的螢幕快照。

    使用下列內容，將名為 .editorconfig 的新檔案新增至專案。 [*.cs] 指標表示這項變更僅適用於專案中的 C# 程式代碼檔案。

    # Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

  4. 當您按下 Tab 鍵 鍵時，索引標籤字元現在會出現，而不是空格。

    螢幕快照，顯示在程式碼中按下 Tab 鍵會增加製表符。

    螢幕快照顯示 Tab 鍵在程式碼中新增製表符。

EditorConfig 設定疑難排解

如果 EditorConfig 檔案存在於您專案位置或上方目錄結構中的任何位置，Visual Studio 會將該檔案中的編輯器設定套用至編輯器。 在此情況下，您可能會在狀態列中看到下列訊息：

User preferences for this file type are overridden by this project's coding conventions.

這表示，如果 [工具]>[選項]>[文本編輯器] 中的任何編輯器設定（例如縮排大小和樣式、索引卷標大小或編碼慣例）是在目錄結構中專案或上方的 EditorConfig 檔案中指定，則 EditorConfig 檔案中的慣例會覆寫 文本編輯器中的設定。

若要針對EditorConfig問題進行疑難解答，請遵循下列步驟：

  1. 若要關閉 Visual Studio 的 EditorConfig 支援，請清除 [工具]>[選項]>[文字編輯器]中的 [遵循項目編碼慣例] 選項。

    顯示「遵循專案編碼慣例」設定的螢幕截圖。

  2. 若要在專案的父目錄中尋找任何 EditorConfig 檔案，請開啟命令提示字元，並從包含您專案的磁碟根目錄執行下列命令。

    dir .editorconfig /s

  3. 若要控制 EditorConfig 慣例的範圍，請在存放庫根目錄的 .editorconfig 檔案或您專案所在的目錄中，設定 root=true 屬性。

    Visual Studio 會在開啟檔案的目錄中和每個父目錄中尋找名為 .editorconfig 的檔案。 搜尋會在到達根目錄路徑時結束，或找到包含 root=true 的 .editorconfig 檔案時結束。

相關內容