MSBuild - задача

  • Статья

Выполняет сборку проектов MSBuild из другого проекта MSBuild.

Параметры

В следующей таблице приводятся параметры задачи MSBuild.

Параметр Описание
BuildInParallel Необязательный параметр Boolean.

Если его значение true, то сборка проектов, указанных в параметре Projects, выполняется параллельно, по возможности. По умолчанию — false.
Projects Обязательный параметр ITaskItem[] .

Он определяет файлы проекта, необходимые для сборки.
Properties Необязательный параметр String.

Список разделенных точкой с запятой пар имя-значение для применения в качестве глобальных свойств к дочернему проекту. Указание этого параметра функционально эквивалентно заданию значений свойств с помощью параметра -property при выполнении сборки с использованием MSBuild.exe. Например:

Properties="Configuration=Debug;Optimize=$(Optimize)"

При передаче проекту свойств с помощью параметра Properties MSBuild может создать новый экземпляр проекта даже в том случае, если файл проекта уже загружен. MSBuild создает один экземпляр проекта с использованием заданного пути проекта и уникального набора глобальных свойств. Например, это поведение позволяет создать несколько задач MSBuild, вызывающих myproject.proj, с Configuration=Release и получить единственный экземпляр myproject.proj (если в задаче не указаны уникальные свойства). Если указать свойство, которое еще не было просмотрено MSBuild, MSBuild формирует новый экземпляр проекта, который можно создать параллельно с другими экземплярами проекта. Например, сборка конфигурации выпуска может выполняться в одно время со сборкой конфигурации отладки.
RebaseOutputs Необязательный параметр Boolean.

Если его значение true, то относительные пути целевых выходных элементов из созданных проектов корректируются таким образом, чтобы соответствовать вызывающему проекту. По умолчанию — false.
RemoveProperties Необязательный параметр String.

Задает набор глобальных свойств для удаления.
RunEachTargetSeparately Необязательный параметр Boolean.

Если его значение true, то задача MSBuild вызывает каждый целевой объект из списка, переданного в MSBuild, по одному, а не все одновременно. Задание для этого параметра значения true гарантирует вызов последующих целевых объектов даже в случае сбоя ранее вызванных объектов. В противном случае из-за сбоя во время сборки какого-то одного объекта вызов всех последующих целевых объектов прекратится. По умолчанию — false.
SkipNonexistentProjects Необязательный параметр Boolean.

Если его значение true, то файлы проекта, не существующие на диске, будут пропущены. В противном случае такие проекты приведут к ошибке. По умолчанию — false.
SkipNonexistentTargets Необязательный параметр Boolean.

Если true, то файлы проекта, которые существуют, но не содержат именованные Targets, будут пропущены. В противном случае такие проекты приведут к ошибке. По умолчанию — false. Представлено в MSBuild 15.5.
StopOnFirstFailure Необязательный параметр Boolean.

Если его значение true, то в случае, если происходит сбой во время сборки одного из проектов, сборка остальных проектов не будет выполнена. В настоящее время не поддерживается при параллельной сборке (с несколькими процессорами).
TargetAndPropertyListSeparators Необязательный параметр String[].

Определяет список целевых объектов и свойств в качестве метаданных элемента Project). Разделители будут восстановлены перед обработкой. Например, выражение %3B (экранированный знак ";") будет рассматриваться как восстановленный знак ";".
TargetOutputs Необязательный выходной параметр ITaskItem[], доступный только для чтения.

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

Параметр TargetOutputs также содержит следующие метаданные:

- MSBuildSourceProjectFile: файл проекта MSBuild, содержащий целевой объект, который задает выходные данные.
- MSBuildSourceTargetName. Целевой объект, определяющий выходные данные. Примечание. Если необходимо определить выходные данные из каждого файла проекта или целевого объекта отдельно, запустите задачу MSBuild отдельно для каждого файла проекта или целевого объекта. Если вы запустите задачу MSBuild один раз для сборки всех файлов проекта, выходные данные всех целевых объектов будут собраны в один массив.
Targets Необязательный параметр String.

Определяет целевой объект (или объекты) для сборки в файлах проекта. Используйте точку с запятой для разделения списка имен целевых объектов. Если целевые объекты в задаче MSBuild не заданы, будет выполнена сборка целевых объектов по умолчанию, заданных в файлах проекта. Примечание. Целевые объекты должны быть указаны во всех файлах проекта. Если это не так, при сборке возникает ошибка.
ToolsVersion Необязательный параметр String.

