MSBuild

Статья
11/03/2023

Microsoft Build Engine представляет собой платформу для сборки приложений. Компонент MSBuild обеспечивает для файла проекта схему XML, определяющую способы, используемые платформой сборки для обработки и сборки приложений. Visual Studio использует MSBuild, но MSBuild не зависит от Visual Studio. Вызывая msbuild.exe или dotnet build в файле проекта или решения, вы можете оркестрировать и создавать продукты в средах, где Visual Studio не установлен.

Visual Studio использует MSBuild для загрузки и сборки управляемых проектов. Файлы проектов в Visual Studio (с расширением CSPROJ, VBPROJ, VCXPROJ) содержат код XML MSBuild, который выполняется при создании проекта с помощью интегрированной среды разработки. Проекты Visual Studio импортируют все необходимые параметры и процессы сборки для выполнения стандартной работы по разработке, но их можно расширять и изменять в Visual Studio или в редакторе XML.

Чтобы установить MSBuild в системе Windows, которая не имеет Visual Studio, перейдите в раздел "Средства сборки для Visual Studio " на странице загрузки. Установка MSBuild с помощью этого метода предоставляет MSBuild.exe.

Для .NET Core и .NET 5 или более поздней версии другой способ получения эквивалента MSBuild заключается в установке пакета SDK для .NET. Команда dotnet build сборки .NET доступна с помощью пакета SDK для .NET в macOS, Windows или Linux. Команда dotnet build сборки .NET — это тонкая оболочка в версии .NET Core MSBuild.exe. С помощью интерфейса командной строки .NET Core (CLI), использующего MSBuild, можно создавать проекты, предназначенные для .NET Core и .NET 5 и более поздних версий.

Начиная с Visual Studio 2022, при выполнении сборки в Visual Studio используется 64-разрядная версия MSBuild.

Сведения об MSBuild для C++ см. в разделе MSBuild (C++).

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

Среда Visual Studio не установлена.
Вам требуется 64-разрядная версия MSBuild, но вы используете Visual Studio 2019 или более ранней версии. Эта версия MSBuild обычно не нужна, но она позволяет MSBuild обращаться к большему объему памяти.
Сборку требуется выполнять в нескольких процессах. Однако можно использовать интегрированную среду разработки, чтобы добиться того же результата для проектов на C++ и C#.
Требуется изменить систему сборки. Например, может потребоваться выполнить следующие действия:
- предварительная обработка файлов перед их компиляцией;
- копирование выходных данных сборки в другое место;
- создание сжатых файлов из выходных данных сборки;
- пост-обработка. Например, может потребоваться присвоить сборке другой номер версии.

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

Примечание.

С помощью Azure Pipelines можно автоматически компилировать, тестировать и развертывать приложение. Система сборки может автоматически запускать сборку, когда разработчики возвращают код (например, как часть стратегии непрерывной интеграции) или по расписанию (например, выполнять ежедневную ночную тестовую сборку). Azure Pipelines компилирует код с использованием MSBuild. Дополнительные сведения см. в описании Azure Pipelines.

Вводное руководство по MSBuild в Windows см. в пошаговом руководстве по использованию MSBuild.

Использование MSBuild в командной строке

Чтобы запустить MSBuild из командной строки, передайте файл проекта в MSBuild.exe при использовании соответствующих параметров командной строки. Параметры командной строки позволяют задавать свойства, выполнять определенные целевые объекты и задавать другие параметры, управляющие процессом построения. Например, используя следующий синтаксис командной строки, можно создать файл MyProj.proj со свойством Configuration, для которого задается значение Debug.

MSBuild.exe MyProj.proj -property:Configuration=Debug

MSBuild не изменяет его поведение на основе расширения файла, но соглашение заключается в том, чтобы использовать расширения, заканчивающиеся такими proj , как .csproj, .vcxprojили .vbprojдля основного входного файла MSBuild, называемого "файл проекта".

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

Внимание

Перед загрузкой проекта определите, можно ли доверять коду.

Для .NET Core и .NET 5 или более поздней версии обычно используется dotnet build для вызова MSBuild. См . dotnet build. Если вы устанавливаете только пакет SDK для .NET, а не Visual Studio или средства сборки Visual Studio, вы используете MSBuild только через dotnet build.

