Definiowanie spójnych stylów kodowania za pomocą polecenia EditorConfig

  • Artykuł

Aby wymusić spójne style kodowania dla wszystkich, którzy pracują w bazie kodu, możesz dodać plik EditorConfig do rozwiązania lub projektu. Ustawienia pliku EditConfig są zgodne ze specyfikacją formatu pliku utrzymywaną przez EditorConfig.org. Wiele edytorów kodu i aplikacji obsługuje pliki EditorConfig, w tym program Visual Studio. Jest to przenośny składnik, który podróżuje za pomocą kodu i może wymuszać style kodowania nawet poza programem Visual Studio.

W programie Visual Studio ustawienia pliku EditorConfig mają pierwszeństwo przed globalnymi ustawieniami edytora tekstu (dostęp do nich można uzyskać, wybierając pozycję Edytor tekstu w oknie dialogowym Opcje narzędzi>). Oznacza to, że możesz dostosować każdą bazę kodu do używania ustawień edytora tekstów, które są specyficzne dla tego projektu. W przypadku korzystania z plików EditorConfig nadal można nadal ustawiać własne preferencje edytora osobistego w edytorze tekstów programu Visual Studio. Te ustawienia edytora tekstów mają zastosowanie zawsze, gdy pracujesz w bazie kodu bez pliku EditorConfig lub gdy plik EditorConfig nie zastępuje określonego ustawienia. Przykładem takiej preferencji jest użycie kart lub spacji dla stylu wcięcia kodu.

Po dodaniu pliku EditorConfig do projektu w programie Visual Studio tylko nowe wiersze kodu są formatowane na podstawie ustawień EditorConfig. Formatowanie istniejącego kodu nie zostanie zmienione, chyba że uruchomisz jedno z następujących poleceń:

  • Oczyszczanie kodu.

    Wybierz pozycję Oczyszczanie kodu w edytorze programu Visual Studio lub naciśnij klawisze Ctrl K, Ctrl++E. To polecenie dotyczy ustawień odstępów, takich jak styl wcięcia i wybrane ustawienia stylu kodu, takie jak preferencje nawiasów.

  • Formatuj dokument.

    Wybierz pozycję Edytuj>dokument w formacie zaawansowanym>lub naciśnij klawisze Ctrl+K, Ctrl+D w profilu domyślnym. To polecenie dotyczy tylko ustawień odstępu, takich jak styl wcięcia.

Uwaga

Ten temat dotyczy programu Visual Studio dla systemu Windows. Aby uzyskać Visual Studio dla komputerów Mac, zobacz Tworzenie i edytowanie niestandardowego pliku EditorConfig w Visual Studio dla komputerów Mac.

Spójność kodu

Ustawienia pliku EditorConfig umożliwiają zachowanie spójnych stylów kodowania i konwencji w bazie kodu, niezależnie od używanego edytora lub środowiska IDE. Niektóre style kodowania, które można kontrolować, to styl wcięcia, szerokość tabulacji, znaki końca wiersza i kodowanie. Jeśli na przykład baza kodu języka C# ma konwencję, która używa pięciu znaków spacji, dokumenty używają kodowania UTF-8, a wiersze kończą się znakiem CR/LF, możesz skonfigurować plik EditorConfig tak, aby korzystał z tej konwencji.

Pliki EditorConfig są przydatne, gdy konwencje kodowania używane w projektach osobistych różnią się od konwencji używanych w projektach zespołu. Na przykład możesz wolisz, aby wcięcie dodaje znak tabulacji w kodzie. Jednak twój zespół może zamiast tego wolisz, że wcięcie dodaje cztery miejsca. Pliki EditorConfig rozwiążą ten problem, umożliwiając skonfigurowanie dla każdego scenariusza.

Ponieważ plik .editorconfig w bazie kodu zawiera ustawienia EditorConfig, są one przesyłane wraz z bazą kodu. O ile plik kodu zostanie otwarty w edytorze zgodnym z edytorem EditorConfig, ustawienia edytora tekstów zostaną aktywowane.

Uwaga

Konwencje ustawione w pliku EditorConfig nie mogą być wymuszane w potoku ciągłej integracji/ciągłego wdrażania jako błędy kompilacji lub ostrzeżenia. Wszelkie odchylenia stylu są wyświetlane tylko w edytorze programu Visual Studio i na liście błędów.

Obsługiwane ustawienia

Edytor w programie Visual Studio obsługuje podstawowy zestaw właściwości EditorConfig:

  • indent_style
  • indent_size
  • tab_width
  • end_of_line
  • Charset
  • trim_trailing_whitespace
  • insert_final_newline
  • root

Plik EditorConfig obsługuje wszystkie języki obsługiwane przez program Visual Studio, z wyjątkiem ustawień edytora EditorConfig obsługiwanych przez język XML.

