Практическое руководство. Написание задачи
Обновлен: Ноябрь 2007
В задачах предоставляется код, выполняющийся во время процесса построения. Задачи содержатся в целевых объектах. В MSBuild включена библиотека типичных задач, а также можно создавать собственные задачи. Дополнительные сведения о библиотеке задач, включенных в MSBuild, см. в разделе Справочные сведения о задачах MSBuild.
Задачи
Примеры задач: Copy — копирование одного или нескольких файлов, MakeDir — создание каталога, Csc — компиляция файлов исходного кода Visual C#. Каждая задача реализована в виде класса платформы .NET, обеспечивающего интерфейс ITask, который определен в сборке Microsoft.Build.Framework.dll.
Существуют два подхода к реализации задачи.
Реализация непосредственно интерфейса ITask.
Получение класса из вспомогательного класса Task, который определен в сборке Microsoft.Build.Utilities.dll. Задача реализует 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;
}
}
}
Эта задача запускается из следующего файла проекта:
<Project xmlns="https://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;
}
private string myProperty;
public string MyProperty
{
get { return myProperty; }
set { myProperty = value; }
}
}
}
Из следующего файла проекта запускается эта задача и задается свойство MyProperty для заданного значения:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask MyProperty="Value for MyProperty" />
</Target>
</Project>
Регистрация задач
Если проекту предстоит запускать задачу, MSBuild необходимо знать, как найти сборку, содержащую класс задачи. Задачи регистрируются с использованием метода Элемент UsingTask (MSBuild).
Файл Microsoft.Common.Tasks в MSBuild — это файл проекта, который содержит список элементов UsingTask, регистрирующих все задачи, предоставленные вместе с MSBuild. Этот файл включается автоматически при создании каждого проекта. Если задача, зарегистрированная в файле Microsoft.Common.Tasks, зарегистрирована также в текущем файле проекта, текущий файл проекта имеет преимущество; таким образом можно переопределить задачу по умолчанию собственной задачей с тем же именем.
.gif "Совет") Совет. |
|---|
Чтобы увидеть список задач, предоставленных вместе с MSBuild, просмотрите содержимое файла Microsoft.Common.Tasks. |
Создание событий из задачи
В случае получения задачи из вспомогательного класса Task можно использовать любой из следующих вспомогательных методов в классе Task для создания событий, которые будут подхватываться и отображаться каким-либо зарегистрированным средством ведения журнала:
public override bool Execute()
{
Log.LogError("messageResource1", "1", "2", "3");
Log.LogWarning("messageResource2");
Log.LogMessage(BuildEventImportance.High, "messageResource3");
...
}
Если в задаче реализуется непосредственно интерфейс ITask, можно также создавать эти события, но необходимо использовать интерфейс IBuildEngine. В следующем примере показана задача, реализующая ITask и создающая пользовательское событие:
public class SimpleTask : ITask
{
private IBuildEngine buildEngine;
public IBuildEngine BuildEngine
{
get{ return buildEngine; }
set{ buildEngine = value; }
}
public override bool Execute()
{
TaskEventArgs taskEvent =
new TaskEventArgs(BuildEventCategory.Custom,
BuildEventImportance.High, "Important Message",
"SimpleTask");
BuildEngine.LogBuildEvent(taskEvent);
return true;
}
}
Обязательные параметры задачи
Некоторые свойства задачи можно пометить как "обязательные", чтобы в любом файле проекта, из которого запускается задача, необходимо было задавать значения для этих свойств, иначе построение выполнить не удастся. Примените к свойству .NET в задаче атрибут [Required] следующим образом:
private string requiredProperty;
[Required]
public string RequiredProperty
{
get { return requiredProperty; }
set { requiredProperty = value; }
}
Атрибут [Required] определен свойством RequiredAttribute в пространстве имен Microsoft.Build.Framework.
Пример
Описание
В этом классе Visual 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;
}
}
}
Пример
Описание
В этом классе Visual C# показана задача, реализующая интерфейс ITask. Эта задача возвращает значение true, указывающее на успешность ее выполнения.
Код
using System;
using Microsoft.Build.Framework;
namespace SimpleTask2
{
public class SimpleTask2: ITask
{
//When implementing the ITask interface, it is necessary to
//implement a BuildEngine property of type
//Microsoft.Build.Framework.IBuildEngine. This is done for
//you if you derive from the Task class.
private IBuildEngine buildEngine;
public IBuildEngine BuildEngine
{
get
{
return buildEngine;
}
set
{
buildEngine = value;
}
}
// When implementing the ITask interface, it is necessary to
// implement a HostObject property of type Object.
// This is done for you if you derive from the Task class.
private Object hostObject;
public Object HostObject
{
get
{
return hostObject;
}
set
{
hostObject = value;
}
}
public bool Execute()
{
// This is where the task would presumably do its work.
return true;
}
}
}
Пример
Описание
В этом классе Visual 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;
}
}
}
Пример
Описание
В этом примере показан файл проекта, в котором вызывается задача из предыдущего примера (SimpleTask3).
Код
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<UsingTask TaskName="SimpleTask3.SimpleTask3"
AssemblyFile="SimpleTask3\bin\debug\simpletask3.dll"/>
<Target Name="MyTarget">
<SimpleTask3 MyProperty="Hello!"/>
</Target>
</Project>