В командной dotnet build --help строке перечислены параметры командной строки, относящиеся к dotnet buildне всем параметрам MSBuild.exe, но вы по-прежнему можете использовать все параметры командной строки, перечисленные в справочнике командной строки MSBuild. Параметры, которые не обрабатываются dotnet build , передаются в MSBuild.

Файл проекта

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

Система сборки Visual Studio хранит логику для конкретного проекта в самом файле проекта и использует импортированные XML-файлы MSBuild с такими расширениями, как .props и .targets для определения стандартной логики сборки. Файлы определяют свойства MSBuild и .targets файлы определяют целевые .props объекты MSBuild. Эти импорты иногда отображаются в файле проекта Visual Studio, но в более новых проектах, таких как .NET Core, .NET 5 и .NET 6, импорт в файле проекта не отображается; Вместо этого вы увидите ссылку на пакет SDK, который выглядит следующим образом:

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

Это так называемые проекты в стиле SDK. При ссылке на пакет SDK, например пакет SDK для .NET, импорты .props и .target файлы неявно указываются пакетом SDK.

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

Свойства

Свойства представляют пары ключ-значение, с помощью которых выполняется настройка построения. Для объявления свойства создается элемент с таким же именем как у свойства, который является дочерним по отношению к элементу PropertyGroup. Например, в следующем коде создается свойство BuildDir со значением Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Свойство можно определить условно, задав атрибут Condition в элементе. Содержимое условных элементов игнорируется, пока значение условия не станет true. В следующем примере свойство определяется, Configuration если оно еще не определено.

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

Для обращения к свойствам в файле проекта используется синтаксис $(<ИмяСвойства>). Например, к свойствам из предыдущих примеров можно обращаться с помощью конструкций $(BuildDir) и $(Configuration).

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

Товаров

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

Для объявления элементов в файле проекта создается элемент с именем типа элементов, являющийся дочерним по отношению к элементу ItemGroup. Например, с помощью приведенного ниже кода создается тип элементов с именем Compile, в который входят два файла.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Для обращения к типам элементов в файле проекта используется синтаксис @(<ТипЭлемента>). Например, ссылка на тип элементов в этом примере выглядела бы следующим образом: @(Compile).

В MSBuild имена элементов и атрибутов задаются с учетом регистра. А имена свойств, элементов (item) и метаданных — нет. В следующем примере создается тип элементов Compile, comPile или любого другого варианта написания, и типу элементов присваивается значение "one.cs;two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

При объявлении элементов можно использовать подстановочные знаки; элементы могут содержать дополнительные метаданные для расширенных сценариев построения. Дополнительные сведения об элементах см. в разделе Элементы.

Задачи

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

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

MSBuild включает стандартные задачи, которые можно изменять в соответствии с требованиями. Примеры: Copy — копирование файлов, MakeDir — создание каталогов, Csc — компиляция файлов исходного кода Visual C#. Список доступных задач и сведения об их использовании см. в справочнике по задачам.

Задача выполняется в файле проекта MSBuild путем создания элемента с таким же именем как у задачи в виде дочернего элемента по отношению к элементу Target. Задачи, как правило, принимают параметры, которые передаются как атрибуты элемента. В качестве параметров можно использовать свойства и элементы MSBuild. Например, с помощью следующего кода вызывается задача MakeDir и ей передается значение свойства BuildDir, объявленного в предыдущем примере.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Дополнительные сведения о задачах см. в разделе Задачи.

Целевые объекты

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

Целевые объекты объявляются в файле проекта с помощью элемента Target. Например, с помощью следующего кода создается целевой объект с именем Compile, который затем вызывает задачу Csc со списком элементов, объявленным в предыдущем примере.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

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

Журналы сборки

Ошибки, предупреждения и сообщения журнала сборки можно выводить на консоль или на другое устройство вывода. Дополнительные сведения см. в статье "Получение журналов сборки с помощью MSBuild".

Использование MSBuild в Visual Studio

