Аннотация

Утилита BuildIt - консольное приложение Microsoft^® .NET, автоматизирующее процесс сборки приложений, рассмотренный в документе "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe" в MSDN^® Library (ищите в разделе patterns & practices). BuildIt спроектирована, разработана и протестирована Sapient Corporation, а также отрецензирована Microsoft, в частности членами группы patterns & practices и теми, кто отвечает за систему разработки Visual Studio^® .NET.

Используя BuildIt, вы:

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

BuildIt позволяет быстро настроить процесс сборки, применяемый в ходе разработки распределенных .NET-приложений. К скачиваемой программе прилагаются полный исходный код и исчерпывающая документация по применению в Microsoft Visual C#^® и Visual Basic^® .NET.

Примечание
Сейчас BuildIt поддерживает сборку решений, которые содержат установочные проекты, созданные в среде Visual Studio .NET для проектов на Visual Basic .NET и Visual C#. Мы не тестировали свою утилиту с проектами на других .NET-языках или с другими установочными проектами (например основанными на Wise или InstallShield).

Хотя BuildIt прошла тестирование и рецензирование и считается вполне надежной, ее код и документация предоставляются на условиях "как есть".

Данный документ состоит из следующих разделов.

Скачивание и установка BuildIt
Проверка установленного приложения
Руководство пользователя
Развертывание и администрирование
Известные проблемы
Проектирование и реализация
Описание классов
Часто задаваемые вопросы
Резюме

Скачивание и установка BuildIt

Щелкните эту ссылку, чтобы скачать BuildIt.

При установке в меню Programs создастся подменю Microsoft Application Blocks for .NET, в свою очередь содержащее подменю Sapient BuildIt, из которого открывается решение Visual Studio .NET для BuildIt.

Проверка установленного приложения

Чтобы убедиться, что BuildIt работает правильно, соберите два решения-примера, находящиеся в папке Program Files\BuildIt\Code\BuildItTest. Выполните следующие операции.

Чтобы добавить элементы в систему контроля исходных файлов

1. Создайте в Visual SourceSafe^® (VSS) проект BuildItTest.
2. Укажите для $/BuildItTest рабочую папку Program Files\BuildIt\Code\BuildItTest.
3. Добавьте в VSS файлы с информацией о версиях сборки.
   1. Добавьте файл Program Files\BuildIt\Code\BuildItTest\AssemblyVersionInfo.cs в $/BuildItTest.
   2. Сделайте то же самое для AssemblyVersionInfo.vb.
4. Создайте виртуальный каталог для Web-проекта (Project2).
   1. Перейдите в Program Files\BuildIt\Code\BuildItTest\Solution2\Project2.
   2. Щелкните правой кнопкой мыши Project2 и выберите Properties.
   3. Щелкните ярлычок Web Sharing, затем - Share this folder.
   4. Согласитесь с псевдонимом по умолчанию (default alias). Щелкните OK, чтобы закрыть диалоговое окно Edit Alias.
   5. Щелкните OK, чтобы закрыть диалоговое окно Properties.
5. Добавьте решения в VSS.
   1. Откройте файл Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
   2. В Solution Explorer щелкните правой кнопкой мыши Solution1 и выберите Add Solution to Source Control.
   3. Перейдите в $/BuildItTest и щелкните OK (щелкните Yes для создания проекта VSS).
   4. Если потребуется указать местонахождение Project1, перейдите в $/BuildItTest/Solution1 и щелкните OK.
   5. Повторите операции по пп. a-d для решения Solution2.
6. Задайте в VSS совместное использование файлов версий сборок.
   1. Сделайте $/BuildItTest/AssemblyVersionInfo.cs доступным папке $/BuildItTest/Solution1/Project1.
   2. Сделайте $/BuildItTest/AssemblyVersionInfo.vb доступным папке $/BuildItTest/Solution2/Project2.

Чтобы добавить файлы версий сборок в проекты

1. Добавьте файл AssemblyVersionInfo.cs в проект Project1 решения Solution1:
   1. Откройте решение Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
   2. В Solution Explorer щелкните правой кнопкой мыши Project1, выберите Add и щелкните Add Existing Item.
   3. Перейдите к ProgramFiles\BuildIt\Code\BuildItTest\Solution1\Project1\AssemblyVersionInfo.cs и щелкните Open.
   4. В диалоговом окне Check Out for Edit щелкните Check Out, чтобы снять Project1.csproj с учета.
   5. Откройте AssemblyVersionInfo.cs и обратите внимание на номер версии (1.0.0.*).
   6. Нажмите CTRL+SHIFT+B, чтобы собрать решение.
   7. В Solution Explorer щелкните правой кнопкой мыши Project1 и выберите Check In Now (Recursive).
   8. Повторите операции по пп. a-g, чтобы добавить AssemblyVersionInfo.vb в проект Project2 решения Solution2.
2. Измените параметры конфигурации.
   1. Откройте файл Program Files\BuildIt\Code\BuildItTest\BuildIt.exe.config.
   2. Отредактируйте параметры sourceControl.
3. Разверните BuildIt.
   1. Откройте файл Open Program Files\BuildIt\Code\BuildIt.sln.
   2. Нажмите CTRL+SHIFT+B, чтобы собрать решение (убедитесь, что вы собираете Release-версию).
   3. Скопируйте .exe-файл и все .dll-файлы из папки Program Files\BuildIt\Code\BuildIt\bin\Release в папку Program Files\BuildIt\Code\BuildItTest.