Aplikacja EditorConfig obsługuje konwencje stylu kodu, w tym konwencje języka, formatowania i nazewnictwa dla języków C# i Visual Basic.

Dodawanie i usuwanie plików EditorConfig

Po dodaniu pliku EditorConfig do projektu lub bazy kodu program Visual Studio formatuje wszystkie nowe wiersze kodu pisane zgodnie z ustawieniami pliku EditorConfig. Jednak program Visual Studio nie konwertuje istniejących stylów na nowe, dopóki nie sformatujesz dokumentu ani nie uruchomisz oczyszczania kodu. Jeśli na przykład wcięcia w pliku są sformatowane za pomocą kart i dodasz plik EditorConfig, który formatuje wcięcia ze spacjami, znaki wcięcia nie są automatycznie konwertowane na spacje. Po sformatowaniu dokumentu (wybierz pozycję Edytuj>dokument w formacie zaawansowanym>lub naciśnij klawisze Ctrl K, Ctrl++D), ustawienia odstępu w pliku EditorConfig są stosowane do istniejących wierszy kodu.

Jeśli usuniesz plik EditorConfig z projektu lub bazy kodu, musisz zamknąć i ponownie otworzyć wszystkie otwarte pliki kodu dla ustawień edytora globalnego, aby wywłaszać nowe wiersze kodu.

Dodawanie pliku EditorConfig do projektu

Aby dodać plik EditorConfig do projektu lub rozwiązania, wykonaj następujące kroki:

  1. Otwórz projekt lub rozwiązanie w programie Visual Studio. Wybierz rozwiązanie lub węzeł projektu, w zależności od tego, czy ustawienia EditorConfig powinny być stosowane do wszystkich projektów w rozwiązaniu, czy tylko jednego. Możesz również wybrać folder w projekcie lub rozwiązaniu , aby dodać plik editorconfig do.

  2. Z menu wybierz pozycję Projekt>Dodaj nowy element lub naciśnij klawisze Ctrl+Shift+A.

    Zostanie otwarte okno dialogowe Dodawanie nowego elementu .

  3. W polu wyszukiwania wprowadź ciąg editorconfig.

    Dwa szablony elementów pliku editorconfig są wyświetlane w wynikach wyszukiwania.

    Zrzut ekranu przedstawiający szablony elementów pliku EditorConfig w programie Visual Studio.

  4. Wybierz szablon pliku editorconfig (pusty), aby dodać plik EditorConfig wstępnie wypełniony domyślnymi opcjami EditorConfig dla białych znaków, stylu kodu i konwencji nazewnictwa. Możesz też wybrać szablon pliku editorconfig (.NET), aby dodać plik EditorConfig wstępnie wypełniony domyślnymi odstępami na platformie .NET, stylem kodu i konwencjami nazewnictwa.

    W Eksplorator rozwiązań zostanie wyświetlony nowy plik editorconfig, który zostanie otwarty w edytorze jako nowa karta.

    Zrzut ekranu przedstawiający plik .editorconfig w Eksplorator rozwiązań i edytorze.

  5. Opcjonalnie edytuj plik, a następnie zapisz go.

Inne sposoby dodawania pliku EditorConfig

Istnieje kilka innych sposobów dodawania pliku EditorConfig do projektu:

Hierarchia plików i pierwszeństwo

Po dodaniu pliku .editorconfig do folderu w hierarchii plików jego ustawienia mają zastosowanie do wszystkich odpowiednich plików na tym poziomie i niższych. Można również zastąpić ustawienia EditorConfig dla określonego projektu, bazy kodu lub części bazy kodu, tak aby korzystały z różnych konwencji niż inne części bazy kodu. Może to być przydatne, gdy dołączasz kod z innego miejsca i nie chcesz zmieniać jego konwencji.

Postępuj zgodnie z tymi wytycznymi:

  • Aby zastąpić niektóre lub wszystkie ustawienia EditorConfig, dodaj plik editorconfig na poziomie hierarchii plików, które mają zostać zastosowane. Nowe ustawienia pliku EditorConfig mają zastosowanie do plików na tym samym poziomie i w dowolnych podkatalogach.

    Zrzut ekranu przedstawiający hierarchię EditorConfig.

  • Jeśli chcesz zastąpić niektóre, ale nie wszystkie ustawienia, określ tylko te ustawienia w pliku editorconfig . Zastępowane są tylko te właściwości, które jawnie są wyświetlane w pliku .editorconfig niższego poziomu. Inne ustawienia z plików .editorconfig wyższego poziomu nadal mają zastosowanie.

  • Jeśli chcesz mieć pewność, że żadne ustawienia z plików .editorconfig wyższego poziomu nie są stosowane do tej części bazy kodu, dodaj root=true właściwość do pliku editorconfig niższego poziomu.

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