Visual Studio использует формат файла проекта MSBuild для хранения данных сборки об управляемых объектах. Параметры проекта, добавленные или измененные с помощью интерфейса Visual Studio, отражаются в файле .*proj, который создается для каждого проекта. Для построения управляемых проектов в Visual Studio используется размещенный экземпляр MSBuild. Это означает, что выполнить построение управляемого проекта можно в Visual Studio или в командной строке (даже при отсутствии Visual Studio), и результаты будут одинаковыми.

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

Настройка для различных версий

С помощью Visual Studio можно скомпилировать приложение для запуска в любой из нескольких версий платформа .NET Framework или .NET Core, включая .NET 5 и более поздних версий. Например, можно скомпилировать приложение для запуска на платформа .NET Framework 4 на 32-разрядной платформе, и вы можете скомпилировать то же приложение для запуска на платформа .NET Framework 4.8 на 64-разрядной платформе. Возможность компиляции для нескольких платформ называется настройкой для различных версий.

Ниже приведены несколько преимуществ настройки для различных версий:

Вы можете разрабатывать приложения, ориентированные на более ранние версии .NET Framework, например версии 3.5 и 4.7.2.
Можно ориентироваться на профиль платформы, который представляет собой предопределенное подмножество целевой платформы.
После появления пакета обновления для текущей версии .NET Framework можно выбрать его в качестве целевой платформы.
Поддержка различных платформ гарантирует, что приложение использует только те функциональные возможности, которые доступны в целевой версии .NET Framework и платформы.

Дополнительные сведения см. в разделе Настройка для различных версий.

Настройка сборки

MSBuild поддерживает широкий спектр пользовательских сценариев сборки. Большинство встроенных функций можно переопределить или расширить. Дополнительные сведения см. в статье Настройка сборки и

Доступ к MSBuild программным способом

Если вы разрабатываете средство сборки, может потребоваться вызвать MSBuild программным способом из приложения .NET. С помощью API MSBuild можно управлять всеми аспектами сложной системы сборки. MSBuild предоставляет пакет NuGet с полным API (пространство имен Microsoft.Build), который можно использовать из приложения .NET для этих целей. См. раздел "Использование API MSBuild".

MSBuild — это открытый код

MSBuild — это проект с открытым исходным кодом, который принимает вклад пользователей, как и остальная часть экосистемы .NET. Репозиторий, содержащий источник MSBuild, доступен в репозитории GitHub: MSBuild GitHub.

См. также

Заголовок	Description
Пошаговое руководство. Создание файла проекта MSBuild с нуля	Содержит описание способов пошагового создания основного файла проекта путем использования только текстового редактора.
Пошаговое руководство. Использование MSBuild	Содержит вводную информацию о стандартных блоках MSBuild и описание способов записи, управления и отладки проектов MSBuild без выхода из интегрированной среды разработки Visual Studio.
Основные понятия MSBuild	Содержит информацию о четырех стандартных блоках MSBuild: свойствах, элементах, целевых объектах и задачах.
Товаров	Содержит описание общих понятий, относящихся к формату файлов MSBuild, и способов взаимодействия фрагментов.
Свойства MSBuild	Содержит вводную информацию о свойствах и коллекциях свойств. Свойства представляют собой пары ключ-значение, с помощью которых выполняется настройка сборок.
Целевые объекты	Содержит объяснение группировки задач в определенном порядке и вызова разделов процесса построения из командной строки.
Задачи	Описывает процесс создания блока исполняемого кода, с помощью которого MSBuild выполняет атомарные операции построения.
Условия	Рассматривает использование атрибута `Condition` в элементе MSBuild.
Пакетная обработка	Описывает, как MSBuild классифицирует списки элементов по метаданным для выполнения в задачах и целевых объектах.
Настройка для различных версий	Показывает, как использовать несколько версий .NET и (или) нескольких платформ.
Получение журналов сборки	Описание возможностей записи в журнал событий, сообщений и ошибок сборки.
Как MSBuild выполняет сборку проектов	Описывает внутренний процесс сборки, используемый в MSBuild.
Создание настраиваемой задачи для создания кода	Инструкции по созданию настраиваемой задачи и пример кода.
Использование MSBuild для создания клиента REST API	Инструкции по расширению сборки для работы с созданием клиента REST API и пример кода.
Дополнительные ресурсы	Содержит список ресурсов сообщества и службы поддержки с дополнительной информацией о MSBuild.

Справочные материалы

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