4. Запустите и проверьте BuildIt.
   1. Откройте файл Program Files\BuildIt\Code\BuildItTest\BuildNumber.xml и обратите внимание, что следующий номер сборки - 1.
   2. Откройте файл Program Files\BuildIt\Code\BuildItTest\BuildIt.bat и посмотрите на командную строку BuildIt.
   3. Запустите BuildIt.bat, чтобы собрать решения.
   4. Откройте файл Program Files\BuildIt\Code\BuildItTest\BuildIt.log и проверьте, не было ли ошибок.
   5. Откройте файл Program Files\BuildIt\Code\BuildItTest\BuildReport.log и посмотрите результаты сборки.
   6. Откройте файл BuildNumber.xml. Обратите внимание, что следующий номер сборки увеличился до 2.
   7. Откройте файл AssemblyVersionInfo.cs или AssemblyVersionInfo.vb и обратите внимание, что номера версий изменились с 1.0.0.* на 1.0.1.*.
   8. Перейдите в папку Program Files\BuildIt\Code\BuildItTest\Archive\1 и убедитесь, что сгенерированные сборки помещены в папку, номер которой соответствует номеру версии.
   9. Перейдите в папку Program Files\BuildIt\Code\BuildItTest\Latest и убедитесь, что сгенерированные сборки копируются в папку последних версий.
   10. В VSS просмотрите хронологию (Show history) по $/BuildItTest и убедитесь, что проект VSS помечен номером версии.

Руководство пользователя

В следующих разделах дается подробная информация об использовании BuildIt.

Управление номерами сборок
Сборка решений
Просмотр отчета о сборке
Повторная сборка решения
Архивирование сборок
Отправка информации о результатах по электронной почте
Контроль версий сборок

Управление номерами сборок

В BuildIt номера сборок используются, чтобы помечать решения, исходные файлы которых контролируются VSS, и обновлять номера версий сборок (если установлен соответствующий параметр сборки). При успешном завершении каждой сборки BuildIt генерирует новый номер сборки, увеличивая текущий номер на единицу (если сборка терпит неудачу, номер не увеличивается). Затем новый номер сборки сохраняется в XML-файле, имя и местонахождение которого задаются атрибутом buildNumberFilePath, содержащимся в файле BuildIt.exe.config.

В следующем примере показывается содержимое XML-файла BuildNumber.xml, где хранится номер сборки.

<buildNumber>1000</buildNumber>

Примечание
XML-файл номера сборки необходимо создать и инициализировать начальным номером сборки перед запуском BuildIt. Кроме того, номера сборок должны быть целыми положительными числами.

Сборка решений

BuildIt можно настроить на сборку одного или нескольких решений. В системах на основе нескольких решений, содержащих файловые ссылки друг на друга, необходимо указывать решения в правильном порядке. Например, если решение Solution2 зависит от решения Solution1, вы должны задать, что Solution1 следует собирать перед Solution2.

Фрагмент кода из BuildIt.exe.config показывает, как настроить BuildIt на сборку системы на основе нескольких решений:

<solutions latestRootFolderFullName="c:\System"
 buildNumberFilePath="c:\System\BuildNumber.xml">
  <solution path="c:\System\Solution1\Solution1.sln"/>
  <solution path="c:\System\Solution2\Solution2.sln"/>
</solutions>

Просмотр отчета о сборке

После каждой сборки BuildIt генерирует отчет, помещаемый в файл BuildReport.log в рабочей папке. Отчет о сборке можно просмотреть в любом текстовом редакторе. Он содержит итоговую информацию и два списка: решения, собранные удачно, и решения, сборка которых потерпела неудачу. Если какие-либо решения не удалось собрать, их можно собрать вручную в Visual Studio .NET, чтобы выяснить, в чем дело.

=============================================
Build Report Generated by BuildIt
=============================================
Build Number:    8016
Build Start:    9/12/2002 6:50:09 PM
Build End:    9/12/2002 6:50:43 PM
Build Duration:  1 minute(s)
Archive Folder:  c:\System\Archive\8016\
Latest Folder:    c:\System\Latest\
Build Results:    1 succeeded, 0 failed

=============================================
Succeeded
=============================================
c:\System\Solution1\Solution1.sln

=============================================
Failed
=============================================

Повторная сборка решения

Повторная сборка (ключ /rebuild) требуется, если сборка по каким-то причинам была прервана. Перед повторной сборкой решения выполните следующие операции.

Чтобы выполнить прерванную сборку заново

1. Если для исправления ошибок необходимо изменять код, вручную снимите требуемые файлы с регистрации в VSS и перенесите на компьютер, где выполняется сборка.
   Примечание
   При снятии файлов с регистрации используйте те же учетные данные для входа в VSS, что и заданные в файле конфигурации утилиты сборки. Это позволит идентифицировать файлы, которые пришлось изменить для исправления ошибок.
2. Отредактируйте код, перекомпилируйте его в Visual Studio .NET и протестируйте перекомпилированные файлы.
3. Когда вы убедитесь, что ошибка исправлена, зарегистрируйте измененные файлы.
4. Вручную обновите метку каждого зарегистрированного файла меткой, сгенерированной во время предыдущей сборки.
   1. Щелкните имя файла правой кнопкой мыши и выберите Show History.
   2. В диалоговом окне History Options щелкните OK.
   3. Щелкните версию файла, метку которого вы хотите обновить, затем щелкните Details.
   4. Обновите поле Label меткой, использовавшейся при сборке (например "Build 100").
5. Вручную запустите BuildIt с параметром /rebuild.

Архивирование сборок

Можно настроить BuildIt на архивирование предыдущих сборок в заданный каталог в соответствии с описанием, приведенным в разделе "Хранение предыдущих версий" документа "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe" в MSDN Library.

Когда установлен параметр сборки archiveBuild, утилита копирует сгенерированные сборки в папку, имя которой соответствует номеру текущей версии сборки. Эта папка является подпапкой корневой папки архивирования, задаваемой в файле конфигурации атрибутом archiveRootFolderFullName.

