Jak zainicjować i tworzyć projekty .NET

Utwórz projekt .NET

Stworzenie projektu .NET od podstaw jest tak proste, jak użycie kreatora Visual Studio. Przejdź do File => New Project lub Add New Project do istniejącego rozwiązania. Po utworzeniu nowego projektu możesz od razu zacząć kodować. Jednak domyślne ustawienia projektu tworzone przez kreatory są trudne do zaakceptowania dla profesjonalnych zespołów, ponieważ stawiają zbyt nisko poprzeczkę w zakresie jakości. Co więcej, żaden kreator nie może wiedzieć o innych krokach konfiguracji, które należy wykonać w konkretnym środowisku programistycznym.

W tym artykule przeprowadzę Cię przez kilka ważnych ustawień, które powinieneś włączyć, gdy tylko stworzysz nowy projekt, co jest ważne, aby zminimalizować przyszły dług techniczny. Omówimy również kilka typowych praktyk stosowanych przez wielu programistów .NET podczas tworzenia rozwiązań i nowych projektów. Nawet jeśli nie stosujesz niektórych z tych pomysłów, dobrze jest nauczyć się i uzyskać przegląd tego, co robi większość zespołów.

Struktura

Dobrze zdefiniowana struktura jest niezbędna w przypadku złożonych projektów. Poprawia to wrażenia on-boardingowe, gdy do zespołu dołączają nowicjusze, i ułatwia życie, gdy wspierasz stare projekty. Istnieją dwa kluczowe wskaźniki dobrej struktury:

• Korzystanie z folderów rozwiązań i projektów
• Spójne nazewnictwo

Lornetka składana

Foldery rozwiązań, czasami nazywane folderami wirtualnymi , są bardzo przydatnym narzędziem do grupowania projektów. W widoku Eksplorator rozwiązań kliknij prawym przyciskiem myszy i wybierz Add => New Solution Folder , a następnie przeciągnij i upuść dowolny z istniejących projektów do tego nowego folderu. Te foldery nie są dublowane w systemie plików, co pozwala zachować niezmienioną strukturę fizyczną, więc przenoszenie projektów z jednego folderu rozwiązania do drugiego nie powoduje ich fizycznego przeniesienia.

Posiadanie ponumerowanych prefiksów nie jest wymagane, ale powoduje to, że foldery są uporządkowane bezpośrednio w oknie Eksplorator rozwiązań .

Program Visual Studio może pracować z wieloma rozwiązaniami jednocześnie, wykorzystując partycjonowane pojedyncze rozwiązanie lub modele z wieloma rozwiązaniami . Są rzadko używane, więc nie będę ich omawiał w tym artykule.

W przeciwieństwie do folderów Solution foldery Project są zgodne ze strukturą folderów fizycznych i dlatego pozostają na dysku jako rzeczywiste foldery. Ponadto foldery projektu zawierające kod C# powinny być zgodne z przestrzenią nazw projektu . To sprawia, że ​​nawigacja jest całkiem naturalna. Możesz nawet włączyć regułę ReSharper, aby ostrzegała o takich niezgodnościach.

Nazywanie

Istnieje kilka zalecanych zasad dotyczących nazewnictwa:

• Użyj CamelCase.
• Nazwa projektu powinna być zgodna z nazwą zestawu wyjściowego.
• Projekt zawierający testy automatyczne powinien mieć przyrostek .Tests .
• Wszystkie nazwy projektów powinny mieć wspólny prefiks, taki jak Company.Product .

Jest też kilka rozsądnych zasad. Powinieneś sam zdecydować, kiedy je zastosować, kierując się zdrowym rozsądkiem (i oczywiście gramatykę angielską):

