ALM Rangers

Реализация статического анализа кода с помощью StyleCop

Хамид Шахид

Продукты и технологии:
StyleCop, Visual Studio Team Foundation Server

В статье рассматриваются:

  • основы StyleCop;
  • добавление StyleCop в Team Build;
  • использование настраиваемых шаблонов сборки.

Как часто вы встречали код, который просто невозможно понять? Обычно небрежное форматирование, неправильные комментарии и отсутствие соглашений по именованию делают код нечитаемым. Такие несогласованности часто недооцениваются, считаются маловажными, но они могут существенно затруднить дальнейшее сопровождение кода.

StyleCop — отличная утилита для поддержания согласованного стиля и формата вашего исходного кода. StyleCop подобно Visual Studio Code Analysis выполняет статический анализ кода. Однако в отличие от Visual Studio Code Analysis она может сканировать файлы исходного кода, а не управляемый код. Более того, StyleCop проверяет лишь стилевые рассогласования и не выполняет оптимизацию кода и анализ его производительности.

В этой статье я познакомлю вас с утилитой StyleCop, покажу, как она работает, и рассмотрю факторы, которые следует учитывать при ее внедрении в свой проект. Наконец, я продемонстрирую, как включить запуск StyleCop в процесс сборки, осуществляемый Visual Studio Team Foundation Server (TFS).

Основы StyleCop

StyleCop (stylecop.codeplex.com) — утилита с открытым исходным кодом, выполняющая статический анализ файлов исходного кода на C#. Она интегрируется с Visual Studio и появляется в контекстом меню, давая вам возможность сканировать текущий файл или любые выбранные файлы/проекты. На рис. 1 показаны команды StyleCop, доступные в контекстном меню для проекта Visual Studio.

Команды StyleCop в контекстном меню
Рис. 1. Команды StyleCop в контекстном меню

Если вы выбираете команду Run StyleCop или Run StyleCop (Rescan All), то StyleCop разбирает все файлы на C# и проверяет их на соответствие заданным в StyleCop правилам. Если обнаруживаются какие-то нарушения, в окне Error List появляется предупреждение.

Файл настройки StyleCop Здесь хранятся все параметры конфигурации StyleCop. Этот файл содержит информацию вроде выбранных правил, лексические данные, такие как собственные слова и акронимы, и сведения о том, следует ли объединять этот файл настройки с файлом настройки в родительских каталогах, если таковые есть.

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

Файл собственного словаря Кроме возможности добавления слов и акронимов в файл настройки, StyleCop также позволяет работать с файлом CustomDictionary.xml, который использует тот же формат, что и словарь Visual Studio Code Analysis. Благодаря этому вы можете использовать одинаковый словарь для обеих утилит. Формат файла словаря показан на рис. 2.

Рис. 2. Файл собственного словаря

<Dictionary>
  <Words>
    <Unrecognized>
      <Word/>
    </Unrecognized>
    <Recognized>
      <Word/>
    </Recognized>
    <Deprecated>
      <Term PreferredAlternate=""/>
    </Deprecated>
    <Compound>
      <Term CompoundAlternate=""/>
    </Compound>
    <DiscreteExceptions>
      <Term />
    </DiscreteExceptions>
  </Words>
  <Acronyms>
    <CastingException>
      <Acronym />
    </CastingException>
  </Acronyms>
</Dictionary>

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

Правила StyleCop На основе правил StyleCop проверяет файл исходного кода. Существует ряд готовых правил, и при желании вы можете писать свои правила. В вики по StyleCop вы найдете подробную информацию о написании собственных правил StyleCop (bit.ly/12P665L).

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

Правила StyleCop группируются по семи категориям.

  1. Documentation Rules Проверяют правильность элементов документации в файлах исходного кода.
  2. Layout Rules Проверяют разметку и строчные отступы в файлах исходного кода.
  3. Maintainability Rules Проверяют файлы исходного кода по критериям удобства сопровождения, таким как наличие ненужных скобок или присутствие нескольких классов в одном файле.
  4. Naming Rules Проверяют взаимозаменяемость имен методов и переменных.
  5. Ordering Rules Проверяют правильность упорядочения кода.
  6. Readability Rules Проверяют правильность форматирования и читаемость кода.
  7. Spacing Rules Проверяют правильность отступов в коде.