По умолчанию BuildIt архивирует только результаты сборки проектов на Visual C# и Visual Basic .NET. Чтобы заархивировать результаты сборки проектов других типов, например установочных проектов Visual Studio .NET, добавьте элементы folder в элемент additionalFoldersToArchive.

В следующем фрагменте файла BuildIt.exe.config показывается, как использовать эти элементы.

<options>
  <archiveBuild mode="on" archiveRootFolderFullName="c:\System\Archive">
    <additionalFoldersToArchive>
      <folder fullName=" c:\System\Solution1\Setup1\Debug"
       destFolderName="Debug\Setup1" />
      <folder fullName=" c:\System\Solution1\Setup1\Release"
       destFolderName="Release\Setup1" />
    </additionalFoldersToArchive>
  </archiveBuild>
</options>

Отправка информации о результатах по электронной почте

В BuildIt реализована отправка информации о результатах сборок в сообщениях электронной почты, описанная в разделе "Рассылка по электронной почте информации о сборке" в документе "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe" в MSDN Library. Для этого нужно соответствующим образом настроить BuildIt, в частности задать адрес, на который отправляются сообщения.

Если установлен параметр сборки sendBuildReport, утилита генерирует и отправляет на адрес электронной почты, заданный атрибутом toAddress, электронное сообщение, содержащее файл BuildReport.log с отчетом о сборке.

В следующем фрагменте файла BuildIt.exe.config показывается, как настроить этот параметр:

<options>
  <sendBuildReport mode="on" smtpServer="255.255.255.255"
   toAddress="you@yourcompany.com"/>
</options>

Контроль версий сборок

BuildIt можно настроить на обновление версии сборки текущим номером, который хранится в XML-файле, заданном атрибутом buildNumberFilePath:

<solutions buildNumberFilePath="c:\System\BuildNumber.xml">

Версия сборки обычно задается атрибутом AssemblyVersion (определяемым в файле AssemblyInfo.cs или AssemblyInfo.vb). Однако, когда в конфигурации утилиты задано обновление версии сборки, атрибут AssemblyVersion следует определить в отдельном файле (например в AssemblyVersionInfo.cs или AssemblyVersionInfo.vb), совместно используемом в VSS всеми .NET-проектами решения. Благодаря этому BuildIt может обновить один файл и передать изменение всем проектам решения. Дополнительную информацию см. в разделе "Централизованное формирование номеров версий сборок" документа "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".

ПримечаниеДва файла-примера AssemblyVersionInfo.cs и AssemblyVersionInfo.vb копируются в папку BuildItTest при установке BuildIt.

Номер версии физически состоит из четырех частей - чисел, разделенных точками:

<старший номер версии>.<младший номер версии>.<номер сборки>.<ревизия>

Когда установлен параметр сборки updateAssemblyVersion, утилита обновляет сегмент <номер сборки> атрибута AssemblyVersion текущим номером сборки.

В следующем фрагменте файла BuildIt.exe.config показывается, как установить этот параметр.

<options>
  <updateAssemblyVersion mode="on"
   csAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.cs"
   vbAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.vb" />
</options>

Развертывание и администрирование

В этом разделе рассматриваются следующие вопросы администрирования.

Развертывание BuildIt
Настройка BuildIt
Защита BuildIt
Устранение неполадок при работе с BuildIt

Развертывание BuildIt

При развертывании любого приложения важно выявить все существующие зависимости. BuildIt реализована в виде одной сборки BuildIt.exe и зависит от следующих файлов и систем:

• BuildIt.exe.config - параметры конфигурации;
• BuildNumber.xml содержит следующий номер сборки;
  Примечание
  Имя и путь XML-файла номера сборки задаются атрибутом buildNumberFilePath в файле BuildIt.exe.config. Обратите внимание, что XML-файл с номером сборки необходимо создать и инициализировать начальным номером сборки до запуска BuildIt. Дополнительную информацию см. в разделе "Хранение номеров сборок".
• Microsoft.ApplicationBlocks.ExceptionManagent.dll и Microsoft.ApplicationBlock.ExceptionManagent.Interfaces.dll обрабатывают исключения;
• Interop.SourceSafeTypeLib.dll - используется при взаимодействии с VSS API (SSAPI.dll);
• Visual SourceSafe 6.0c - клиентские программы для доступа к удаленной базе данных VSS;
• Visual Studio .NET - выполняет сборку .NET-решений.

  Приняв к сведению эту информацию, можно выбрать способ развертывания, удовлетворяющий требованиям группы разработчиков. Предлагается два способа развертывания BuildIt: с помощью XCOPY или Windows Installer. В следующих разделах эти варианты рассматриваются более подробно.

Развертывание с помощью XCOPY
Развертывание BuildIt командой XCOPY - самый простой способ; однако от специалиста, развертывающего BuildIt, требуется больше знаний. При использовании этого способа требуемые сборки и файл конфигурации приложения (BuildIt.exe.config) копируются командой XCOPY в каталог на компьютере, на котором развертывается приложение. Затем системной утилитой Installutil.exe вызывается класс ExceptionManagerInstaller, чтобы создать источники событий, необходимые стандартному классу публикации исключения (exception publisher) при записи данных в Windows Event Log. Например, выполняется следующая командная строка:

Installutil.exe Microsoft.ApplicationBlocks.ExceptionManagement.dll

Дополнительную информацию об Exception Management Application Block см. в разделе MSDN Library Microsoft Application Blocks for .NET.

