Поделиться через

Пошаговое руководство. Использование MSBuild

  • Статья

MSBuild — это платформа построения для Microsoft и Visual Studio. В этом пошаговом руководстве представлено описание стандартных блоков MSBuild и способы создания, управления и отладки проектов MSBuild. Ниже описываются следующие вопросы:

  • Создание и управление файлом проекта.

  • Способы использования свойств построения.

  • Способы использования элементов построения.

MSBuild можно запустить из Visual Studio или из командного окна. В этом пошаговом руководстве показано создание файла проекта MSBuild с помощью Visual Studio. Файл проекта можно редактировать в Visual Studio, а в командном окне можно построить проект и проанализировать результаты построения.

Создание проекта MSBuild

Система проектов Visual Studio основана на MSBuild. Благодаря ей упрощается создание нового файла проекта с помощью Visual Studio. В этом разделе описывается создание файла проекта Visual C#. Вместо него можно создать файл проекта Visual Basic. В рамках этого руководства различия между двумя файлами проекта незначительны.

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

  1. Запустите Visual Studio.

  2. В меню Файл последовательно выберите пункты Создать и Проект.

  3. В диалоговом окне Новый проект выберите тип проекта Visual C# и щелкните шаблон Приложение Windows Forms. В поле Имя введите BuildApp. Для решения укажите Расположение, например D:\. Примите значение по умолчанию для поля Создать каталог для решения (флажок установлен), диалоговое окно Добавить в систему управления версиями пустое, и Имя решения задано как BuildApp.

    Щелкните ОК, чтобы создать файл проекта.

Анализ файла проекта

В предыдущем разделе файл проекта Visual C# создавался с помощью Visual Studio. Файл проекта представлен в обозревателе решений узлом проекта под названием BuildApp. Чтобы проанализировать файл проекта, можно использовать редактор кода Visual Studio.

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

  1. В обозревателе решений щелкните узел проекта BuildApp.

  2. Обратите внимание, что в обозревателе Свойства свойство Файл проекта задано как BuildApp.csproj. К имени всех файлов проекта добавляется суффикс "proj". Если создается проект Visual Basic, имя файла проекта будет BuildApp.vbproj.

  3. Щелкните правой кнопкой мыши узел проекта, а затем Отменить загрузку проекта.

  4. Еще раз щелкните правой кнопкой мыши узел проекта и выберите Изменить BuildApp.csproj.

    Файл проекта откроется в редакторе кода.

целевые объекты и задачи

Файлы проекта представляют собой файлы в формате XML с корневым узлом Project (Проект).

<?xml version="1.0" encoding="utf-8"?>

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

В элементе Project следует указать пространство имен xmlns.

Построение и создание приложения осуществляются с помощью элементов Target (целевой объект) и Task (Задача).

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

  • целевой объект представляет собой именованную последовательность задач. В конце файла проекта находятся два целевых объекта, которые в этом случае заключены в комментарии HTML: BeforeBuild и AfterBuild.

    <Target Name="BeforeBuild">

    </Target>

    <Target Name="AfterBuild">

    </Target>

    Дополнительные сведения см. в разделе Цели MSBuild.

У узла Project имеется необязательный атрибут DefaultTargets, выбирающий целевой объект, который строится по умолчанию, в этом случае Build (Построение).

<Project ToolsVersion="4.0" DefaultTargets="Build" ...

целевой объект Build не определен в файле проекта. Вместо этого он импортируется из файла Microsoft.CSharp.targets с помощью элемента Import (Импорт).

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Импортированные файлы эффективно вставляются в файл проекта, если на них имеется ссылка.

MSBuild отслеживает целевые объекты построения и гарантирует, что каждый целевой объект будет построен не более одного раза.

Добавление целевого объекта и задачи

Добавьте целевой объект в файл проекта. Добавьте задачу в целевой объект, который выводит сообщение.

Чтобы добавить целевой объект и задачу

  1. Добавьте эти строки в файл проекта непосредственно после оператора Import:

    <Target Name="HelloWorld">
</Target>

    При этом будет создан целевой объект под названием HelloWorld (Здравствуй, мир!). Следует обратить внимание на наличие поддержки Intellisense во время редактирования файла проекта.

  2. Добавьте строки к целевому объекту HelloWorld, чтобы в результате раздел выглядел следующим образом:

    <Target Name="HelloWorld">
  <Message Text="Hello"></Message>
  <Message Text="World"></Message>
</Target>

  3. Сохраните файл проекта.

Задача Message (Сообщение) является одной из многих задач, поставляемых с MSBuild. Полный список доступных задач и информацию об их использовании см. в разделе Справочные сведения о задачах MSBuild.