Подробнее о категориях и самих правилах StyleCop см. в документации по ссылке bit.ly/191GgiQ.

Добавление StyleCop в Team Build

Замечательно, что правила StyleCop выбираются и хранятся в файле настройки, но единственный способ обеспечить согласованное выполнение StyleCop для всего исходного кода — запускать ее как часть процесса сборки.

Это делается двумя способами.

  1. Интегрируем StyleCop с файлом MSBuild проекта C#, чтобы она запускалась при каждой компиляции проекта. В документации StyleCop (bit.ly/13ZX2xL) описывается, как добиться этой цели.
  2. Добавляем StyleCop в ваш непрерывный интеграционный процесс Team Build, чтобы она выполнялась при каждом включении файлов в систему контроля версий.

Я поясню, как запускать StyleCop в непрерывном интеграционном процессе Team Build. Если вы применяете процесс управляемой сборки (gated builds), запуск StyleCop будет гарантировать, что любые файлы исходного кода с нарушениями не будут приняты системой контроля версий. А если такого процесса у вас нет, вы все равно получите приглашение исправить нарушения при включении кода в систему контроля версий.

Чтобы запустить StyleCop в Team Build, процесс должен быть вызван какой-то операцией в рабочем процессе сборки. Я буду использовать операцию StyleCop из проекта Community TFS Build Extensions с открытым исходным кодом (tfsbuildextensions.codeplex.com). Community TFS Build Extensions — это набор библиотек, содержащих ряд повторно используемых операций рабочего процесса, которые вы можете просто перетаскивать в свой шаблон процесса Team Build.

Изменения контроллера сборки Первое, что надо сделать перед настройкой Team Build, — задать путь к вашим сборкам (assemblies) для контроллера сборки (build controller). Это место, откуда агенты сборки (build agents) загружают сборки (assemblies) для любых пользовательских операций, найденных ими в рабочем процессе сборки.

Чтобы добавить собственные сборки, создайте новую папку в соответствующем месте в своем Team Project. Я назвал новую папку Custom Assemblies и создал ее в BuildProcessTemplate непосредственно под корневой папкой Team Project. Теперь зарегистрируйте следующие сборки:

  • StyleCop.dll;
  • StyleCop.CSharp.dll;
  • StyleCop.CSharp.Rules.dll;
  • TFSBuildExtensions.Activities.dll;
  • TFSBuildExtensions.Activities.StyleCop.dll.

Следующий шаг — настройка контроллера сборки на использование этих сборок. Для этого:

  1. щелкните ссылку сборки в Team Explorer. Выберите Actions и укажите Manage Build Controllers;
  2. из появившегося диалогового окна выберите свой контроллер сборки и щелкните кнопку Properties;
  3. в диалоговом окне Build Controller Properties укажите в свойстве Version control path to custom assemblies папку Custom Assemblies, созданную ранее в Team Project, как показано на рис. 3.

Диалоговое окно Build Controller Properties
Рис. 3. Диалоговое окно Build Controller Properties

Щелкните OK и закройте диалоговое окно свойств. К этому моменту контроллер сборки сконфигурирован на загрузку ваших операций. Далее нужно настроить шаблон вашего процесса сборки.

Пользовательские шаблоны сборки

TFS создает для каждого нового Team Project ряд готовых шаблонов сборки. Эти шаблоны создаются в папке ProcessBuildTemplates, которая находится в корне Team Project. Начните с копии шаблона DefaultTemplate.11.1.xaml и добавьте в него операцию StyleCop. Я создал копию файла DefaultTemplate.11.1.xaml и переименовал ее в CustomTemplate.xaml.