Развертывание с помощью Windows Installer
Развертывание BuildIt с помощью Windows Installer требует больше усилий, чем при использовании XCOPY, но знаний - меньше. При создании проекта Setup and Deployment в Visual Studio.NET добавьте в папку приложения результаты сборки проектов BuildIt, Exception Management и Exception Management Interfaces, а также файл BuildIt.exe.config. Затем добавьте результаты сборки проекта Exception Management в список дополнительных действий (custom action), чтобы при установке создавался экземпляр класса ExceptionManagerInstaller.

Настройка BuildIt

Поведение утилиты контролируется файлом конфигурации приложения. Файлы конфигурации приложения - это XML-документы, размещаемые в корневом каталоге иерархии каталогов приложения. Имя файла конфигурации приложения имеет вид имя_приложения.расширение_файла.config. Для BuildIt такой файл называется BuildIt.exe.config.

В этом разделе содержатся следующие разделы, описывающие конфигурирование BuildIt.

Задание параметров сборки приложений
Настройка трассировки
Настройка управления исключениями
Использование с несколькими версиями Visual Studio .NET

ПримечаниеИзменения, внесенные в файл конфигурации, вступают в силу после перезапуска BuildIt.

Задание параметров сборки приложений
Каждый режим сборки можно включить или отключить, присвоив атрибуту mode значение on/off, как, например, в следующем фрагменте кода:

<options>
  <sendBuildReport mode="on" smtpServer="255.255.255.255"
   toAddress="you@company.com"/>
</options>

Примечание
Если атрибут mode отсутствует или имеет любое значение, отличное от on/off, то генерируется исключение. Кроме того, значения атрибута mode не чувствительны к регистру.

Настройка трассировки
В BuildIt при генерации информации трассировки, выводимой на консоль или в файл BuildIt.log в рабочей папке, используется класс Trace пространства имен System.Diagnostics. Ниже приведен пример вывода трассировки.

Validating command-line arguments
Reading BuildIt settings from configuration file
Starting build 100 at 11/1/2002 1:57:53 PM
Updating assembly version file $/System/AssemblyVersionInfo.cs
Labelling source
Getting source from label
Backing up latest folder
Building Debug version of solution C:\System\Solution1\Solution1.sln
Building Release version of solution C:\System\Solution1\Solution1.sln
Building Debug version of solution C:\System\Solution2\Solution2.sln
Building Release version of solution C:\System\Solution2\Solution2.sln
2 solution(s) succeeded, 0 failed
Deleting latest backup folder
Archiving additional folders
Generating build report
Not sending build report because the option was not enabled
Ending build at 11/1/2002 1:58:40 PM - 0 minute(s) to complete

Включена трассировка или выключена, определяется значением переменной traceLevel типа TraceSwitch, задаваемым в файле BuildIt.exe.config file. Если переменная типа TraceSwitch имеет значение 0, то трассировка выключена, если задано значение 3, трассировка включена. При присваивании TraceSwitch значения 4 выводится более подробная информация трассировки (устанавливается режим отображения всей информации).

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

<system.diagnostics>
  <switches>
    <add name="traceLevel" value="3"/>
  </switches>
</system.diagnostics>

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

<appSettings>
  <add key="appendTraceOutput" value="off" />
</appSettings>

Примечание
Если ключ appendTraceOutput отсутствует, BuildIt по умолчанию перезаписывает файл трассировки.

Настройка управления исключениями
В BuildIt используется Exception Management Application Block, разработанный Microsoft. Его параметры задаются в XML-файле конфигурации. Если параметры не указаны, Exception Management Application Block по умолчанию публикует исключения в журнале приложения. Однако можно использовать и свои средства публикации исключений.
На момент написания данного документа параметры Exception Management не настраиваются в файле конфигурации. Поэтому все исключения публикуются в журнале событий, который можно просмотреть с помощью Event Viewer. Дополнительную информацию см. в разделе MSDN Library "Exception Management Application Block Overview".

Использование с несколькими версиями Visual Studio .NET
По умолчанию BuildIt использует для сборки решений самую позднюю установленную на компьютере версию Visual Studio .NET. Однако, если на компьютере установлено несколько версий, разработчик может использовать при работе с BuildIt какую-либо другую версию Visual Studio .NET. Чтобы BuildIt использовала определенную версию Visual Studio .NET, поместите в раздел appSettings файла конфигурации ключ visualStudioProgID. Вот как это делается.

<appSettings>
  <add key="visualStudioProgID" value="VisualStudio.Solution.7" />
</appSettings>

Примечание
Если ключ visualStudioProgID отсутствует, BuildIt использует последнюю установленную версию Visual Studio .NET.

Защита BuildIt

Как и в случае любого другого приложения, вы должны защищать все конфиденциальные данные и ресурсы от несанкционированного доступа. При работе с BuildIt нужно рассмотреть два основных вопроса.

Запрещение несанкционированного доступа к файлам конфигурации приложения
Разрешения доступа, необходимые BuildIt

Запрещение несанкционированного доступа к файлам конфигурации приложения
Поскольку в файле конфигурации утилиты содержатся конфиденциальные данные, например имя и пароль пользователя VSS, позаботьтесь о том, чтобы только авторизованные пользователи могли просматривать или изменять эти параметры. Вы можете защитить файл конфигурации с помощью файловых разрешений Windows NTFS.

Разрешения доступа, необходимые BuildIt
BuildIt использует Exception Management Application Block для вывода информации об исключениях в журнал событий. Кроме того, BuildIt читает и записывает файлы. Поэтому участник системы безопасности (security principal), используемый BuildIt, должен обладать разрешением на выполнение этих операций.

Устранение неполадок при работе BuildIt

Разработчикам доступно два механизма устранения неполадок при работе с утилитой сборки: трассировка и обработка исключений. Когда включена трассировка, BuildIt генерирует в рабочей папке файл трассировки BuildIt.log, позволяющий определить, какие операции выполнила утилита. Это полезно, когда нужно выяснить, почему утилита ведет себя не так, как ожидалось.

