Написание задач для MSBuild

2025-06-12

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

Предпосылки

Проект Visual Studio, который строится с помощью MSBuild.

Задачи

Примеры задач MSBuild включают Copy, копирующий один или несколько файлов , MakeDir, который создает каталог и Csc, который компилирует файлы исходного кода C#. Каждая задача реализуется как класс .NET, реализующий ITask интерфейс, определенный в сборкеMicrosoft.Build.Framework.dll .

При реализации задачи можно использовать любой из следующих подходов:

Реализуйте интерфейс ITask напрямую.
Наследуйте свой класс от вспомогательного класса Task, который определён в сборке Microsoft.Build.Utilities.dll. Task реализует ITask и предоставляет стандартные реализации некоторых членов ITask. Ведение журнала также проще.

В обоих случаях необходимо добавить метод в именованный Executeкласс, который вызывается при выполнении задачи. Этот метод не принимает параметров и возвращает значение Boolean: true, если задача завершилась успешно или false, если она завершилась ошибкой. В следующем примере показана задача, которая не выполняет никаких действий, завершается успешно и возвращается true.

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace MyTasks
{
    public class SimpleTask : Task
    {
        public override bool Execute()
        {
            return true;
        }
    }
}

Следующий файл проекта MSBuild выполняет предыдущую задачу:

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

При выполнении задач они также могут получать входные данные из файла проекта при создании свойств .NET в классе задач. MSBuild задает эти свойства непосредственно перед вызовом метода Execute задачи. Чтобы создать строковое свойство, используйте код задачи, например следующий пример:

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace MyTasks
{
    public class SimpleTask : Task
    {
        public override bool Execute()
        {
            return true;
        }

        public string MyProperty { get; set; }
    }
}

Следующий файл проекта запускает эту задачу и устанавливает MyProperty в заданное значение.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Как MSBuild вызывает задачи

При вызове задачи MSBuild сначала создает экземпляр класса задач, а затем вызывает наборы свойств этого объекта для параметров задачи, заданных в элементе задачи в файле проекта. Если элемент задачи не задает параметр или если выражение, указанное в элементе, вычисляется пустой строкой, метод задания свойств не вызывается.

Например, в следующем проекте вызывается только сеттер для Input3.

<Project>
 <Target Name="InvokeCustomTask">
  <CustomTask Input1=""
              Input2="$(PropertyThatIsNotDefined)"
              Input3="value3" />
 </Target>
</Project>

Задача не должна зависеть от относительного порядка вызова набора свойств параметров.

Типы параметров задачи

MSBuild изначально обрабатывает свойства типа string, boolITaskItem и ITaskItem[]. Если задача принимает параметр другого типа, MSBuild вызывает ChangeType преобразование из string, со всеми ссылками на свойства и элементы, развернутыми в целевой тип. Если преобразование завершается ошибкой для любого входного параметра, MSBuild выдает ошибку и не вызывает метод задачи Execute() .

Регистрация задач

Чтобы выполнить задачу, MSBuild должна знать, как найти и запустить сборку, содержащую класс задач. Задачи регистрируются с помощью элемента UsingTask (MSBuild).

Если задача имеет конкретные зависимости от среды выполнения, необходимо указать MSBuild выполнить задачу в определенной среде, указав атрибуты Architecture или Runtime в элементе UsingTask. Дополнительные сведения см. в разделе "Атрибуты UsingTask" и параметры задачи.

MsBuild-файл Microsoft.Common.tasks — это файл проекта, в котором перечислены UsingTask элементы, которые регистрируют все задачи, предоставленные в MSBuild. Этот файл автоматически включается при сборке любого проекта с помощью MSBuild. Если задача, зарегистрированная в Microsoft.Common.tasks, также зарегистрирована в текущем файле проекта, то приоритет отдается текущему файлу проекта, что позволяет заменить задачу по умолчанию на вашу собственную задачу с таким же именем.

Совет

