Как загружать и создавать проекты .NET

Создать .NET-проект

Создать проект .NET с нуля так же просто, как использовать мастер Visual Studio. Перейдите в File => New Project или Add New Project в существующее решение. Как только новый проект будет создан, вы можете сразу приступить к написанию кода. Однако настройки проекта по умолчанию, выдаваемые мастерами, вряд ли приемлемы для профессиональных команд, поскольку задают слишком низкую планку качества. Более того, никакие мастера не могут знать о других шагах настройки, которые необходимо выполнить в вашей конкретной среде разработки.

В этой статье я расскажу вам о нескольких важных настройках, которые вы должны включить, как только создадите новый проект, что важно для минимизации будущего технического долга. Кроме того, мы рассмотрим некоторые распространенные методы, которые многие разработчики .NET применяют при структурировании решений и новых проектов. Даже если вы не применяете некоторые из этих идей, приятно узнать и получить представление о том, что делает большинство команд.

Структура

Четко определенная структура жизненно важна для сложных проектов. Это улучшает процесс адаптации, когда к команде присоединяются новички, и облегчает вашу жизнь, когда вы поддерживаете старые проекты. Есть два ключевых показателя хорошей структуры:

• Использование папок решений и проектов
• Согласованное наименование

Папки

Папки решений, иногда называемые виртуальными папками , — очень удобный инструмент для группировки ваших проектов. В представлении Solution Explorer просто щелкните правой кнопкой мыши и выберите Add => New Solution Folder , затем перетащите любой из существующих проектов в эту новую папку. Эти папки не отражаются в файловой системе, что позволяет сохранить физическую структуру неизменной, поэтому перемещение проектов из одной папки решения в другую не приводит к их физическому перемещению.

Наличие нумерованных префиксов не требуется, но это делает папки упорядоченными прямо в окне обозревателя решений .

Visual Studio может работать с несколькими решениями одновременно, используя модели с отдельными секционированными решениями или с несколькими решениями . Они редко используются, поэтому я не буду рассматривать их в этой статье.

В отличие от папок решений, папки проекта соответствуют физической структуре папок и поэтому сохраняются на диске как настоящие папки. Кроме того, папки проекта, содержащие код C#, должны соответствовать пространству имен проекта. Это делает навигацию довольно естественной. Вы даже можете включить правило ReSharper для предупреждения о таких несоответствиях.

Именование

Есть несколько рекомендуемых правил, связанных с именованием:

• Используйте CamelCase.
• Имя проекта должно совпадать с именем его выходной сборки.
• Проект, содержащий автоматизированные тесты, должен иметь суффикс .Tests .
• Все имена проектов должны иметь общий префикс, например Company.Product .

Разумных правил тоже немного. Вы должны сами решить, когда их применять, исходя из здравого смысла (и, конечно, английской грамматики):