Если генерируется исключение, BuildIt через Exception Management Application Block выводит информацию об исключениях в журнал приложения. Затем разработчики могут посмотреть в Event Viewer подробную информацию об исключении.

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

Известные проблемы

В большинстве случаев BuildIt работает очень эффективно, но в отдельных ситуациях возникают кое-какие проблемы. В табл. 1 перечислены известные проблемы, связанные с использованием BuildIt.

Табл. 1. Известные проблемы BuildIt

Проектирование и реализация

В этом разделе рассматриваются следующие вопросы проектирования и реализации BuildIt.

Решаемые проблемы
Цели разработки
Описание решения
Усовершенствования

Решаемые проблемы

Приложение BuildIt разработано, чтобы решать следующие проблемы.

• Разработчики теряют время на создание, тестирование и поддержку специализированных сценариев сборки, которые часто невозможно повторно использовать при переходе к новым проектам.
• На разработку отводятся жестко заданные сроки, поэтому не хватает времени на тестирование и документирование сборочных сценариев.

Цели разработки

При разработке BuildIt преследовались следующие цели.

• Решение должно выполнять операции, описанные в документе MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".
• Решение должно быть тщательно документированным, удобным в поддержке и простым в использовании.
• Решение должно быть гибким; нужно предусмотреть возможность настройки без изменения кода и перекомпиляции.
• Решение должно быть надежным; необходима обработка любых исключений, генерируемых в процессе сборки.

Описание решения

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

• BuildInitializer. Проверяет на допустимость аргументы командной строки, считывает параметры средства сборки, обращаясь к классу BuildItSectionHandler, и инициирует сборочный процесс, обращаясь к классу BuildManager.
• BuildItSectionHandler. Считывает из файла конфигурации параметры, влияющие на поведение BuildIt в период выполнения.
• BuildManager. Управляет сборочным процессом.
• SourceSafeHelper. Открывает доступ к операциям VSS (например регистрацию и снятие с учета) в ходе сборочного процесса.
• BuildItResourceManager. Предоставляет доступ (с контролем типов) к сообщениям об ошибках, хранящимся в файле ресурсов.
• BuildItCommandLineArgs. Инкапсулирует аргументы командной строки, поддерживаемые BuildIt.

Логика приложения такова

1. BuildIt запускается с соответствующими аргументами в командной строке.
2. Класс Main1 вызывает метод Start класса BuildInitializer.
3. Класс BuildInitializer проверяет аргументы командной строки и обращается к классу BuildItSectionHandler, считывающему параметры из файла конфигурации утилиты. Класс BuildItSectionHandler возвращает параметры в структуре BuildItSettings, которая обеспечивает контроль типов.
4. Класс BuildInitializer создает экземпляр класса BuildManager, передавая структуру BuildItSettings его конструктору.
5. Затем BuildInitializer вызывает метод Build класса BuildManager, инициируя в зависимости от аргументов командной строки сборку или повторную сборку.

Параметры файла конфигурации

Файл конфигурации BuildIt - BuildIt.exe.config - содержит параметры, считываемые при выполнении. Это позволяет изменять поведение утилиты без ее перекомпиляции.

Параметры в этом файле указывают:

• какие решения собираются;
• информацию, необходимую для подключения к определенной базе данных VSS;
• обновляются ли версии сборок номером сборки;
• архивируются ли ранее собранные сборки в заданном каталоге;
• отправляется ли по электронной почте отчет о результатах сборки и, если да, на какой адрес.
  Примечание
  BuildIt генерирует исключение, когда какой-либо параметр отсутствует или задан некорректно (если только в документе не оговорено обратное).
  В следующем фрагменте кода показан формат параметров, задаваемых в файле конфигурации.

<configuration>
  <configSections>
    <section name="BuildIt"
     type="Sapient.Framework.Tools.BuildIt.BuildItSectionHandler,
     BuildIt"/>
  </configSections>

  <appSettings>
    <add key="appendTraceOutput" value="off" />
    <add key="enableCustomMessageFilter" value="on"/>
    <add key="visualStudioProgID" value="VisualStudio.Solution.7"/>
  </appSettings>

  <buildIt>
    <sourceControl username="username" password="password"
     iniFilePath="c:\Program Files\Microsoft Visual Studio\VSS\srcsafe.ini"
     srcVSSRootFolder="$/System" srcFileRootFolder="c:\System"/>

    <solutions latestRootFolderFullName="c:\System"
     buildNumberFilePath="c:\System\BuildNumber.xml">
      <solution path=" c:\System\Solution1\Solution1.sln"/>
      <solution path=" c:\System\Solution2\Solution2.sln"/>
    </solutions>

    <options>
      <sendBuildReport mode="on/off" smtpServer="255.255.255.255"
       toAddress="you@yourcompany.com"/>
      <archiveBuild mode="on/off"
        archiveRootFolderFullName="c:\System\Archive">
        <additionalFoldersToArchive>
          <folder fullName="c:\System\Solution1\Setup1\Debug"
           destFolderName="Debug\Setup1" />
          <folder fullName=" c:\System\Solution1\Setup1\Release"
           destFolderName="Release\Setup1" />
        </additionalFoldersToArchive>
      </archiveBuild>
      <updateAssemblyVersion mode="on/off"
       vbAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.vb"
       csAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.cs"/>
    </options>
  </buildIt>
</configuration>

Элемент configSections
Элемент configSections используется, чтобы связать раздел файла конфигурации с конкретным классом, обрабатывающим такие разделы. В показанном выше фрагменте кода элемент section используется, чтобы связать раздел BuildIt с классом BuildItSectionHandler из пространства имен Sapient.Framework.Tools.BuildIt.