Определяет ToolsVersion, используемую при сборке проектов, для передачи в эту задачу.

Позволяет задаче MSBuild выполнить сборку проекта, предназначенного для версии .NET Framework, отличающейся от той, которая указана в проекте. Допустимые значения: 2.0, 3.0 и 3.5. Значение по умолчанию: 3.5.

Замечания

Помимо перечисленных выше параметров, эта задача наследует параметры от класса TaskExtension, который, в свою очередь, наследует от класса Task. Список этих дополнительных параметров и их описания см. в статье Базовый класс TaskExtension.

В отличие от использования задачи Exec для запуска MSBuild.exe, эта задача использует тот же процесс MSBuild для создания дочерних проектов. Список уже собранных целевых объектов, которые могут быть пропущены, доступен как родительским, так и дочерним сборкам. Эта задача выполняется быстрее, так как при этом не создаются новые процессы MSBuild.

Эта задача может обрабатывать не только файлы проекта, но также файлы решения.

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

Начиная с версии MSBuild 3.5, проекты решения извлекают конечные выходные данные из всех подпроектов, которые он создает.

Передача свойств в проекты

В версиях MSBuild более ранних, чем MSBuild 3.5, выполнение передачи различных наборов свойств в разные проекты, перечисленные в элементе MSBuild, было сложной задачей. При использовании атрибута Properties задачи MSBuild его значение применялось ко всем создаваемым проектам. Чтобы применить разные значения, задачу MSBuild приходилось выполнять в пакетном режиме и условно определять разные свойства для каждого проекта в списке элементов.

MSBuild 3.5 предоставляет два новых зарезервированных элемента метаданных, Properties и AdditionalProperties, позволяющие легко передавать разные свойства в разные проекты, сборка которых выполнена с помощью задачи MSBuild.

Примечание.

Эти новые элементы метаданных применимы только к элементам, переданным с помощью атрибута Projects задачи MSBuild.

Преимущества сборки в системах с несколькими процессорами

Одно из основных преимуществ использования новых метаданных проявляется при выполнении сборок проектов в параллельном режиме в системах с несколькими процессорами. Метаданные позволяют объединить все проекты в один вызов задачи MSBuild, не требуя выполнения пакетной обработки или задачи MSBuild с разными условиями. При вызове единой задачи MSBuild сборка всех проектов, перечисленных в атрибуте Projects, будет выполняться параллельно. (Однако, только если BuildInParallel=true атрибут присутствует в задаче MSBuild.) Дополнительные сведения см. в статье "Создание нескольких проектов параллельно".

Метаданные Properties

Если указано, метаданные Properties переопределяют параметр Properties задачи, а метаданные AdditionalProperties добавляются к определениям параметров.

Чаще всего сборка нескольких файлов решения осуществляется с помощью задачи MSBuild, выполняемой с использованием разных конфигураций сборки. Например, вам нужно выполнить сборку решения a1 с помощью конфигурации отладки, а решения a2 — с помощью конфигурации выпуска. В версии MSBuild 2.0 такой файл проекта выглядел следующим образом:

Примечание.

В следующем примере знаком "..." обозначены дополнительные файлы решения.

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

Эту процедуру можно упростить, используя метаданные Properties и выполняя одну задачу MSBuild, как показано ниже:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

- или -

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln..."/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Debug"/>
    </Target>
</Project>

Метаданные AdditionalProperties

Рассмотрим сценарий, в котором выполняется сборка двух файлов решения с помощью задачи MSBuild, того и другого с использованием конфигурации выпуска, но одного из них с архитектурой x86, а другого — с архитектурой ia64. В версии MSBuild 2.0 вам потребовалось бы создать несколько экземпляров задачи MSBuild. Один — для сборки проекта с помощью конфигурации выпуска с архитектурой x86, другой — с помощью конфигурации выпуска с архитектурой ia64. Файл проекта выглядел бы следующим образом:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Release;
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release;
          Architecture=ia64"/>
    </Target>
</Project>

Эту процедуру можно упростить, используя метаданные AdditionalProperties и выполняя одну задачу MSBuild, как показано ниже:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Release"/>
    </Target>
</Project>

Пример

В следующем примере используется задача MSBuild для сборки проектов, определенных коллекцией элементов ProjectReferences. Полученные конечные выходные данные хранятся в коллекции элементов AssembliesBuiltByChildProjects.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

См. также