Pliki EditorConfig są odczytywane od góry do dołu. Jeśli istnieje wiele właściwości o tej samej nazwie, ostatnio znaleziona właściwość o tej samej nazwie ma pierwszeństwo.

Edytowanie plików EditorConfig

Program Visual Studio 2022 udostępnia edytor wizualny plików EditorConfig.

Po zmodyfikowaniu pliku EditorConfig należy ponownie załadować pliki kodu, aby nowe ustawienia zaczęły obowiązywać.

Program Visual Studio pomaga edytować pliki EditorConfig, udostępniając listy uzupełniania funkcji IntelliSense. Na przykład:

Zrzut ekranu przedstawiający funkcję IntelliSense w pliku EditorConfig.

Jeśli edytujesz wiele plików EditorConfig, przydatne może być rozszerzenie EditorConfig Language Service. Niektóre funkcje tego rozszerzenia obejmują wyróżnianie składni, ulepszoną funkcję IntelliSense, walidację i formatowanie kodu.

Zrzut ekranu przedstawiający funkcję IntelliSense z rozszerzeniem EditorConfig Language Service.

Przykład

Poniższy przykład przedstawia stan wcięcia fragmentu kodu języka C# przed i po dodaniu pliku EditorConfig do projektu:

  1. W oknie dialogowym Opcje narzędzi>ustaw ustawienia edytora>tekstów C#>Tabs dla edytora tekstów programu Visual Studio, aby utworzyć cztery znaki spacji po naciśnięciu klawisza Tab.

    Zrzut ekranu przedstawiający ustawienie karty Edytor tekstu.

  2. Zgodnie z oczekiwaniami po naciśnięciu klawisza Tab w następnym wierszu wcięcie wiersza przez dodanie czterech znaków odstępu.

    Zrzut ekranu przedstawiający klawisz Tab dodający spacje w kodzie.

    Zrzut ekranu przedstawiający klawisz Tab dodający spacje w kodzie.

  3. Użyj polecenia EditorConfig, aby przełączyć ustawienie kart, aby używać kart.

    Wybierz pozycję Użyj kart w pliku EditorConfig.

    Zrzut ekranu przedstawiający konfigurowanie używania kart dla klawisza Tab.

    Dodaj nowy plik o nazwie .editorconfig do projektu z następującą zawartością. Wskaźnik [*.cs] oznacza, że ta zmiana ma zastosowanie tylko do plików kodu języka C# w projekcie.

    # Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

  4. Po naciśnięciu klawisza Tab znaki tabulacji są teraz wyświetlane zamiast spacji.

    Zrzut ekranu przedstawiający klawisz Tab z dodawaniem znaków tabulacji w kodzie.

    Zrzut ekranu przedstawiający klawisz Tab z dodawaniem znaków tabulacji w kodzie.

Rozwiązywanie problemów z ustawieniami EditorConfig

Jeśli plik EditorConfig istnieje w dowolnym miejscu w strukturze katalogów w lokalizacji lub powyżej lokalizacji projektu, program Visual Studio stosuje ustawienia edytora w tym pliku do edytora. W takim przypadku na pasku stanu może zostać wyświetlony następujący komunikat:

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

Oznacza to, że jeśli jakiekolwiek ustawienia edytora w edytorze narzędzi>Opcje>tekstu (takie jak rozmiar wcięcia i styl, rozmiar karty lub konwencje kodowania) są określone w pliku EditorConfig w lub powyżej projektu w strukturze katalogu, konwencje w pliku EditorConfig zastępują ustawienia w Edytorze tekstów.

Aby rozwiązać problemy z konfiguracją EditorConfig, wykonaj następujące kroki:

  1. Aby wyłączyć obsługę polecenia EditorConfig dla programu Visual Studio, wyczyść opcję Śledź konwencje kodowania projektu w edytorze tekstów Opcje>narzędzi.>

    Zrzut ekranu przedstawiający ustawienie Postępuj zgodnie z konwencjami kodowania projektu.

  2. Aby znaleźć wszystkie pliki EditorConfig w katalogach nadrzędnych projektu, otwórz wiersz polecenia i uruchom następujące polecenie z katalogu głównego dysku zawierającego projekt.

    dir .editorconfig /s

  3. Aby kontrolować zakres konwencji EditorConfig, ustaw root=true właściwość w pliku .editorconfig w katalogu głównym repozytorium lub w katalogu, w którym znajduje się projekt.

    Program Visual Studio szuka pliku o nazwie .editorconfig w katalogu otwartego pliku i w każdym katalogu nadrzędnym. Wyszukiwanie kończy się, gdy osiągnie ścieżkę pliku głównego lub jeśli zostanie znaleziony plik root=true editorconfig.

Powiązana zawartość