Задача Message принимает строковое значение атрибута Text (Текст) в качестве входного и отображает его в устройстве вывода. целевой объект HelloWorld дважды выполняет задачу Message: сначала отображает сообщение "Hello", а затем — "World".

Построение целевого объекта

Запустите MSBuild из командной сроки Visual Studio, чтобы построить целевой объект HelloWorld, определенный выше. Используйте параметр команды /target или /t, чтобы выбрать целевой объект.

Примечание

В следующих разделах под командным окном мы будем подразумевать командное окно Visual Studio.

Чтобы построить целевой объект

  1. Нажмите кнопку Пуск и щелкните Все программы. Найдите и щелкните Командная строка Visual Studio в папке Набор средств Visual Studio.

  2. В командном окне перейдите в папку с файлом проекта, в этом случае — D:\BuildApp\BuildApp.

  3. Запустите msbuild с параметром /t:HelloWorld. При этом будет выбран и построен целевой объект HelloWorld:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте выходные данные в командном окне. Должны отображаться две строки "Hello" и "World":

    Hello

    World

Примечание

Если вместо них отображается The target "HelloWorld" does not exist in the project , возможно, файл проекта не был сохранен в редакторе кода.Сохраните файл и повторите попытку.

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

Примечание

Если запустить команду msbuild без параметра /t, она построит целевой объект, предоставленный атрибутом DefaultTarget элемента Project, в этом случае "Build".При этом выполняется построение приложения Windows Forms BuildApp.exe.

Свойства построения

Свойства построения — это пары "имя-значение", управляющие построением. В начале файла проекта уже определены некоторые свойства построения:

<PropertyGroup>

...

<ProductVersion>10.0.11107</ProductVersion>

<SchemaVersion>2.0</SchemaVersion>

<ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>

<OutputType>WinExe</OutputType>

...

</PropertyGroup>

Все свойства являются дочерними элементами PropertyGroup. Имя свойства представляет собой имя дочернего элемента, а значение свойства — это текстовый элемент дочернего элемента. Например:

<TargetFrameworkVersion>v4.0</TargetFrameworkVersion>

определяет свойство под названием TargetFrameworkVersion, присваивая ему строковое значение "v4.0".

Свойства построения можно переопределить в любое время. If

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

далее в файле проекта или в файле, позже импортированном в файл проекта, TargetFrameworkVersion принимает новое значение "v3.5".

Анализ значения свойства

Чтобы проанализировать значение свойства, следует использовать следующий синтаксис, где PropertyName — это имя свойства:

$(PropertyName)

С помощью этого синтаксиса проанализируйте некоторые свойства в файле проекта.

Чтобы проанализировать значение свойства

  1. В редакторе кода замените целевой объект HelloWorld следующим кодом:

    <Target Name="HelloWorld">
  <Message Text="Configuration is $(Configuration)" />
  <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
</Target>

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должны отображаться следующие две строки (версия .NET Framework может быть другой):

    Configuration is Debug

    MSBuildToolsPath is C:\Windows\Microsoft.NET\Framework\v4.0.20317

Примечание

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

Условные свойства

Многие свойства, например Configuration (Конфигурация), задаются условно, т.е. атрибут Condition (Условие) появляется в элементе свойства. Условные свойства определяются или переопределяются, только если условие — true. Следует обратить внимание, что неопределенным свойствам по умолчанию присваивается значение пустой строки. Например:

<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

означает: "Если свойство Configuration еще не определено, определите его и присвойте значение "Debug".

Практически у всех элементов MSBuild может быть атрибут Condition. Дополнительные сведения об использовании атрибута Condition см. в разделе Условия MSBuild.

Зарезервированные свойства

В MSBuild некоторые имена свойств резервируются для сохранения информации о файле проекта и двоичных файлах MSBuild. MSBuildToolsPath является примером зарезервированного свойства (новая возможность в MSBuild 3.5). В ссылках на зарезервированные свойства используется обозначение $, как и для любых других свойств. Дополнительные сведения см. в разделах Практическое руководство. Использование ссылки на имя или расположение файла проекта и Зарезервированные свойства MSBuild.

Переменные среды

Ссылки на переменные среды в файлах проектов выполняются так же, как ссылки на свойства построения. Например, чтобы использовать переменную среды в файле проекта, укажите $(Path). Если в файле проекта содержится определение свойства, имя которого совпадает с переменной среды, свойство из файла проекта переопределяет значение переменной среды. Дополнительные сведения см. в разделе Практическое руководство. Использование переменных среды в построении.

Задание свойств из командной строки

Свойства можно определять из командной строки с помощью параметра /property или /p. Значения свойств, полученные из командной строки, переопределяют значения свойств, заданные в файле проекта и переменных среды.