• Używaj tematów w liczbie mnogiej, gdy kontener (projekt lub folder) zawiera wiele wystąpień tego samego rodzaju (np. Tests lub System.Collections ).
• Użyj formy pojedynczej, gdy cały kontener zawiera kod dotyczący jednej jednostki (np. System.Collections.ObjectModel`).
• W przypadku krótkich skrótów używaj wielkich liter, tak jak robi to System.IO .
• W przypadku długich skrótów użyj CamelCase, takiego jak Modules.Forex. .

Ogólna zasada: krótki skrót nie powinien być dłuższy niż trzy znaki.

Konfiguracja rozwiązania

Konfigurowanie rozwiązania jest tak proste, jak dostarczenie wszystkich plików infrastruktury, których potrzebujesz dla swojego środowiska. Chociaż niektóre z nich można dodać później (np. pliki integracyjne CI), kilka plików lepiej mieć na samym początku.

Ustawienia wyostrzania

Jeśli jesteś profesjonalnym programistą .NET, najprawdopodobniej używasz ReSharper. ReSharper jest bardzo elastyczny w zarządzaniu swoimi ustawieniami. Jako lider zespołu możesz tworzyć i rozpowszechniać ustawienia współdzielenia zespołu , które będą używane przez innych programistów. Ustawienia wspólne dla zespołu są przechowywane w pliku z rozszerzeniem .DotSettings . ReSharper automatycznie wybierze te ustawienia, jeśli nazwa pliku jest zgodna z nazwą rozwiązania programu Visual Studio:

 MyCompany.MyProduct.sln MyCompany.MyProduct.sln.DotSettings

Dlatego powinieneś stworzyć ten plik na samym początku, jeśli ostatecznie chcesz zastosować jakieś ustawienia dla całego zespołu. Dobrym przykładem może być zasada używania (lub nieużywania) słowa kluczowego var . Twój plik ustawień współdzielonych przez zespół może mieć tylko tę jedną regułę, podczas gdy inne są preferencjami programistów. Warto wspomnieć, że w ten sam sposób ustawienia ReSharper można ustawić na poziomie projektu, ponieważ możesz mieć starszy kod, którego nie możesz modyfikować (np. Zmień na użycie słowa kluczowego var ).

Jeśli nazwałeś ten plik poprawnie, jak pokazano w przykładzie, każde nowe wystąpienie programu Visual Studio ze świeżą konfiguracją ReSharper będzie automatycznie wybierało ten plik i wymuszało reguły. Nie zapomnij zatwierdzić tego pliku do kontroli źródła.

Zasady StyleCop

Podobnie jak ustawienia ReSharper, możesz udostępniać ustawienia StyleCop. Jeśli używasz ReSharper, prawdopodobnie masz zainstalowaną wtyczkę integracyjną, która będzie wykorzystywać StyleCop z ReSharper. Jednak StyleCop przechowuje swoje ustawienia niezależnie w plikach o nazwie Settings.StyleCop . Podobnie możesz mieć ten plik wraz z plikiem rozwiązania i plikami projektu.

Jeśli używasz StyleCop, nie zapomnij uruchomić narzędzia konfiguracyjnego StyleCop i wyłączyć kontrole, których nie chcesz wykonywać. Domyślnie wszystkie sprawdzenia są włączone. Zapisz nowe ustawienia w tym pliku i zatwierdź w kontroli źródła.

Pliki tekstowe

Jeśli budujesz produkt publiczny i zamierzasz opublikować kod źródłowy, nie zapomnij również utworzyć i zatwierdzić tych plików:

 README.md LICENSE

Polecam używanie formatu przecen dla pliku README.md , ponieważ stał się on standardem przemysłowym i jest obsługiwany przez publiczne usługi kontroli źródła, takie jak GitHub, a także wewnętrzne serwery, takie jak BitBucket (dawniej Stash).

Specyfikacje NuGet

Jeśli tworzysz bibliotekę, która ma być dystrybuowana w Galerii NuGet, najprawdopodobniej musisz utworzyć pliki specyfikacji pakietu, takie jak MyProject.nuspec . Wolę tworzyć te pliki ręcznie i zatwierdzać je do kontroli źródła. Pakiety są zwykle zwalniane przez jedno z zadań ciągłej integracji (w skrócie CI), ale także w dowolnym momencie możesz zbudować i opublikować pakiet ręcznie z konsoli w następujący sposób:

 nuget.exe pack MyLibrary.nuspec

Tylko nie zapomnij o zwiększeniu wersji pakietu przed wykonaniem tego polecenia.

Pliki specyficzne dla CI

Wszyscy używamy różnych serwerów CI i wszystkie mają różne skrypty konfiguracyjne i ustawienia. Wspomnę tylko o kilku typowych dodatkach, które warto rozważyć:

• Ustawienia NUnit , które określają, jakie zestawy zawierają testy do wykonania na serwerze CI dla poszczególnych zadań. Wszystkie testy są praktycznie podzielone na kilka kategorii. Istnieją testy jednostkowe, które należy uruchamiać przy każdej kompilacji, testy wydajności wykonywane co noc oraz testy integracyjne wykonywane na podstawie poszczególnych wersji.
• Ustawienia NCover , które określają, które zespoły testowe powinny być analizowane pod kątem pokrycia testami.
• Zbierane będą ustawienia SonarQube , które określają metryki oprogramowania.
• Skrypty zadań , takie jak NAnt, PowerShell lub po prostu pliki wsadowe systemu Windows.

Konfiguracja projektów

Pliki projektu, a mianowicie .csproj lub .vbpro , zawierają wszystkie ustawienia używane przez program Visual Studio i MSBuild. Jednak nie wszystkie z nich są dostępne w oknie Właściwości projektu. Aby ręcznie edytować te pliki w programie Visual Studio, wykonaj następujące czynności:

• Kliknij prawym przyciskiem myszy projekt w widoku Eksplorator rozwiązań.
• Wybierz opcję Usuń projekt .
• Kliknij ponownie prawym przyciskiem myszy, aby wybrać akcję Edytuj xyz.csproj .
• Pełna edycja.
• Ponownie kliknij prawym przyciskiem myszy projekt i wybierz opcję Wczytaj ponownie projekt .

Alternatywnie możesz otworzyć plik projektu w swoim ulubionym edytorze tekstu, edytować go i zapisać. Po przełączeniu się z powrotem do okna programu Visual Studio zostanie wyświetlony monit o ponowne załadowanie zmienionego projektu.

Kontrola ostrzeżeń

Tworzenie wysokiej jakości oprogramowania wymaga, aby nigdy nie ignorować ostrzeżeń dotyczących kompilacji. Dlatego należy włączyć maksymalny poziom ostrzeżeń i traktować wszelkie ostrzeżenia jako błędy. Pamiętaj, że powinieneś to zrobić dla wszystkich posiadanych konfiguracji kompilacji, takich jak Debug i Release. Najlepszym sposobem, aby to zrobić, jest zapisanie następujących ustawień we wspólnej grupie właściwości:

 <WarningLevel>4</WarningLevel> <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

I upewnij się, że nie masz takich samych ustawień w innych grupach właściwości. W przeciwnym razie zastąpią odpowiednie właściwości ze wspólnej grupy.

FxCop

Uruchamianie FxCop jest po prostu praktyczne przy każdej konfiguracji. Większość zespołów woli uruchamiać FxCop od czasu do czasu (zwykle przed wydaniem), aby upewnić się, że nie pojawiły się żadne poważne błędy. Jeśli jednak chcesz przeprowadzić ostateczne sprawdzenie każdej kompilacji, dodaj tę opcję:

 <RunCodeAnalysis>true</RunCodeAnalysis>

Zauważ, że FxCop, podobnie jak StyleCop, ma swoje własne ustawienia, które można umieścić w folderze głównym i dodać do kontroli źródła. Te ustawienia są prawdopodobnie używane podczas uruchamiania FxCop na serwerach CI.

Dokumentacja

Ta część dotyczy XmlDoc. Jeśli budujesz publiczne API, powinieneś stworzyć i utrzymywać dokumentację API. Większość programistów zaczyna od programowania API (rzeczywiste kodowanie) i tuż przed wydaniem włączają ustawienie projektu Build / XML documentation file . Oczywiście po kolejnej przebudowie pojawia się mnóstwo błędów, ponieważ każdy brakujący XmlDoc skutkuje błędem kompilacji. Aby tego uniknąć, warto na samym początku włączyć wspomnianą opcję.

Jeśli jesteś zbyt leniwy, aby napisać odpowiednią dokumentację lub nie lubisz wpisywać zbyt dużej ilości tekstu, wypróbuj narzędzia automatyzujące ten proces, takie jak GhostDoc.

Umowy na kod

Code Contracts to doskonała platforma firmy Microsoft Research, która umożliwia wyrażanie warunków wstępnych, warunków końcowych i niezmienników obiektów w kodzie w celu sprawdzania w czasie wykonywania, analizy statycznej i dokumentacji. Używałem tego w wielu krytycznych projektach i bardzo pomogło, więc zachęcam do wypróbowania tego.

Jeśli zdecydujesz się na użycie kontraktów kodu, ważne jest, aby włączyć kontrakty na samym początku, gdy właśnie utworzyłeś nowy projekt. Dodanie kontraktów w trakcie tworzenia jest możliwe, ale będzie wymagało zmian w wielu klasach, aby Kontakty pasowały do ​​siebie. Dlatego nie zapomnij włączyć wszystkich wymaganych ustawień (przynajmniej CodeContractsEnableRuntimeChecking ) i upewnić się, że te ustawienia pojawiają się we wspólnej grupie właściwości.

Egzekwowanie stylu Cop

Wcześniej rozmawialiśmy o konfiguracji StyleCop na czas programowania. Jednak gdy projekt jest kompilowany na serwerze CI, ReSharper nie ma tam żadnego wpływu i dlatego powinniśmy włączyć weryfikację StyleCop, aby działała z MSBuild.

Zwykle odbywa się to poprzez ręczną modyfikację pliku projektu. Musisz zwolnić projekt w Visual Studio, edytować plik projektu, a następnie załadować projekt z powrotem:

 <PropertyGroup> <!— add this to the common property group (common to Debug/Release/etc) —> <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings> </PropertyGroup> <!— add this Import in the very bottom —> <Import Project="$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets">

Ustawienie StyleCopTreatErrorsAsWarnings zrobi to, co mówi: zepsuje twoją kompilację po każdym naruszeniu reguły StyleCop. Element importu jest wymagany, aby program MSBuild dodał zadanie StyleCop do łańcucha kompilacji.

Być może zauważyłeś ścieżkę do Program Files . Ponieważ programiści mogą mieć zainstalowane różne wersje StyleCop, niektóre zespoły preferują przechowywanie prywatnej kopii tej samej instalacji StyleCop pod kontrolą źródła. W takim przypadku ścieżka będzie względna. Ułatwia to również konfigurację maszyn CI, ponieważ nie trzeba instalować StyleCop lokalnie.

Informacje o zespole

Każdy projekt .NET utworzony przez kreatora programu Visual Studio będzie zawierał plik AssemblyInfo.cs wypełniony automatycznie (patrz podfolder Właściwości ), który zawiera niektóre atrybuty Assembly , ale żaden kreator nie może wypełnić wszystkich atrybutów Assembly . Upewnij się, że masz wypełnione przynajmniej te atrybuty:

• AssemblyTitle
• AssemblyDescription
• AssemblyCompany
• AssemblyProduct
• AssemblyCopyright
• AssemblyVersion

To absolutne minimum jest wymagane dla wszelkich zespołów, które zamierzasz dystrybuować. Praktycznym powodem tego jest NuGet: jeśli używasz automatycznego tworzenia specyfikacji NuGet z wybranego pliku zestawu, to narzędzie uzyska potrzebne informacje z tych właściwości.

Na samym początku możesz też zapełnić jeszcze jedną posiadłość:

 InternalsVisibleTo

Ta właściwość sprawia, że ​​klasy wewnętrzne i interfejsy są widoczne dla określonego zestawu. Jest to zwykle używane do automatycznych testów, które zamierzasz utworzyć dla swojego projektu.

Parametry połączenia

Jak zarządzać ciągami połączeń to bardzo popularne pytanie w Stack Overflow. Problem polega na tym, aby parametry połączenia były unikatowe dla każdego dewelopera lub zadania CI, a nie ujawniać szczegółów połączenia podczas publikowania kodu źródłowego.

W App.config (dla aplikacji komputerowych) lub Web.config (dla aplikacji internetowych) wprowadź następujące ustawienie, które spowoduje ładowanie pliku user.config w czasie wykonywania. Zachowaj to pod kontrolą źródła:

 <?xml version="1.0" encoding="utf-8" ?> <configuration> <connectionStrings configSource="user.config"></connectionStrings> </configuration>

Najwyraźniej plik user.config powinien być wyłączony z kontroli źródła, a każdy programista powinien mieć lokalną kopię tego pliku, zachowując prywatność parametrów połączenia:

 <connectionStrings> <add name="test" connectionString="Server=.;Database=...;"/> </connectionStrings>

.gitignore

Dla tych, którzy używają Git jako kontroli źródła, ważne jest, aby dodać kilka wzorców plików do pliku .gitignore . Jednak nasza inteligentna społeczność zbudowała już uogólniony plik, który można znaleźć tutaj: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Powinieneś wziąć go jako plik referencyjny .gitignore i po prostu dodać niestandardowe wykluczenia, których możesz dodatkowo potrzebować.

Odznaki GitHub

Być może widzieliście ładnie wyglądające plakietki pojawiające się na stronie projektu README . Jeśli publikujesz swój projekt w serwisie GitHub, rozważ połączenie projektu z usługami publicznymi w celu:

• Budowanie: aby pokazać, że kompilacja kończy się niepowodzeniem lub przechodzi.
• Testowanie: aby pokazać pokrycie testów i stan wykonania testów.
• Publikowanie: aby wyświetlić najnowszą wersję pakietu NuGet.

Pełną listę odznak i powiązanych usług można znaleźć na shields.io. Możesz znaleźć wiele interesujących odznak, które są dobre dla projektów Open Source.

Po zarejestrowaniu projektu w wybranej usłudze otrzymasz link do obrazu i kompletny link do składni przecen, który możesz dodać do swojego pliku README.md . Nawiasem mówiąc, jest to jeden z powodów, dla których powinieneś preferować markdown dla plików Readme .

Przykładowe odznaki przecenowe z projektu Roslyn:

[![Build Status]([http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)) [![Join the chat at [https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)](https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge))

Automatyczna walidacja struktury rozwiązania

Mimo że ustawiłeś wszystkie ustawienia, które omówiliśmy w tym artykule, prędzej czy później jeden z twoich programistów może je zmienić i zatwierdzić zmiany w kontroli źródła. Czasami dzieje się to przez pomyłkę i często te zmiany nie są wyłapywane podczas przeglądu kodu. Poza tymi wypadkami powinniśmy zwracać uwagę na następujące typowe błędy:

• Złe referencje : gdy ktoś odwołuje się do lokalnego zestawu, którego inni mogą nie mieć, lub gdy ktoś usunął plik z dysku, podczas gdy link do tego pliku pozostaje w pliku .csproj . To na pewno zepsuje kompilację, ale może się to zdarzyć za późno, gdy zmiana zostanie wypchnięta, a inni ją wycofają. Jest to szczególnie ważne w przypadku statycznych plików internetowych, których nie można zweryfikować podczas kompilacji.
• Spójność nazewnictwa : narzędzia, takie jak StyleCop, mogą kontrolować kod źródłowy C#, ale żadne narzędzia nie mogą wymuszać reguł dla plików projektu lub właściwości zespołu. Dobrym przykładem jest to: Chcemy, aby nazwy projektów były zgodne z nazwą zestawu wyjściowego i chcemy, aby nazwy projektów miały wspólny prefiks, taki jak MyCompany.MyProduct .

Zauważyłem, że obserwowanie tych błędów w Przeglądach kodu jest podatne na błędy i powinno być zautomatyzowane. Napisałem więc proste narzędzie, które wykonuje te i wiele innych testów sprawdzających spójność rozwiązania. Poznaj SolutionInspectora. To jest Open Source i rozpowszechniane na licencji MIT. Możesz go zbudować z kodu źródłowego lub zainstalować z NuGet:

 Install-Package SolutionInspector

Narzędzie przechodzi przez całą strukturę rozwiązania i stosuje wiele reguł walidacji. Reguły są konfigurowane za pomocą plików XML, umieszczanych wraz z innymi plikami rozwiązań. Aby kontrolować ustawienia na podstawie projektu, wystarczy dodać ten sam plik z różnymi ustawieniami do odpowiedniego folderu projektu.

Domyślnie nie jest wymagany żaden plik konfiguracyjny. W takim przypadku narzędzie zastosuje wszystkie dostępne reguły i przekaże wszystkie problemy do konsoli.

Oto przykład pliku konfiguracyjnego:

 <?xml version="1.0" encoding="utf-8"?> <Settings xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">](http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">) <SolutionSettings> <MinSolutionFormatVersion>12.00</MinSolutionFormatVersion> <MaxSolutionFormatVersion>12.00</MaxSolutionFormatVersion> <DetectMissingFiles>true</DetectMissingFiles> <ProjectNamePrefix>MyCompany.MyProduct.</ProjectNamePrefix> <ProjectNameIsFileName>true</ProjectNameIsFileName> <IgnoredProjects> AVerySpecialProject1; AVerySpecialProject2; </IgnoredProjects> </SolutionSettings> <ProjectSettings> <DetectMissingFiles>true</DetectMissingFiles> <AllowBuildEvents>true</AllowBuildEvents> <AssemblyNameIsProjectName>true</AssemblyNameIsProjectName> <RootNamespaceIsAssemblyName>true</RootNamespaceIsAssemblyName> <RequiredImports>StyleCop.MSBuild.Targets</RequiredImports> <Properties> <TreatWarningsAsErrors>true</TreatWarningsAsErrors> <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings> </Properties> </ProjectSettings> </Settings>

Chociaż ustawienia są dość opisowe, wyjaśnię niektóre z nich:

• MinSolutionFormatVersion / MaxSolutionFormatVersion uniemożliwi deweloperom przełączanie wersji programu Visual Studio.
• DetectMissingFiles jest bardzo przydatny w przypadku statycznej zawartości sieci Web lub innych plików niebędących kodem dodanych do rozwiązania lub projektu.
• AllowBuildEvents może uniemożliwić dodawanie niestandardowych zdarzeń kompilacji, które mogą wykonywać niepotrzebne rzeczy.
• Properties to najbardziej elastyczny element: możesz porównać dowolne właściwości z żądanymi wartościami, niezależnie od tego, czy są to znane właściwości, czy niestandardowe.

Wniosek

Przejrzeliśmy kilka standardowych praktyk, plików konfiguracyjnych i ustawień projektu, które można zastosować podczas rozpoczynania nowego projektu. Wykonanie tego na samym początku zmniejszy przyszłe zadłużenie techniczne i sprawi, że kod źródłowy Twojego produktu będzie wyglądał ładnie i profesjonalnie. W przypadku projektów Open Source ma to szczególne znaczenie, ponieważ każdy kontrybutor znałby Twoje oczekiwania, badając konfiguracje rozwiązań i pliki projektów.