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

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 EditorConfig 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. Ponieważ ustawienia znajdują się w pliku, towarzyszą one kodowi i mogą być używane nawet poza programem Visual Studio.

W programie Visual Studio ustawienia pliku EditorConfig mają pierwszeństwo przed różnymi globalnymi ustawieniami edytora tekstów dostępnymi w Tools>Options>Text Editor>C/C++>Code Style. Możesz użyć pliku EditorConfig, aby dostosować każdą bazę kodu do używania ustawień edytora tekstów specyficznych dla tego projektu.

Możesz ręcznie wypełnić plik EditorConfig lub automatycznie wygenerować go na podstawie ustawień stylu kodu wybranych w programie Visual Studio. Aby utworzyć nowy plik .editorconfig na podstawie bieżących ustawień programu Visual Studio, w menu głównym programu Visual Studio wybierz pozycję narzędzia Tools>Options>Text Editor>C/C++>Code Style. Następnie wybierz pozycję Wygeneruj plik editorconfig z ustawień. Wybierz folder, w którym znajduje się projekt, a następnie wybierz pozycję Wybierz folder, aby zapisać plik .editorconfig.

Jeśli używasz pliku EditorConfig, nadal możesz ustawić 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 to, czy użyć 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 czyszczenie kodu w edytorze programu Visual Studio lub naciśnij 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 Edytuj>Zaawansowane>Formatuj Dokumentlub naciśnij Ctrl+K, Ctrl+D w profilu domyślnym. To polecenie dotyczy tylko ustawień odstępu, takich jak styl wcięcia.

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 woleć, aby wcięcie dodawało znak tabulacji w twoim kodzie. Jednak twój zespół może woleć, żeby wcięcie dodawało cztery spacje. 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.

Obsługiwane ustawienia

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

• indent_style
• rozmiar wcięcia
• szerokość tabulacji
• koniec_linii
• zestaw znaków
• usuń_białe_znaki_końcowe
• insert_final_newline
• korzeń

Plik EditorConfig obsługuje wszystkie języki wspierane przez program Visual Studio, z wyjątkiem obsługi ustawień edytora EditorConfig dla języka XML.

Aplikacja EditorConfig obsługuje konwencje stylu kodu, w tym konwencje języka, formatowanie oraz konwencje 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 lub nie uruchomisz Oczyszczanie 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. Podczas formatowania dokumentu (wybierz Edytuj>Zaawansowane>Formatuj dokument lub naciśnij Ctrl+K, Ctrl+D), ustawienia białych znaków 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 aktualnie otwarte pliki kodu, aby ustawienia edytora globalnego zaczęły być stosowane do nowych wierszy 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 swoim projekcie lub rozwiązaniu, aby dodać do niego plik .editorconfig.

2. Z menu wybierz pozycję Project>Dodaj nowy elementlub naciśnij Ctrl+Shift+A.

   Otwiera się okno dialogowe Dodawanie nowego elementu.

3. W polu wyszukiwania wprowadź editorconfig.

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

   

4. Wybierz szablon editorconfig File (pusty), aby dodać plik EditorConfig, który jest wstępnie wypełniony domyślnymi opcjami EditorConfig w zakresie 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ślnym odstępem .NET, stylem kodu i konwencjami nazewnictwa.

   Nowy plik .editorconfig zostanie wyświetlony w Eksploratorze rozwiązań i zostanie otwarty w edytorze jako nowa karta.

   

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

Inne sposoby dodawania pliku EditorConfig

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

• Użyj IntelliCode dla Visual Studio, aby wygenerować plik .editorconfig w rozwiązaniu. Kliknij prawym przyciskiem myszy w Eksploratorze rozwiązań i wybierz Dodaj>New EditorConfig (IntelliCode) z menu kontekstowego. Funkcja IntelliCode dla programu Visual Studio wywnioskuje style kodu z istniejącego kodu, a następnie tworzy plik EditorConfig ze wstępnie zdefiniowanymi preferencjami w stylu kodu.

• Automatycznie wygeneruj plik EditorConfig na podstawie ustawień stylu kodu.

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 na niższym poziomie. 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 następującymi wytycznymi:

• Aby zastąpić niektóre lub wszystkie ustawienia EditorConfig, dodaj plik .editorconfig na poziomie hierarchii plików, na którym chcesz, aby zastąpione ustawienia miały zastosowanie. Nowe ustawienia pliku EditorConfig mają zastosowanie do plików na tym samym poziomie i w dowolnych podkatalogach.

  

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

• Jeśli chcesz mieć pewność, że do tej części bazy kodu nie zastosowano żadnych ustawień z plików .editorconfig wyższego poziomu, dodaj właściwość root=true 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ć.

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 Tools>Options ustawienia edytora tekstu Text Editor>C#>Tabulatory w programie Visual Studio skonfiguruj tak, aby po naciśnięciu klawisza Tab były wstawiane cztery znaki spacji.

   

2. Zgodnie z oczekiwaniami, gdy naciśniesz klawisz Tabulatora w następnym wierszu, linia zostaje wcięta przez dodanie czterech znaków odstępu.

   

3. Użyj EditorConfig, aby zmienić ustawienia na używanie tabulatorów.

   Wybierz Użyj kart w pliku EditorConfig.

   pl-PL:

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

   

Rozwiązywanie problemów z ustawieniami EditorConfig

Jeśli plik EditorConfig istnieje w dowolnym miejscu w strukturze katalogów na poziomie lub powyżej lokalizacji projektu, program Visual Studio stosuje ustawienia edytora zawarte w tym pliku do twojego 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 w Tools>Options>Text Editor (na przykład rozmiar wcięcia i styl, rozmiar tabulatora lub konwencje kodowania) są określone w pliku EditorConfig na poziomie projektu lub wyżej w strukturze katalogów, konwencje w pliku EditorConfig zastępują ustawienia w Edytorze tekstu .

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

1. Aby wyłączyć obsługę EditorConfig w programie Visual Studio, odznacz opcję Postępuj zgodnie z konwencjami kodowania projektu w obszarze Narzędzia Tools>Options>Text Editor.

   

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 właściwość root=true 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ę po osiągnięciu ścieżki pliku głównego lub znalezieniu pliku .editorconfig z root=true.

Powiązana zawartość

• Opcje zasad stylu kodu dla platformy .NET
• Obsługa pliku EditorConfig dla usługi językowej
• EditorConfig.org
• funkcje edytora kodu
• pliki konfiguracji dla reguł analizy kodu