Чтобы задать значение свойства из командной строки

  1. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld /p:Configuration=Release

  2. Проанализируйте результат. Должна отобразиться следующая строка:

    Configuration is Release.

MSBuild создает свойство Configuration и присваивает ему значение "Release".

Специальные символы

Некоторые знаки имеют специальное значение в файлах проекта MSBuild. Примерами таких знаков являются точка с запятой (;) и звездочка (*). Чтобы использовать эти специальные знаки в качестве литералов в файле проекта, их необходимо задать, используя синтаксис %xx, где xx представляет собой шестнадцатеричное ASCII-значение этого символа.

Измените задачу Message, чтобы отобразить значение свойства Configuration со специальными знаками для удобства чтения.

Чтобы использовать специальные знаки в задаче Message

  1. В редакторе кода замените задачи Message следующей строкой:

    <Message Text="%24(Configuration) is %22$(Configuration)%22" />

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должна отобразиться следующая строка:

    $(Configuration) is "Debug"

Дополнительные сведения см. в разделе Специальные знаки в MSBuild.

Элементы построения

Элемент представляет собой данные, как правило, имя файла, используемые в качестве входных данных для системы построения. Например, коллекцию элементов, представляющую исходные файлы, можно передать задаче под названием Compile (Компилировать), чтобы скомпилировать эти элементы в сборку.

Все элементы являются дочерними элементами ItemGroup. Имя элемента представляет собой имя дочернего элемента, а значение элемента — это значение атрибута Include (Включить) дочернего элемента. Значения элементов с одинаковым именем собираются в типы элементов с этим именем. Например:

<ItemGroup>

<Compile Include="Program.cs" />

<Compile Include="Properties\AssemblyInfo.cs" />

</ItemGroup>

определяет группу элементов с двумя элементами. Тип элемента Compile имеет два значения: "Program.cs" и "Properties\AssemblyInfo.cs".

С помощью следующего кода тот же тип элементов создается посредством объявления обоих файлов (разделенных точкой с запятой) в одном атрибуте Include.

<ItemGroup>

<Compile Include="Program.cs;Properties\AssemblyInfo.cs" />

</ItemGroup>

Дополнительные сведения см. в разделе Элементы MSBuild.

Примечание

Пути к файлам относительны папки с файлом проекта MSBuild.

Анализ значений типа элементов

Чтобы получить значения типа элементов, следует использовать следующий синтаксис, где ItemType — это имя типа элементов:

@(ItemType)

С помощью этого синтаксиса проанализируйте тип элемента Compile в файле проекта.

Чтобы проанализировать значения типа элементов

  1. В редакторе кода замените задачу HelloWorld следующим кодом:

    <Target Name="HelloWorld">
  <Message Text="Compile item type contains @(Compile)" />
</Target>

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должна отобразиться следующая длинная строка:

    Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs

По умолчанию значения типа элементов отделяются точкой с запятой.

Чтобы изменить разделитель типа элементов, следует использовать следующий синтаксис, где ItemType — это тип элемента, а Separator — это строка из одного или нескольких разделительных знаков:

@(ItemType, Separator)

Измените задачу Message, чтобы для отображения элементов Compile по одному в строке использовались символы возврата каретки и перевода строки (%0A%0D).

Чтобы отобразить значения типа элементов по одному в строке

  1. В редакторе кода замените задачу Message следующей строкой:

    <Message Text="Compile item type contains @(Compile, '%0A%0D')" />

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должны отобразиться следующие строки:

    Compile item type contains Form1.cs

    Form1.Designer.cs

    Program.cs

    Properties\AssemblyInfo.cs

    Properties\Resources.Designer.cs

    Properties\Settings.Designer.cs

Атрибуты Include и Exclude и подстановочные знаки

Для добавления элементов в тип элемента можно использовать подстановочные знаки "*", "**" и "?" с атрибутом Include. Например:

<Photos Include="images\*.jpeg" />

добавляет все файлы с расширением JPEG в папке изображений в тип элементов Photos (Фотографии), а

<Photos Include="images\**.jpeg" />

добавляет все файлы с расширением JPEG в папке изображений и всех ее подпапках в тип элементов Photos. Дополнительные примеры см. в разделе Практическое руководство. Выбор файлов для построения.

Следует обратить внимание, что поскольку элементы объявлены, они добавляются в тип элементов. Например:

<Photos Include="images\*.jpeg" />

<Photos Include="images\*.gif" />

создает тип элемента под названием Photo (Фотография), содержащий все файлы в папке изображений с расширением JPEG или GIF. Этот код аналогичен следующей строке:

<Photos Include="images\*.jpeg;images\*.gif" />

С помощью атрибута Exclude (Исключить) можно исключить элемент из типа элементов. Например:

