MSBuild

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 или с помощью текстового редактора.

Установка MSBuild

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

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

Сведения о MSBuild

Начиная с 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 см. в разделе Справочник по командной строке.

Важно

Перед скачиванием проекта определите надежность кода.

Для .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 для определения стандартной логики сборки. Файлы .props определяют свойства MSBuild и .targets файлы определяют целевые объекты 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>

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

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

Элементы

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

В файле проекта элементы декларируются путем создания элемента, где имя типа элемента выступает дочерним элементом элемента ItemGroup. Например, следующий код создает тип элемента с именем Compile, который включает два файла.

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

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

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

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

Создание журналов

Вы можете записывать ошибки сборки, предупреждения и сообщения на консоль или другое выходное устройство. Дополнительные сведения см. в разделе Получение журналов сборки с помощью 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 выпущен, вы можете нацелиться на него.

• Мультитаргетирование гарантирует, что приложение использует только функциональность, доступную в целевом фреймворке и платформе.

Дополнительные сведения см. в мультитаргетинг.

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

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

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

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

MSBuild — это открытый исходный код

MSBuild — это проект с открытым кодом, который принимает участие пользователей в репозитории MSBuild GitHub .

См. также

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

Ссылка

• справочник по MSBuild
  Ссылки на разделы, содержащие справочные сведения.

• глоссарий
  Определяет общие термины MSBuild.