Чтобы настроить рабочий процесс сборки, нужно будет добавить пользовательские операции в среду разработки. Для этого создайте новый проект библиотеки операций рабочего процесса в Visual Studio. В диалоге Add New Project убедитесь, что в качестве целевой платформы выбрана Microsoft .NET Framework 4.5. Затем добавьте ссылку на файл CustomTemplate.xaml в только что созданный проект. С этой целью щелкните проект правой кнопкой мыши, выберите Add Existing Item, перейдите к файлу CustomTemplate.xml и щелкните кнопку Add as Link.

Последний шаг в настройке вашей среды разработки — добавление операции StyleCop в окно Toolbox, чтобы разрешить ее перетаскивание. Для этого щелкните правой кнопкой мыши область ниже «activities» в окне Toolbox и выберите Add Tab. Назовите новую вкладку TFS Build Extensions. Щелкните ее имя правой кнопкой мыши и выберите Choose items. Перейдите к сборке TfsBuildExtensions.Activities.Stylecop.dll и щелкните OK. Теперь вы можете открыть файл CustomTemplate.xaml и перетащить в него операцию StyleCop.

Настройка шаблона сборки Вы должны запускать StyleCop на ранних этапах процесса сборки. Это позволяет быстро завершить сборку неудачей, если будут обнаружены любые нарушения. Поскольку StyleCop требует сканирования файлов исходного кода, первое место, где может быть выполнен StyleCop, — сразу за последовательностью Initialize Workspace в рамках последовательности Run On Agent, как показано на рис. 4.

Место, в которое следует перетащить операцию StyleCop
Рис. 4. Место, в которое следует перетащить операцию StyleCop

Определив место в рабочем процессе сборки для добавления операции StyleCop, следует добавить операцию последовательности (sequence activity). Переименуйте операцию последовательности в Run StyleCop. Окончательный список моей последовательности Run StyleCop приведен на рис. 5.

Последовательность Run StyleCop
Рис. 5. Последовательность Run StyleCop

Пример В табл. 1 описываются переменные, определенные в последовательности Run StyleCop, их типы и соответствующее предназначение.

Табл. 1. Переменные, определенные в последовательности Run StyleCop

Имя переменной Тип Описание
SourceCodeFiles IEnumerable<String> Хранит имена всех файлов, которые должна просканировать StyleCop
IsSuccess Boolean Сообщает, выявила ли операция StyleCop какие-нибудь нарушения
ViolationCount Int32 Хранит счетчик числа нарушений, выявленных StyleCop

Рабочий процесс также содержит параметр StyleCopSettingsFile типа String, в котором хранится путь к файлу настройки StyleCop.

Первая операция в последовательности Run StyleCop — FindMatchingFiles. Эта операция содержится в сборке Microsoft.TeamFoundation.Build.Workflow.dll и возвращает список всех файлов, совпадающих с заданным файловым шаблоном. В табл. 2 описано, как задаются свойства этой операции.

Табл. 2. Свойства операции FindMatchingFiles

Имя свойства Значение
DisplayName FindMatchingFiles
IsSuccess String.Format(“{0}\**\*.cs”, BuildDirectory)
Result SourceCodeFiles

Этой операции передается шаблон для поиска всех C#-файлов (*.cs) в Build Directory, и она возвращает результат в перечислении SourceCodeFiles.

Следующая операция в последовательности — ConvertWorkspaceItem, которая находится в сборке Microsoft.TeamFoundation.Build.Workflow.Activities.dll. Она преобразует серверный путь к данному файлу настройки StyleCop (передаваемому как параметр) в локальный путь на сервере сборки. Свойства этой операции показаны в табл. 3.

Табл. 3. Свойства операции Get Local Settings File

Имя свойства Значение
Direction ServerToLocal
DisplayName Get Local Settings File
Input StyleCopSettingsFile
Result StyleCopSettingsFileLocalPath
Workspace Workspace

Теперь, когда получены имена файлов исходного кода и найдено место хранения файла настройки StyleCop, переходим к операции Execute StyleCop в последовательности Run StyleCop. В табл. 4 показано, как задаются свойства этой операции StyleCop.

Табл. 4. Свойства операции Execute StyleCop