Элемент appSettings
Элемент appSettings содержит параметры, специфичные для приложения и допускающие представление в виде пар "ключ-значение". В настоящее время в BuildIt определено три таких параметра.

• appendTraceOutput. Когда этот ключ имеет значение on, BuildIt добавляет вывод трассировки в файл трассировки BuiltIt.log.
  Примечание
  Если этого ключа нет или если его значение не равно on, BuildIt перезаписывает файл трассировки.
• enableCustomMessageFilter. Когда этот ключ имеет значение on, BuildIt устанавливает специальный фильтр сообщений, обрабатывающий исходящие COM-сообщения во время ожидания ответа на синхронные вызовы. Реализация этого фильтра повторяет отклоненные вызовы Automation-объектов Visual Studio .NET, если эти объекты заняты. Если они заняты, а фильтр не активен, генерируется исключение.
  Примечание
  Если этого ключа нет или если его значение отлично от on, BuildIt не активизирует фильтр сообщений.
   
• visualStudioProgID. Если этот ключ имеет значение progID, BuiltIt при сборке решения использует заданную версию Visual Studio .NET.
  Примечание
  Если этого ключа нет, BuildIt использует самую последнюю версию Visual Studio .NET из установленных.

Элемент sourceControl
Элемент sourceControl содержит информацию о базе данных VSS, используемой сборочным процессом. У этого элемента имеются следующие атрибуты:

• username. Имя пользователя VSS, указываемое при входе в базу данных.
• password. Пароль пользователя VSS.
• iniFilePath. Путь к .ini-файлу VSS, используемый при определении местонахождения базы данных (например C:\Program Files\Microsoft Visual Studio\VSS\srcsafe.ini).
• srcVSSRootFolder. Корневая папка VSS, содержащая собираемый исходный код (например $/System). BuildIt выполняет рекурсивную операцию Get из этого VSS-проекта.
• srcFileRootFolder. Корневая папка файловой системы, содержащая собираемый исходный код (например C:\System). BuildIt при выполнении рекурсивной операции Get копирует файл в этот каталог.

Элемент solutions
Элемент solutions содержит информацию о собираемых решениях. У этого элемента имеются следующие атрибуты:

• latestRootFolderFullName. Имя корневой папки, содержащей по завершении сборки последние версии сгенерированных сборок (например C:\System). Дополнительную информацию см. в разделе "Копирование результатов в папку Latest" документа MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".
  Примечание
  В документе "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe" утверждается, что "в системах на основе одного решения или одного решения, разбитого на части, папка Latest не нужна, так как используются ссылки на проекты, а не указывающие на сборки ссылки на файлы". Однако, поскольку ничто не мешает системе на основе одного решения превратиться в систему на основе нескольких решений, BuildIt всегда копирует результаты сборки в папку последних версий. Благодаря этому разработчики могут использовать файловые ссылки при обращении к сборкам, сгенерированным для другого решения.
• buildNumberFilePath. XML-файл, используемый для генерации следующего номера сборки (например C:\System\BuildNumber.xml). Дополнительную информацию см. в разделе "Генерация номеров версий сборок" в документе MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".
  Примечание
  В документе "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe" не предлагается обязательно использовать какой-либо определенный способ генерации номеров версий сборок. BuildIt решает эту задачу, по окончании каждой успешной сборки увеличивая номер сборки, хранящийся в заданном XML-файле. Сборка считается успешной, если при ее выполнении не было никаких ошибок.

Элемент solution
Элемент solution содержит информацию об определенном решении. У этого элемента единственный атрибут.

• path. Файл собираемого решения (например C:\System\Solution1\Solution1.sln).

Элемент options
Элемент options содержит дочерние элементы, задающие различные параметры сборки. Для каждого параметра сборки имеется свой элемент.

Элемент sendBuildReport
Элемент sendBuildReport задает, отправляется ли по окончании сборки отчет о ней и, если да, на какой электронный адрес. Дополнительную информацию см. в разделе "Рассылка по электронной почте информации о сборке" в документе MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".

В этом элементе содержатся следующие атрибуты:

• mode. Если имеет значение "on", BuildIt отправляет отчет о сборке на заданный адрес.
• smtpServer. IP-адрес SMTP-сервера, используемого для переадресации сообщения.
• toAddress. Адрес, на который отправляется отчет о сборке.

Элемент archive Build
Элемент archiveBuild задает, архивируются ли генерируемые сборки, в папку, имя которой соответствует номеру сборки. Дополнительную информацию см. в разделе "Хранение предыдущих версий" документа MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".

В этом элементе содержатся следующие атрибуты.

• mode. Если имеет значение "on", BuildIt копирует сгенерированные сборки в папку, имя которой соответствует номеру сборки.
• archiveRootFolderFullName. Имя корневой папки, в которой содержатся архивированные предыдущие версии сборок (например C:\System\Archive).

  Элемент additionalFoldersToArchive
  По умолчанию BuildIt архивирует только результаты сборки проектов на Visual C# и Visual Basic .NET. Чтобы архивировать результаты сборки других проектов, например установочных проектов Visual Studio .NET, добавьте элементы folder в элемент additionalFoldersToArchive.

  В элементе folder содержатся следующие атрибуты.

• fullName. Полное имя архивируемой исходной папки (например C:\System\Solution1\Setup1\Debug).
• destFolderName. Имя папки, в которую выполняется архивация (например Debug\Setup1).
  Примечание
  Если установлен параметр archiveBuild, BuildIt копирует файлы из каждой заданной исходной папки в указанную папку назначения, находящуюся внутри корневой архивной папки.

Элемент updateAssemblyVersion
Элемент updateAssemblyVersion задает, обновляются ли номера версий генерируемых сборок в соответствии с номером сборки. Дополнительную информацию см. в разделе "Управление версиями сборок" документа MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".

