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

MSBuild — это платформа сборки для Microsoft и 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-форматированные файлы с корневым узлом Project.

Большинство проектов .NET имеют атрибут Sdk. Эти проекты называются проектами в стиле SDK. Ссылка на пакет SDK означает, что MSBuild импортирует набор файлов, которые предоставляют инфраструктуру сборки для этого пакета SDK. Если вы не ссылаетесь на какой-либо пакет SDK, вы по-прежнему можете использовать MSBuild, вы просто не будете автоматически иметь все свойства и целевые объекты, относящиеся к пакету SDK.

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

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

Создание приложения выполняется с использованием элементов Target и Task.

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

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

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

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

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

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

Задача Message принимает строковое значение атрибута Text в качестве входных данных и отображает его на выходном устройстве (или записывает его в один или несколько журналов, если применимо). Целевой объект HelloWorld дважды выполняет задачу "Сообщение": сначала отображается "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>net8.0</TargetFrameworkVersion>

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

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

<TargetFrameworkVersion>net6.0</TargetFrameworkVersion>

отображается позже в файле проекта или в файле, импортированном позже в проект, затем TargetFrameworkVersion принимает новое значение "net6.0".

Проверка значения свойства

Чтобы получить значение свойства, используйте следующий синтаксис, где 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>

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

Почти все элементы MSBuild могут иметь атрибут Condition. Дополнительные сведения об использовании атрибута 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.

Измените задачу 'Сообщение', чтобы показать значение свойства Configuration со специальными символами и сделать его более читабельным.

Использование специальных символов в задаче "Сообщение":

1. В редакторе кода замените обе задачи сообщения этой строкой:

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

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

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

   msbuild buildapp.csproj -t:HelloWorld
   

4. Проверьте выходные данные. Вы увидите эту строку:

   $(Configuration) is "Debug"
   

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

Создание предметов

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

Все элементы являются дочерними элементами элементов ItemGroup. Имя элемента — это имя дочернего элемента, а значение элемента — значение атрибута Include дочернего элемента. Значения элементов с тем же именем собираются в соответствующие типы элементов. Например

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

определяет группу элементов, содержащую два элемента. Тип элемента Компиляция имеет два значения: 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 является типом элемента и разделителем является строка одного или нескольких разделяющих символов:

@(ItemType, Separator)

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

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

1. В редакторе кода замените задачу "Сообщение" этой строкой:

   <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 для добавления элементов в тип элемента. Например

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

добавляет все файлы с расширением .jpeg в папку изображений в тип "Фотографии", а

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

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

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

<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 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 содержит метаданные культуры со значением "Fr".

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

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

%(ItemType.MetaDataName)

Для проверки метаданных элемента:

1. В редакторе кода замените задачу "Сообщение" этой строкой:

   <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) возвращает имя файла любого элемента. Для полного списка известных метаданных элементов см. метаданные известных элементов.

Для изучения известных метаданных:

1. В редакторе кода замените задачу "Сообщение" этой строкой:

   <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, все элементы имеют известные метаданные имени файла.

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

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

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

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

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

1. В редакторе кода замените задачу "Сообщение" этой строкой:

   <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