Имя свойства Значение
DisplayName Execute StyleCop
LogExceptionStack True
SettingsFile StyleCopSettingsFile
ShowOutput True
SourceFiles SourceCodeFiles.ToArray()
Result StyleCopSettingsFileLocalPath
Succeeded IsSuccess
TreatWarningsAsErrors True

Эта операция принимает перечисление SourceCodeFiles (преобразуемое в массив) как входной параметр и возвращает результат и счетчик нарушений в переменных IsSuccess и ViolationCount соответственно. Ей присваивается отображаемое имя Execute StyleCop, и она настраивается на обработку предупреждений как ошибок, а значит, процесс сборки завершится неудачей, если будут обнаружены любые ошибки.

Последняя операция в последовательности Run StyleCop — Write Build Message. Она настраивается на отображение результата и счетчика нарушений. В табл. 5 показано, как задаются свойства этой операции.

Табл. 5. Свойства операции Write Build Message

Имя свойства Значение
DisplayName Completion Message
Importance Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.Normal
Message String.Format(“StyleCop was completed with {0} violations”, StyleCopViolationsCount)

Теперь ваш пользовательский шаблон сборки готов к использованию. Сохраните и зарегистрируйте файл CustomTemplate.xaml. Чтобы задействовать новый шаблон сборки, откройте определение сборки, щелкните процесс, раскройте узел Build Process Template и нажмите кнопку New. В появившемся диалоговом окне New Process Template выберите Select an existing XAML file и перейдите к файлу CustomTemplate.xaml.

Некоторые соображения по StyleCop

Вот несколько соображений, которые вы должны учитывать.

  • StyleCop в отличие от Visual Studio Code Analysis не поддерживает Visual Basic .NET и применима лишь для файлов исходного кода, написанного на C#.
  • На момент написания этой статьи StyleCop еще не работала с Visual Studio 2013.
  • Hosted Build Controller — это контроллер сборки, размещенный в облаке и доступный через Visual Studio Team Foundation Service. Этапы конфигурирования этого контроллера сборки те же, если вы используете локальный сервер сборки.
  • В этой статье использовался Team Foundation Server (TFS) 2012. Все описанные этапы идентичны для TFS 2010 и TFS 2013. Убедитесь, что используете правильную версию TFS Build Extensions.

Установите для параметра StyleCopSettingsFile значение, указывающее на местонахождение вашего файла Settings.StyleCop. Щелкните Save для сохранения определения сборки. Теперь ваш процесс сборки с участием StyleCop готов к использованию. Лучше всего применять этот шаблон для управляемого процесса сборки (gated builds). Тогда вы будете уверены, что ни один файл исходного кода, зарегистрированный в системе контроля версий, не будет иметь никаких нарушений правил StyleCop.

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

Заключение

Я продемонстрировал, как с помощью StyleCop можно принудительно выполнять статический анализ кода в вашем Team Build. Статический анализ кода способствует применению более качественных стандартов кодирования, и его можно проводить в Team Build, чтобы быть уверенным, что весь зарегистрированный код соответствует вашим стандартам. Аналогично можно вводить в действие и другие правила. Microsoft ALM Rangers создали ряд полезных шаблонов сборки, которые вы можете использовать в проекте Team Foundation Build Customization Guide (vsarbuildguide.codeplex.com). Более того, у вас есть возможность писать свои операции или применять операции, доступные в проекте Community TFS Build Extensions.


Хамид Шахид (Hamid Shahid) — Microsoft ALM Ranger и независимый консультант с более чем 12-летним опытом в проектировании и разработке корпоративного ПО. Способствует распространению передового опыта в применении технологий Microsoft ALM. Ведет блог hamidshahid.blogspot.com и пишет заметки в twitter.com/hamid_shahid.

Выражаю благодарность за рецензирование статьи ALM Rangers и экспертам Майку Фурье (Mike Fourie) (независимый консультант), Вилли-Петеру Шаубу (Willy-Peter Schaub) из Microsoft и Патриции Уэгнер (Patricia Wagner) из Microsoft.