Руководство. Использование MSBuild

MSBuild является платформой сборки для корпорации Майкрософт и Visual Studio. В этом руководстве описаны стандартные блоки MSBuild и показано, как писать, управлять и отлаживать проекты MSBuild. Здесь содержатся сведения о:

• создание файла проекта и работа с ним;

• Использование свойств сборки.

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

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

Установка MSBuild

Если у вас есть Visual Studio, то MSBuild уже установлен. В Visual Studio 2022 средства сборки устанавливаются в папку установки Visual Studio. Для обычной установки по умолчанию в Windows 10 файл MSBuild.exe находится в папке установки MSBuild\Current\Bin.

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

Чтобы установить MSBuild в системе без Visual Studio, см. раздел "Средства сборки для Visual Studio 2022" на странице загрузок. Другой способ получить MSBuild — установить пакет SDK для .NET.

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

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

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

1. Откройте Visual Studio и создайте проект.

   В поле поиска введите winformsи нажмите кнопку "Создать новое приложение Windows Forms" (платформа .NET Framework). В появившемся диалоговом окне выберите Создать.

   В поле Имя проекта введите BuildApp. Введите расположение решения, например D:\.

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

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

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

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

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

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

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

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

Примечание.

Для некоторых типов проектов, например C++, необходимо выгрузить проект, прежде чем можно будет открыть и изменить файл проекта. Чтобы выгрузить проект, щелкните правой кнопкой мыши файл проекта и выберите Выгрузить проект.

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

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

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0"  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

Большинство проектов .NET имеют Sdk атрибут. Эти проекты называются проектами в стиле SDK.

<Project Sdk="Microsoft.NET.Sdk">

Существует множество вариантов пакетов SDK для .NET для специальных целей; Они описаны в пакетах SDK для проекта .NET.

Создание приложения выполняется с помощью элементов Целевой объект и Задача.

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

• Целевой объект представляет собой именованную последовательность задач. Дополнительные сведения см. в статье о целевых объектах.

• [это может быть именованная последовательность задач, но крайне важно то, что она представляет собой что-то, что должно быть создано или выполнено, поэтому ее необходимо определить с помощью подхода, ориентированного на цели]

Целевой объект по умолчанию не определен в файле проекта. Вместо этого он указан в импортированных проектах. Элемент Import указывает импортированные проекты. Например, в проекте C# целевой объект по умолчанию импортируется из файла Microsoft.CSharp.targets.

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

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

В проектах в стиле SDK вы не увидите этого элемента Import, так как атрибут SDK приводит к неявному импорту этого файла.

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

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

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

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

1. Добавьте следующие строки в файл проекта сразу после инструкции Import или после начала элемента Project.

   <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", а затем отображает "Мир".

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

Если вы пытаетесь создать этот проект из Visual Studio, он не создает определенный целевой объект. Это связано с тем, что Visual Studio выбирает целевой объект по умолчанию, который по-прежнему находится в импортированном .targets файле.

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

Примечание.

Мы будем ссылаться на командную строку разработчика в качестве командного окна в следующих разделах.

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

1. Откройте командное окно.

   В поле поиска на панели задач начните вводить имя средства, например dev или developer command prompt. Откроется список установленных приложений, которые соответствуют вашему шаблону поиска.

   Если его нужно найти вручную, файл — LaunchDevCmd.bat в папке {Папка установки Visual Studio}\Common7\Tools .

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, возможно, вы забыли сохранить файл проекта в редакторе кода. Сохраните файл и повторите попытку.

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

Свойства сборки

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

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

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

<TargetFrameworkVersion>v4.5</TargetFrameworkVersion>

определяет свойство TargetFrameworkVersion, указывающее строковое значение версии 4.5.

Свойства сборки можно переопределять в любое время. 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. Изучите выходные данные. Вы должны увидеть эти две строки (выходные данные могут отличаться):

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
   

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

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

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

значение "Если свойство конфигурации еще не определено, определите его и присвойте ему значение "Отладка".

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

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

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

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

Ссылаться на переменные среды в файлах проектов можно так же, как на свойства сборки. Например, чтобы использовать переменную среды PATH в файле проекта, примените $(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, даже если файл проекта является импортированным. Существует несколько исключений, например при использовании элементов Import и UsingTask.

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

Чтобы получить значения типа элемента, используйте следующий синтаксис, где 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 для использования символов возврата каретки и перевода строки (%0A%0D) для отображения элементов Compile по одному в строке.

Отображение значений типов элементов по одному в строке

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
   

Атрибуты 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="XFiles item type contains @(XFiles)" />
   

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

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

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

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

   msbuild buildapp.csproj -t:HelloWorld
   

5. Изучите выходные данные. Вы должны увидеть следующую строку:

   XFiles 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, эквивалентный общей конструкции программирования foreach. Дополнительные сведения см. в статье Пакетная обработка.

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

Всякий раз, когда элемент добавляется в список элементов, ему назначаются некоторые стандартные метаданные. Например %(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
   

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

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

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

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

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

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

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
   

Обратите внимание, что метаданные, выраженные в этом синтаксисе, не вызывают пакетную обработку.

Следующие шаги

Чтобы узнать, как создать простой файл проекта один шаг за раз в Windows, попробуйте создать файл проекта MSBuild с нуля.

Если вы используете в основном пакет SDK для .NET, перейдите по ссылке MSBuild для проектов пакета SDK для .NET.

См. также

• Общие сведения об MSBuild
• Справочные сведения о MSBuild