У этого элемента есть такие атрибуты.

• mode. Если имеет значение "on", то вместе с номером сборки генерируются и версии сборок.
• vbAssemblyVersionVSSPath. Путь VSS к файлу версии сборки, совместно используемому всеми собираемыми проектами на Visual Basic .NET (например $/System/AssemblyVersionInfo.vb). Если в вашем решении нет проектов на Visual Basic, оставьте значение этого атрибута пустым. Дополнительную информацию см. в разделе "Централизованное формирование номеров версий сборок" документа MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".
• csAssemblyVersionVSSPath. Путь VSS к файлу версии сборки, совместно используемому всеми собираемыми проектами на Visual C# (например $/System/AssemblyVersionInfo.cs). Если в вашем решении нет проектов на Visual C#, оставьте значение этого атрибута пустым. Дополнительную информацию см. в разделе "Централизованное формирование номеров версий сборок" документа MSDN Library "Групповая разработка в среде Visual Studio .NET и Visual SourceSafe".

Усовершенствования

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

• Определить интерфейс, позволяющий BuildIt взаимодействовать не только с Visual SourceSafe, но и с другими средствами контроля исходных файлов (например ISourceControlProvider). Тогда разработчики смогли бы настроить BuildIt на работу с другой системой контроля исходных файлов, например с Rational ClearCase.
• Упростить настройку BuildIt, реализовав поведение по умолчанию в случае отсутствия какого-либо параметра. Сейчас BuildIt генерирует ошибку, если какого-то параметра нет в файле конфигурации. Лучше было бы разработать более "прощающую" версию BuildIt, которая при отсутствии параметра принимала бы его значение по умолчанию.
• Еще больше упростить настройку BuildIt, перейдя к использованию относительных путей вместо полных. В настоящее время все пути к файлам должны быть полностью определенными. Такие пути гибче относительных, но слишком громоздки. Удобнее было бы задавать отдельные пути относительно начальной корневой папки (например для файлов решений, XML-файла с номером сборки и т. д.).
• Дать возможность разработчикам задавать неограниченное количество файлов версии сборки в параметре updateAssemblyVersion. Сейчас BuildIt позволяет указать один файл версии сборки для Visual C# и один для - для Visual Basic .NET. Это ограничение основано на предположении, что разработчики совместно используют в VSS один файл на Visual C# с информацией о версии сборки для всех проектов на Visual C# и один такой файл на Visual Basic .NET во всех проектах на Visual Basic .NET. Но разработчики могут предпочесть обновлять файлы с номерами версий по отдельности, не обращаясь к общим файлам VSS.
• Определить событие "после сборки" ("post-build" event), которое можно использовать для расширения сборочного процесса. В данный момент единственный способ расширить сборочный процесс - изменить исходный код BuildIt. Более гибким подходом было бы реализовать событие, генерируемое по окончании сборки. Тогда разработчики могли бы связывать с этим событием обработчики, выполняющие нестандартные операции. Такая стратегия позволила бы настраивать и другие части сборочного процесса (например до сборки, во время сборки и после сборки).
• Разрешить задавать имя файла конфигурации BuildIt. В настоящее время BuildIt ищет параметры конфигурации в стандартном файле конфигурации - BuildIt.exe.config. Поэтому применять BuildIt для сборки двух решений одновременно нельзя. Вместо этого разработчикам приходится копировать сборки BuildIt в другой каталог. Более "дружественным" решением было бы позволить разработчикам указывать в командной строке имя файла конфигурации, отличное от имени стандартного файла.
• Сделать так, чтобы BuildIt автоматически создавала виртуальный каталог для любого Web-проекта, которому он еще не сопоставлен. Сейчас Visual Studio .NET предлагает указать местонахождение рабочей копии Web-проекта, если ее еще нет. Вместо этого BuildIt могла бы просто автоматически создавать виртуальный каталог.

Описание классов

В этом разделе содержится информация о следующих классах:

BuildInitializer

Класс BuildInitializer проверяет на допустимость параметры командной строки, считывает параметры утилиты сборки, обращаясь к классу BuildItSectionHandler, и инициирует сборочный процесс, обращаясь к классу BuildManager.

Комментарии
Класс BuildInitializer реализует один public-метод Start, вызываемый static/shared-методом Main консольного приложения. Сначала метод Start проверяет на допустимость все аргументы командной строки, вызывая private-метод AreCommandLineArgsValid. Если аргументы допустимы, BuildInitializer считывает параметры утилиты через класс BuildItSectionHandler. Наконец, BuildInitializer инициирует процесс сборки, вызывая метод Build класса BuildManager.

BuildItSectionHandler

Класс BuildItSectionHandler заполняет структуру BuildItSettings данными, прочитанными из файла конфигурации средства сборки, и возвращает ее.

Комментарии
Класс BuildItSectionHandler, реализующий интерфейс IConfigurationSectionHandler, анализирует параметры конфигурации, заданные в элементе BuildIt файла конфигурации утилиты сборки. Этот класс загружает информацию из элемента BuildIt в структуру BuildItSettings.

В структуре BuildItSettings определено несколько свойств, предоставляющих доступ (с контролем типов) к параметрам конфигурации, определенным в файле конфигурации. Например, в структуре BuildItSettings три свойства, возвращающие различные параметры сборки системы: OptionSendBuildReport, OptionArchiveBuild и OptionUpdateAssemblyVersion. Кроме того, в структуре BuildItSettings определены свойства Solutions и SourceControlInfo, содержащие информацию из соответствующих элементов файла конфигурации.

BuildManager

Класс BuildManager управляет сборочным процессом.

