Пошаговое руководство. Использование 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.

Рабочий построение приложения выполняется с целевой объект и элементами задача.

  • Задача представляет собой наименьший блок, другими словами, это "атом" построения.Задачи являются независимыми исполняемыми компонентами, которые могут иметь входные и выходные данные.В настоящий момент отсутствуют задачи, на которые имеются ссылки или которые определены в файле проекта.В разделах ниже описано добавление задач в файл проекта.Дополнительные сведения см. в разделе Задачи 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 buildapp.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 buildapp.csproj /t:HelloWorld

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

    Configuration is Debug
MSBuildToolsPath is C:\Windows\Microsoft.NET\Framework\v4.0.20317
ПримечаниеПримечание

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

Dd393573.collapse_all(ru-ru,VS.110).gifУсловные свойства

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

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

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

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

Dd393573.collapse_all(ru-ru,VS.110).gifЗарезервированные свойства

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

Dd393573.collapse_all(ru-ru,VS.110).gifПеременные среды

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

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

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

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

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

    msbuild buildapp.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 buildapp.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 buildapp.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 buildapp.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

Dd393573.collapse_all(ru-ru,VS.110).gifАтрибуты 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 buildapp.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 buildapp.csproj /t:HelloWorld

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

    Compile.DependentUpon:
Compile.DependentUpon: Form1.cs
Compile.DependentUpon: Resources.resx
Compile.DependentUpon: Settings.settings

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

Dd393573.collapse_all(ru-ru,VS.110).gifСтандартные метаданные

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

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

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

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

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

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

    msbuild buildapp.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 (Имя файла).

Dd393573.collapse_all(ru-ru,VS.110).gifПреобразование метаданных

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

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

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

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

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

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

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

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

    msbuild buildapp.csproj /t:HelloWorld

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

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

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

Что дальше?

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

См. также

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

MSBuild

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