Список задач, предоставляемых определенной версией MSBuild, можно увидеть, просмотрев содержимое файла Microsoft.Common.tasks.

Требовать задания свойств задачи

Вы можете пометить определенные свойства задачи как обязательные, чтобы любой файл проекта, выполняющий задачу, должен был задать значения для этих свойств, иначе сборка завершится неудачно. Примените атрибут [Required] к свойству .NET в задаче следующим образом:

[Required]
public string RequiredProperty { get; set; }

Атрибут [Required] определяется RequiredAttribute в пространстве имен Microsoft.Build.Framework.

Создание событий из задачи

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

public override bool Execute()
{
    Log.LogError("messageResource1", "1", "2", "3");
    Log.LogWarning("messageResource2");
    Log.LogMessage(MessageImportance.High, "messageResource3");
    ...
}

Если задача реализуется ITask напрямую, вы по-прежнему можете вызвать такие события, но необходимо использовать IBuildEngine интерфейс. В следующем примере показана задача, реализующая ITask и создающая настраиваемое событие.

public class SimpleTask : ITask
{
    public IBuildEngine BuildEngine { get; set; }

    public override bool Execute()
    {
        TaskEventArgs taskEvent =
            new TaskEventArgs(BuildEventCategory.Custom,
            BuildEventImportance.High, "Important Message",
           "SimpleTask");
        BuildEngine.LogBuildEvent(taskEvent);
        return true;
    }
}

Упаковка задачи

Рекомендуемый способ распространения задачи — в пакете NuGet. Пакет должен включить все зависимости. Руководство по созданию пользовательской задачи см. в разделе "Создание пакета NuGet".

Пример 1

Следующий класс C# демонстрирует задачу, полученную из вспомогательного Task класса. Эта задача возвращает true, указывая, что она выполнена успешно.

using System;
using Microsoft.Build.Utilities;

namespace SimpleTask1
{
    public class SimpleTask1: Task
    {
        public override bool Execute()
        {
            // This is where the task would presumably do its work.
            return true;
        }
    }
}

Пример 2

Следующий класс C# демонстрирует задачу реализации ITask интерфейса. Эта задача возвращает true, указывая, что она выполнена успешно.

using System;
using Microsoft.Build.Framework;

namespace SimpleTask2
{
    public class SimpleTask2: ITask
    {
        //When implementing the ITask interface, it's necessary to
        //implement a BuildEngine property of type
        //Microsoft.Build.Framework.IBuildEngine. This is done for
        //you if you derive from the Task class.
        public IBuildEngine BuildEngine { get; set; }

        // When implementing the ITask interface, it's necessary to
        // implement a HostObject property of type object.
        // This is done for you if you derive from the Task class.
        public object HostObject { get; set; }

        public bool Execute()
        {
            // This is where the task does its work.
            return true;
        }
    }
}

Пример 3

Этот класс C# демонстрирует задачу, наследуемую от вспомогательного класса Task. Задача имеет обязательный строковый атрибут и вызывает событие, отображаемое всеми зарегистрированными логгерами.

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace SimpleTask3
{
    public class SimpleTask3 : Task
    {
        private string myProperty;

        // The [Required] attribute indicates a required property.
        // If a project file invokes this task without passing a value
        // to this property, the build will fail immediately.
        [Required]
        public string MyProperty
        {
            get
            {
                return myProperty;
            }
            set
            {
                myProperty = value;
            }
        }

        public override bool Execute()
        {
            // Log a high-importance comment
            Log.LogMessage(MessageImportance.High,
                "The task was passed \"" + myProperty + "\".");
            return true;
        }
    }
}

Пример 4

В следующем примере показан файл проекта, который вызывает предыдущую примерную задачу. SimpleTask3

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <UsingTask TaskName="SimpleTask3.SimpleTask3"
        AssemblyFile="SimpleTask3\bin\debug\simpletask3.dll"/>

    <Target Name="MyTarget">
        <SimpleTask3 MyProperty="Hello!"/>
    </Target>
</Project>