Комментарии
Класс BuildManager используется классом BuildInitializer и координирует сборочный процесс. Конструктор BuildManager принимает два параметра: типа BuildItSettings и типа BuildItResourceManager. После создания экземпляра класса BuildManager закрытые члены этого класса инициализируются параметрами, передаваемыми в конструкторе. Благодаря этому при выполнении сборочного процесса классу BuildManager доступны параметры приложения и сообщения об ошибках.

Кроме того, у BuildManager есть единственный открытый метод Build, принимающий перечислимое BuildType. Этот параметр задает, какой тип сборки выполняется - Build или Rebuild. Перечислимое BuildType имеет следующий вид.

[C#]
public enum BuildType {Build, Rebuild};

Rebuild - это сборка системы, выполняемая после устранения проблем, возникших в процессе предыдущей сборки. Сборка Rebuild отличается от Build отсутствием некоторых действий. Например, при выполнении Build BuildManager создает в VSS новые метки, а при выполнении Rebuild - нет.

После определения BuildType, класс BuildManager вызывает несколько закрытых методов, выполняющих различные этапы сборочного процесса.

SourceSafeHelper

Класс SourceSafeHelper - это оболочка Automation-объекта VSS, облегчающая взаимодействие с VSS.

Комментарии
Класс SourceSafeHelper используется BuildManager для взаимодействия с VSS при выполнении сборочного процесса. Он содержит несколько открытых методов, таких как Checkin и Checkout, которые скрывают детали реализации от классов, работающих с Automation-объектами VSS. Примечание
Класс SourceSafeHelper не содержит методы для всех операций VSS. Он обеспечивает доступ только к операциям, используемым утилитой сборки.

BuildItResourceManager

Класс BuildItResourceManager предоставляет доступ (с контролем типов) к сообщениям об ошибках, хранящимся в файле ресурсов.

Комментарии
Класс BuildItResourceManager, производный от класса ResourceManager из пространства имен System.Resources, используется, чтобы считывать сообщения об ошибках из файла ресурсов, содержащегося в BuildIt.exe. Он предоставляет несколько открытых методов, например метод GetBuildSolutionFailedString, который обеспечивает доступ (с контролем типов) к значениям ресурсов. Благодаря этому можно избавиться от ошибок, возникающих, если при вызове ResourceManager.GetString(string name) указывается неправильное имя ресурса.

BuildItCommandLineArgs

Класс BuildItCommandLineArgs инкапсулирует набор аргументов командной строки, поддерживаемых утилитой.

Комментарии
Класс BuildItCommandLineArgs, производный от класса StringCollection из пространства имен System.Collections.Specialized, представляет аргументы командной строки, поддерживаемые BuildIt. Он используется классом BuildInitializer, чтобы определять, допустимы ли аргументы командной строки.

Часто задаваемые вопросы

Имею ли я право изменять исходный код BuildIt?
Да, вы имеете право изменять и расширять исходный код BuildIt. Например, вы можете модифицировать вызовы, специфичные для Visual Source Safe, и разработать вспомогательный класс, работающий с вашей системой контроля исходных файлов. Пожалуйста, сообщите нам о внесенных вами изменениях. Адреса, по которым вы можете поделиться с нами своим опытом, даны ниже.

Надо ли устанавливать Visual Studio на компьютере, на котором запускается BuildIt?
Да, Visual Studio должен быть установлен на сервере или рабочей станции, где вы собираете системы с помощью BuildIt. Установки одних лишь компонентов .NET Framework, распространяемых с приложениями, недостаточно.

Резюме

В этом документе описана утилита BuildIt. При ее разработке мы стремились добиться простоты и расширяемости, чтобы вы могли легко адаптировать ее к своему процессу сборки. Пожалуйста, поделитесь своим мнением о BuildIt по адресам, указанным в разделе "Обратная связь".

Об авторе

Майкл Монтейро (Michael Monteiro) - консультант по технологиям в Sapient Corporation и .NET Microsoft Certified Professional с более чем восьмилетним опытом работы. Сейчас работает в группе, руководящей техническими подразделениями Sapient по архитектурным аспектам. С ним можно связаться по адресу mmonte@sapient.com.

Информация о компании Sapient

Sapient - одна из ведущих компаний, занимающихся консалтингом в области бизнеса и технологий, - помогает клиентам из списка "Global 2000" добиваться достойных результатов за счет быстрой разработки приложений и поддержки передовых технологий при фиксированных затратах. Компания Sapient основана в 1991 г., в ней работают более 1500 сотрудников. Офисы компании расположены в Атланте, Кембридже (штат Массачусетс), Чикаго, Далласе, Дюссельдорфе, Лондоне, Лос-Анджелесе, Милане, Мюнхене, Нью-Дели, Нью-Йорке, Сан-Франциско и Вашингтоне. Дополнительную информацию о Sapient можно найти на сайте www.sapient.com.

Благодарности

Выражаю огромную благодарность следующим сотрудникам и рецензентам: Bernard Chen (Sapient Corporation), Brett Keown, Craig Skibo, David Lewis, Deyan Lazarov, Dimitris Georgakopoulos (Sapient Corporation), Edward Jezierski, Filiberto Selvas Patino, Jeff Pflum, Joe Hom (Avanade), Ken Hardy, Kenny Jones, Korby Parnell, Martin Born, Mick Das, Mike Pietraszak, Niel Sutton, Oded Ye Shekel, Rajiv Sodhi (Sapient Corporation), Ray Escamilla, Rich Knox, Russell Christopher и Sumit Sharma (Sapient Corporation).

Обратная связь

Вопросы, предложения или замечания, пожалуйста, направляйте разработчикам BuildIt по адресу buildit@sapient.com.

Если вы хотите связаться с Microsoft, пишите по адресу devfdbck@microsoft.com.