<Compile Include="*.cs" Exclude="*Designer*">

добавляет все файлы с расширением CS в тип элементов Compile кроме файлов, имена которых содержат строку "Designer". Дополнительные примеры см. в разделе Практическое руководство. Исключение файлов из построения.

Атрибут Exclude применяется только к элементам, добавленным с помощью атрибута Include в элемент, содержащий оба этих атрибута. Например:

<Compile Include="*.cs" />

<Compile Include="*.res" Exclude="Form1.cs">

файл Form1.cs, добавленный в предыдущем элементе, не будет исключен.

Чтобы включить и исключить элементы

  1. В редакторе кода замените задачу Message следующей строкой:

    <Message Text="Compile item type contains @(XFiles)" />

  2. Добавьте эту группу элементов непосредственно после элемента Import:

    <ItemGroup>
   <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
</ItemGroup>

  3. Сохраните файл проекта.

  4. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  5. Проанализируйте результат. Должна отобразиться следующая строка:

    Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx

Метаданные элементов

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

Для объявления метаданных элементов в файле проекта создается элемент с именем метаданных, являющийся дочерним по отношению к элементу, содержащему эти метаданные. Элемент может содержать ноль или более значений метаданных. Например, следующий элемент CSFile содержит метаданные Culture (Культура) со значением "Fr":

<ItemGroup>

<CSFile Include="main.cs">

<Culture>Fr</Culture>

</CSFile>

</ItemGroup>

Чтобы получить значение метаданных типа элементов, следует использовать следующий синтаксис, где ItemType — это имя типа элементов, а MetaDataName — имя метаданных.

%(ItemType.MetaDataName)

Чтобы проанализировать метаданные элементов

  1. В редакторе кода замените задачу Message следующей строкой:

    <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должны отобразиться следующие строки:

    Compile.DependentUpon:

    Compile.DependentUpon: Form1.cs

    Compile.DependentUpon: Resources.resx

    Compile.DependentUpon: Settings.settings

Следует обратить внимание на то, что фраза "Compile.DependentUpon" отображается несколько раз. Использование метаданных с таким синтаксисом в рамках целевого объекта становится причиной пакетной обработки. Пакетная обработка — это процесс, при котором задачи в рамках одного целевого файла выполняются по одному разу для каждого уникального значения метаданных. Это аналог скрипта MSBuild общей программной конструкции "for loop". Дополнительные сведения см. в разделе Пакетная обработка в MSBuild.

Стандартные метаданные

При каждом добавлении элемента в список элементов ему присваиваются некоторые стандартные метаданные. Например, %(Filename) возвращает имя файла любого элемента. Полный список стандартных метаданных элементов см. в разделе Общеизвестные метаданные элементов MSBuild.

Чтобы проанализировать стандартные метаданные

  1. В редакторе кода замените задачу Message следующей строкой:

    <Message Text="Compile Filename: %(Compile.Filename)" />

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должны отобразиться следующие строки:

    Compile Filename: Form1

    Compile Filename: Form1.Designer

    Compile Filename: Program

    Compile Filename: AssemblyInfo

    Compile Filename: Resources.Designer

    Compile Filename: Settings.Designer

Сравнив два примера выше, можно увидеть, что хотя не у каждого элемента в типе элементов Compile имеются метаданные DependentUpon, однако у всех элементов есть стандартные метаданные Filename (Имя файла).

Преобразование метаданных

Списки элементов можно преобразовать в новые списки элементов. Чтобы преобразовать список элементов, следует использовать следующий синтаксис, где ItemType — это имя типа элементов, а MetaDataName — имя метаданных.

@(ItemType -> '%(MetadataName)')

Например, коллекцию списков, состоящую из исходных файлов, можно преобразовать в коллекцию объектных файлов с помощью выражения @(SourceFiles -> '%(Filename).obj'). Дополнительные сведения см. в разделе Преобразования MSBuild.

Чтобы преобразовать элементы с помощью метаданных

  1. В редакторе кода замените задачу Message следующей строкой:

    <Message Text="Backup files: @(Compile->'%(filename).bak')" />

  2. Сохраните файл проекта.

  3. Введите и выполните следующую строку в командном окне:

    msbuild helloworld.csproj /t:HelloWorld

  4. Проанализируйте результат. Должна отобразиться следующая строка:

    Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak

Следует обратить внимание, что выраженные в этом синтаксисе метаданные не становятся причиной пакетной обработки.

Что дальше?

Сведения о пошаговом создании простого файла проекта см. в разделе Пошаговое руководство. Создание файла проекта MSBuild с нуля.

См. также

Другие ресурсы

MSBuild

Справочные сведения о MSBuild