• Используйте субъекты во множественном числе, когда контейнер (проект или папка) содержит несколько экземпляров одного типа (например, Tests или System.Collections ).
• Используйте форму единственного числа, когда весь контейнер содержит код, посвященный одному объекту (например, System.Collections.ObjectModel`).
• Для коротких сокращений используйте верхний регистр, как это делает System.IO .
• Для длинных сокращений используйте CamelCase, например Modules.Forex. .

Эмпирическое правило: короткая аббревиатура не должна быть длиннее трех символов.

Настройка решения

Настроить решение так же просто, как предоставить все файлы инфраструктуры, необходимые для вашей среды. Хотя некоторые из них можно добавить позже (например, файлы интеграции CI), несколько файлов лучше иметь в самом начале.

Настройки ReSharper

Если вы профессиональный разработчик .NET, то, скорее всего, вы используете ReSharper. ReSharper очень гибко управляет своими настройками. Как руководитель группы вы можете создавать и распространять общие параметры команды , которые будут использоваться другими разработчиками. Общие настройки Team хранятся в файле с расширением .DotSettings . ReSharper автоматически выберет эти настройки, если имя файла совпадает с именем решения Visual Studio:

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

Поэтому вам следует создать этот файл в самом начале, если вы в итоге хотите применить какие-то настройки ко всей команде. Хорошим примером может служить правило использования (или не использования) ключевого слова var . В вашем файле настроек Team Shared может быть только одно это правило, а другие — на усмотрение разработчиков. Стоит отметить, что таким же образом настройки ReSharper могут быть установлены на уровне каждого проекта, потому что у вас может быть некоторый устаревший код, который вы не можете изменить (например, изменить, чтобы использовать ключевое слово var ).

Если вы правильно назвали этот файл, как показано в примере, то любой новый экземпляр Visual Studio со свежей настройкой ReSharper будет автоматически выбирать этот файл и применять правила. Не забудьте зафиксировать этот файл в системе контроля версий.

Правила StyleCop

Как и в настройках ReSharper, вы можете поделиться настройками StyleCop. Если вы используете ReSharper, то, вероятно, у вас установлен плагин интеграции, который будет использовать StyleCop от ReSharper. Однако StyleCop хранит свои настройки независимо в файлах с именем Settings.StyleCop . Точно так же вы можете иметь этот файл вместе с файлом решения и файлами проекта.

Если вы используете StyleCop, не забудьте запустить инструмент настройки StyleCop и отключить проверки, которые вы не хотите выполнять. По умолчанию все проверки включены. Сохраните новые настройки в этот файл и зафиксируйте их в системе управления версиями.

Текстовые файлы

Если вы собираете общедоступный продукт и собираетесь публиковать исходный код, не забудьте также создать и закоммитить эти файлы:

 README.md LICENSE

Я рекомендую использовать формат уценки для файла README.md , потому что он стал промышленным стандартом и поддерживается общедоступными службами контроля версий, такими как GitHub, а также внутренними серверами, такими как BitBucket (бывший Stash).

NuGet-спецификации

Если вы создаете библиотеку, которая будет распространяться в галерее NuGet, вам, скорее всего, потребуется создать файлы спецификации пакета, например MyProject.nuspec . Я предпочитаю создавать эти файлы вручную и передавать их в систему управления версиями. Пакеты обычно выпускаются одним из ваших заданий непрерывной интеграции (сокращенно CI), но также в любое время вы можете собрать и опубликовать пакет вручную из консоли следующим образом:

 nuget.exe pack MyLibrary.nuspec

Только не забудьте увеличить версию пакета перед выполнением этой команды.

Файлы, специфичные для CI

Мы все используем разные CI-серверы, и все они имеют разные сценарии настройки и настройки. Я бы просто упомянул некоторые из общих дополнений, которые вы можете добавить:

• Настройки NUnit , которые указывают, какие сборки содержат тесты, которые должны выполняться на сервере CI для определенных заданий. Все тесты практически разбиты на несколько категорий. Существуют модульные тесты , которые следует запускать при каждой сборке, тесты производительности , выполняемые каждую ночь, и интеграционные тесты, выполняемые для каждого релиза.
• Параметры NCover , которые указывают, какие тестовые сборки следует анализировать для покрытия тестами.
• Будут собраны настройки SonarQube , которые определяют метрики программного обеспечения.
• Сценарии заданий , такие как NAnt, PowerShell или просто пакетные файлы Windows.

Настройка проектов

Файлы проекта, а именно .csproj или .vbpro , содержат все параметры, используемые Visual Studio и MSBuild. Однако не все из них доступны в окне свойств проекта. Чтобы отредактировать эти файлы в Visual Studio вручную, вы должны сделать следующее:

• Щелкните правой кнопкой мыши проект в представлении обозревателя решений.
• Выберите «Выгрузить проект» .
• Щелкните правой кнопкой мыши еще раз, чтобы выбрать действие Edit xyz.csproj .
• Полное редактирование.
• Щелкните проект правой кнопкой мыши еще раз и выберите «Перезагрузить проект» .

Кроме того, вы можете открыть файл проекта в своем любимом текстовом редакторе, отредактировать его и сохранить. Когда вы вернетесь в окно Visual Studio, вам будет предложено перезагрузить измененный проект.

Предупреждения

Создание высококачественного программного обеспечения требует от вас никогда не игнорировать предупреждения сборки. Поэтому следует включить максимальный уровень предупреждений и рассматривать любые предупреждения как ошибки. Обратите внимание, что вы должны сделать это для всех имеющихся у вас конфигураций сборки, таких как Debug и Release. Лучший способ сделать это — записать в общую группу свойств следующие параметры:

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

И убедитесь, что у вас нет таких же настроек в других группах свойств. В противном случае они переопределяют соответствующие свойства из общей группы.

ФксКоп

Запуск FxCop просто практичен для каждой сборки. Большинство команд предпочитают время от времени запускать FxCop (обычно перед выпуском), чтобы убедиться, что не было допущено серьезных ошибок. Однако, если вы хотите выполнять окончательную проверку каждой сборки, добавьте эту опцию:

 <RunCodeAnalysis>true</RunCodeAnalysis>

Обратите внимание, что FxCop, как и StyleCop, имеет свои собственные настройки, которые можно поместить в корневую папку и добавить в исходный контроль. Эти настройки, вероятно, используются при запуске FxCop на серверах CI.

Документация

Эта часть посвящена XmlDoc. Если вы создаете общедоступный API, вам следует создать и поддерживать документацию API. Большинство разработчиков начинают с разработки API (фактического кодирования), а непосредственно перед релизом включают настройку проекта Build / XML documentation file . Естественно, после очередной пересборки появляется куча ошибок, потому что каждый отсутствующий XmlDoc приводит к ошибке сборки. Чтобы этого не произошло, следует включить указанную опцию в самом начале.

Если вам лень писать надлежащую документацию или вы не любите набирать слишком много текста, попробуйте инструменты, которые автоматизируют этот процесс, такие как GhostDoc.

Кодовые контракты

Code Contracts — это отличная структура от Microsoft Research, которая позволяет вам выражать предварительные условия, постусловия и инварианты объектов в вашем коде для проверки во время выполнения, статического анализа и документации. Я использовал это во многих важных проектах, и это очень помогло, поэтому я рекомендую вам попробовать.

Если вы решили использовать Code Contracts, то важно включить Contracts в самом начале, когда вы только что создали новый проект. Добавление контрактов в середине разработки возможно, но потребует изменений во многих классах, чтобы контакты соответствовали друг другу. Итак, не забудьте включить все необходимые настройки (хотя бы CodeContractsEnableRuntimeChecking ) и убедиться, что эти настройки отображаются в общей группе свойств.

Правоприменение StyleCop

Ранее мы говорили о настройке StyleCop на время разработки. Однако, когда ваш проект создается на сервере CI, ReSharper не оказывает на него никакого влияния, и поэтому мы должны включить проверку StyleCop для запуска с MSBuild.

Обычно это делается путем ручной модификации файла проекта. Вам нужно выгрузить проект в Visual Studio, отредактировать файл проекта и затем загрузить проект обратно:

 <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">

Параметр StyleCopTreatErrorsAsWarnings будет делать то, что он говорит: он сломает вашу сборку при любом нарушении правила StyleCop. Элемент import необходим MSBuild для добавления задачи StyleCop в цепочку сборки.

Вы могли заметить путь к Program Files . Поскольку у разработчиков могут быть установлены разные версии StyleCop, некоторые команды предпочитают хранить частную копию одной и той же установки StyleCop под контролем исходного кода. В этом случае путь будет относительным. Это также упрощает настройку компьютеров CI, поскольку вам не нужно устанавливать StyleCop локально.

Информация о сборке

В каждом проекте .NET, созданном мастером Visual Studio, автоматически заполняется файл AssemblyInfo.cs (см. вложенную папку « Свойства »), который содержит некоторые атрибуты Assembly , но ни один мастер не может заполнить все атрибуты Assembly за вас. Убедитесь, что у вас заполнены хотя бы эти атрибуты:

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

Этот минимум требуется для любых сборок, которые вы собираетесь распространять. Практической причиной этого является NuGet: если вы используете автоматическое создание спецификации NuGet из выбранного файла сборки, этот инструмент будет получать необходимую информацию из этих свойств.

Вы также можете заполнить еще одно свойство в самом начале:

 InternalsVisibleTo

Это свойство делает внутренние классы и интерфейсы видимыми для указанной сборки. Обычно это используется для автоматических тестов, которые вы собираетесь создать для своего проекта.

Строки подключения

Как управлять строками подключения — очень популярный вопрос на Stack Overflow. Проблема заключается в том, как сделать строки подключения уникальными для каждого разработчика или задания CI, а не раскрывать детали подключения при публикации исходного кода.

В App.config (для настольных приложений) или Web.config (для веб-приложений) установите следующий параметр, который будет загружать файл user.config во время выполнения. Держите это под контролем источника:

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

Судя по всему, файл user.config следует исключить из системы контроля версий, и каждый разработчик должен иметь локальную копию этого файла, сохраняя конфиденциальность строки подключения:

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

.gitignore

Для тех, кто использует Git в качестве системы управления версиями, важно добавить некоторые шаблоны файлов в файл .gitignore . Однако наше умное сообщество уже создало обобщенный файл, который можно найти здесь: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Вы должны взять его как справочный файл .gitignore и просто добавить свои пользовательские исключения, которые могут вам дополнительно понадобиться.

Значки GitHub

Возможно, вы видели красивые значки, появляющиеся на странице проекта README . Если вы публикуете свой проект на GitHub, рассмотрите возможность подключения вашего проекта к общедоступным сервисам для:

• Сборка: чтобы показать, что сборка завершается с ошибкой или проходит успешно.
• Тестирование: чтобы показать тестовое покрытие и статус выполнения теста.
• Публикация: чтобы показать последнюю версию пакета NuGet.

Полный список значков и сопутствующих услуг можно найти на Shields.io. Вы можете найти много интересных значков, которые хороши для проектов с открытым исходным кодом.

После того, как вы зарегистрируете свой проект в выбранном сервисе, вам будет предоставлена ​​ссылка на изображение и полная ссылка на синтаксис уценки, которую вы можете добавить в свой файл README.md . Кстати, это одна из причин, почему вы должны предпочесть уценку для файлов Readme .

Примеры значков уценки из проекта 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))

Автоматическая проверка структуры решения

Несмотря на то, что вы установили все настройки, которые мы обсуждали в этой статье, рано или поздно один из ваших разработчиков может изменить их и зафиксировать изменения в системе управления версиями. Иногда это происходит по ошибке, и часто эти изменения не улавливаются во время проверки кода. Помимо этих несчастных случаев, мы должны следить за следующими распространенными ошибками:

• Плохие ссылки : когда кто-то ссылается на локальную сборку, которой у других может не быть, или когда кто-то удалил файл с диска, а ссылка на этот файл остается в файле .csproj . Это наверняка сломает сборку, но это может произойти слишком поздно, когда изменение будет отправлено, а другие вытащат его. Это особенно важно для статических веб-файлов, которые вы не можете проверить во время сборки.
• Согласованность имен : такие инструменты, как StyleCop, могут управлять исходным кодом C#, но никакие инструменты не могут применять правила для файлов проекта или свойств сборки. Вот хороший пример: мы хотим, чтобы имена проектов соответствовали имени выходной сборки, и мы хотим, чтобы имена проектов имели общий префикс, например MyCompany.MyProduct .

Я обнаружил, что отслеживание этих ошибок в Code Review чревато ошибками и должно быть автоматизировано. Поэтому я написал простой инструмент, который выполняет эти и многие другие проверки для проверки согласованности решения. Познакомьтесь с SolutionInspector. Это с открытым исходным кодом и распространяется по лицензии MIT. Вы можете собрать его из исходного кода или установить из NuGet:

 Install-Package SolutionInspector

Инструмент проходит через всю структуру решения и применяет множество правил проверки. Правила настраиваются файлами XML, размещенными вместе с другими файлами решения. Чтобы управлять настройками для каждого проекта, вы просто добавляете один и тот же файл с разными настройками в соответствующую папку проекта.

По умолчанию файл конфигурации не требуется. В этом случае инструмент применит все доступные правила и выведет все проблемы на консоль.

Вот пример файла конфигурации:

 <?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>

Хотя настройки довольно описательные, я объясню некоторые из них:

• MinSolutionFormatVersion / MaxSolutionFormatVersion не позволит вашим разработчикам переключать версию Visual Studio.
• DetectMissingFiles очень полезен для статического веб-контента или других файлов, не являющихся кодом, добавленных в решение или проект.
• AllowBuildEvents может предотвратить добавление пользовательских событий сборки, которые могут привести к ненужным действиям.
• Properties — наиболее гибкий элемент: вы можете проверить любые свойства на соответствие желаемым значениям, будь то известные свойства или пользовательские.

Заключение

Мы рассмотрели несколько стандартных практик, файлов конфигурации и параметров проекта, которые вы можете применить при запуске нового проекта. Если вы сделаете это в самом начале, это уменьшит будущий технический долг и сделает исходный код вашего продукта красивым и профессиональным. Для проектов с открытым исходным кодом это имеет особое значение, потому что любой участник узнает ваши ожидания, изучив конфигурации решения и файлы проекта.