Расширение процесса сборки с помощью MSBuild

В данной статье речь пойдет о том, как расширить процесс сборки проекта с помощью MSBuild.

Меню

• Основные понятия — что такое target и task в MSBuild
• Жизненный цикл сборки MSBuild — какая последовательность вызова таргетов
• Подготовка окружения для примеров
• Таргеты в MSBuild — пример использования некоторых таргетов MSBuild
• Создание собственного таргета MSBuild
• Таски в MSBuild — пример использования некоторых тасков MSBuild
• Переменные и макросы в .csproj
• Ссылки

Основные понятия (Меню)

MSBuild устроен таким образом, что сборка проекта разбита на несколько этапов.

Target — это некоторый этап (событие), происходящее во время сборки проекта. Можно использовать стандартные таргеты, либо определять собственные.

Task — это некоторая задача, которая может выполняться на определенном этапе. Можно использовать стандартные таски или создавать собственные.

Цитата из документации о таргетах (https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-targets):

Targets group tasks together in a particular order and allow the build process to be factored into smaller units.
For example, one target may delete all files in the output directory to prepare for the build, while another
compiles the inputs for the project and places them in the empty directory.

Жизненный цикл сборки MSBuild (Меню)

Для работы MSBuild Microsoft определил ряд стандартных таргетов (в файлах Microsoft.Common.targets, Microsoft.CSharp.targets и т.д.). Довольно тяжело найти информацию о том, какие таргеты уже определены, но опытным путём было выявлено, что есть следующие (упорядочены, могут быть указаны не все):

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

Подготовка окружения для примеров (Меню)

Для примеров необходимо:

• Установленная среда разработки Visual Studio
• Создать проект типа Console Application с именем MSBuildExample
• Открыть папку проекта и найти там файл MSBuildExample.csproj
• Открыть файл MSBuildExample.csproj в блокноте или другом редакторе

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

Внимание! В файле .csproj регистр букв важен.
Для запуска примера необходимо запускать build в среде разработки Visual Studio. Для некоторых примеров потребуется выбирать solution конфигурацию.

Результат будет выводиться в окно Output в Visual Studio (внизу). Если его нет, то откройте его через пункты меню View => Output.

Таргеты в MSBuild (Меню)

Для примеров будем использовать таск Message, который будет выводить информацию в окно Output в Visual Studio. Как говорилось ранее есть стандартные таргеты BeforeBuild и AfterBuild, воспользуемся ими. Про подготовку читать в разделе Подготовка окружения для примеров.

<Target Name="AfterBuild">
  <Message Text="AfterBuild event" Importance="high"></Message>
</Target>
<Target Name="BeforeBuild">
  <Message Text="BeforeBuild event" Importance="high"></Message>
</Target>

Как видно, был выполнен task Message, который вывел указанный нами текст в момент BeforeBuild и AfterBuild в окно Output в Visual Studio.
При определении таргета с одним и тем же именем он перезаписывается!

<Target Name="BeforeBuild">
  <Message Text="First message" Importance="high"></Message>
</Target>
<Target Name="BeforeBuild">
  <Message Text="Second message" Importance="high"></Message>
</Target>

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

Создание собственного таргета MSBuild (Меню)

Если таргетов BeforeBuild и AfterBuild недостаточно или нужно, чтобы таски выполнялись на другом этапе жизненного цикла сборки, то можно определить собственный таргет. Для этих целей есть параметры BeforeTargets и AfterTargets.

 <Target Name="BeforeBuild">
    <Message Text="BeforeBuild event" Importance="high"></Message>
  </Target>
  <Target Name="MyCustomBeforeTarget" BeforeTargets="BeforeBuild">
    <Message Text="MyCustomBeforeTarget event" Importance="high"></Message>
  </Target>
  <Target Name="MyCustomAfterTarget" AfterTargets="BeforeBuild">
    <Message Text="MyCustomAfterTarget event" Importance="high"></Message>
  </Target>

Было определено два собственных таргета — MyCustomBeforeTarget и MyCustomAfterTarget.
Таргет MyCustomBeforeTarget выполняется до таргета BeforeBuild, потому что мы указали:

BeforeTargets="BeforeBuild"

Таргет MyCustomAfterTarget выполняется после таргета BeforeBuild, потому что мы указали:

AfterTargets="BeforeBuild"

Таски в MSBuild (Меню)

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

Рассмотрим несколько примеров использования тасков и макросов.

<Target Name="BeforeBuild">
    <Message Text="Current configuration is Debug" Condition="'$(Configuration)' == 'Debug'" Importance="high"></Message>
    <Message Text="Current configuration is Release" Condition="'$(Configuration)' == 'Release'" Importance="high"></Message>
</Target>

<PropertyGroup>
    <MessageText>Current configuration is $(Configuration)</MessageText>
  </PropertyGroup>
 
  <Target Name="BeforeBuild">
    <Message Text="$(MessageText)" Condition="'$(Configuration)' == 'Debug'" Importance="high"></Message>
    <Message Text="$(MessageText)" Condition="'$(Configuration)' == 'Release'" Importance="high"></Message>
  </Target>

<Target Name="BeforeBuild">
  <Error Condition="!Exists('App.Debug.config')" Text="File App.Debug.config not found"></Error>
</Target>

<Target Name="BeforeBuild">
    <Copy SourceFiles="App.config;App.config" DestinationFiles="$(OutputPath)/Test/App.config;$(OutputPath)/Test/App.test.config"></Copy>
</Target>

Переменные и макросы в .csproj (Меню)

В файле .csproj можно использовать ряд стандартных макросов, их список можно найти здесь https://msdn.microsoft.com/en-us/library/c02as0cs.aspx и здесь https://msdn.microsoft.com/en-us/library/bb629394.aspx. Рассмотрим некоторые полезные макросы:

• $(MSBuildToolsPath) — указывает на путь к папке MSBuild. Например, C:Program Files (x86)MSBuild14.0Bin. Данный макрос при комбинировании пути использовать со слешем. Например, $(MSBuildToolsPath)Microsoft.Web.Publishing.Tasks.dll. Иначе он может некорректно формировать путь и выдавать ошибку, что файл не найден.
• $(OutputPath) — относительный путь к выходной папке. Например, binStage. Данный макрос использовать со слешем, например, $(OutputPath)$(TargetFileName).config.
• $(TargetFileName) — имя выходного файла вместе с расширением. Например, MSBuildExample.exe. Расширение и формат имени выходного файла может отличаться от различных типов проектов. С помощью этого макроса можно безопасно определить какое будет имя у файла конфига. Может быть полезно для трасформаций конфигов.
• $(Configuration) — имя текущей конфигурации. Например, Release, Debug
• $(IntermediateOutputPath) — путь к папке obj. Например, objStage.

Для определения собственных параметров использовать PropertyGroup . Пример определения собственной переменной можно найти в разделе таски в MSBuild.

Ссылки (Меню)

• документация по таргетам
• документация по таскам
• список тасков, предоставляемых Microsoft
• условия
• информация о макросах
• информация о переменных
• информация о процессе билда
• порядок выполнения таргетов
• информация о таргет файлах
• еще немного информации о таргетах и процессе билда. Там же ссылки на серию статей про трансформации

Автор: Алексей

Источник