Cómo: Escribir una tarea
Actualización: noviembre 2007
Las tareas proporcionan el código que se ejecuta durante el proceso de generación. Las tareas están contenidas en destinos. Con MSBuild se proporciona una biblioteca de tareas típicas, pero también puede crear las suyas propias. Para obtener más información sobre la biblioteca de tareas proporcionada con MSBuild, vea Referencia de tareas de MSBuild.
Tareas
Algunos ejemplos de tareas son Copy, que copia uno o más archivos; MakeDir, que crea un directorio; y Csc, que compila archivos de código fuente de Visual C#. Cada tarea se implementa como una clase de .NET que implementa la interfaz ITask, que se define en el ensamblado Microsoft.Build.Framework.dll.
Al implementar una tarea se pueden utilizar dos enfoques:
Implementar la interfaz ITask directamente.
Derivar la clase de la clase auxiliar, Task, que se define en el ensamblado Microsoft.Build.Utilities.dll. La tarea implementa ITask y proporciona implementaciones predeterminadas de algunos miembros de ITask. Además, el registro resulta más sencillo.
En ambos casos, debe agregar a la clase un método denominado Execute, al que se llama cuando se ejecuta la tarea. Este método no utiliza ningún parámetro y devuelve un valor Boolean: es true si la tarea se ha realizado correctamente o false si se ha producido un error. El ejemplo siguiente muestra una tarea que no realiza ninguna acción y devuelve true.
using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace MyTasks
{
public class SimpleTask : Task
{
public override bool Execute()
{
return true;
}
}
}
El archivo de proyecto siguiente ejecuta esta tarea:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask />
</Target>
</Project>
Al ejecutarse una tarea, también puede recibir información de entrada del archivo de proyecto si se crean propiedades de .NET en la clase de la tarea. MSBuild establece estas propiedades de forma inmediata antes de llamar al método Execute de la tarea. Para crear una propiedad de cadena, utilice código de tareas como:
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; }
}
}
}
El archivo de proyecto siguiente ejecuta esta tarea y establece MyProperty en el valor dado:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask MyProperty="Value for MyProperty" />
</Target>
</Project>
Registrar las tareas
Si un proyecto es capaz de ejecutar una tarea, MSBuild debe saber cómo localizar el ensamblado que contiene la clase de la tarea. Las tareas se registran utilizando Elemento UsingTask (MSBuild).
El archivo Microsoft.Common.Tasks de MSBuild es un archivo de proyecto que contiene una lista de elementos UsingTask que registran las tareas suministradas con MSBuild. Este archivo se incluye automáticamente al generar cada proyecto. Si una tarea registrada en Microsoft.Common.Tasks también está registrada en el archivo de proyecto actual, éste último tiene prioridad; es decir, puede reemplazar la tarea predeterminada con la suya propia del mismo nombre.
.gif "Sugerencia") Sugerencia: |
|---|
Puede ver una lista de las tareas que se proporcionan con MSBuild; para ello, vea el contenido de Microsoft.Common.Tasks. |
Provocar eventos desde una tarea
Si la tarea se deriva de la clase auxiliar Task, puede utilizar cualquiera de los siguientes métodos auxiliares en la clase Task para generar eventos que se detectarán y mostrarán por cualquiera de los registradores registrados:
public override bool Execute()
{
Log.LogError("messageResource1", "1", "2", "3");
Log.LogWarning("messageResource2");
Log.LogMessage(BuildEventImportance.High, "messageResource3");
...
}
Si la tarea implementa ITask directamente, también puede provocar estos eventos, pero deberá utilizar la interfaz IBuildEngine. El ejemplo siguiente muestra una tarea que implementa ITask y provoca un evento personalizado:
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;
}
}
Forzar a que se establezcan algunos parámetros de las tareas
Puede marcar algunas propiedades de las tareas como “requeridas” para que cualquier archivo de proyecto que las ejecute deba establecer valores para ellas o, en caso contrario, la compilación no se producirá. Para ello, aplique el atributo [Required] a la propiedad de .NET en la tarea, como sigue:
private string requiredProperty;
[Required]
public string RequiredProperty
{
get { return requiredProperty; }
set { requiredProperty = value; }
}
RequiredAttribute define el atributo [Required] en el espacio de nombres Microsoft.Build.Framework.
Ejemplo
Descripción
Esta clase de Visual C# muestra una tarea que deriva de la clase auxiliar Task. Esta tarea devuelve true, lo que indica que se ha ejecutado correctamente.
Código
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;
}
}
}
Ejemplo
Descripción
Esta clase de Visual C# muestra una tarea que implementa la interfaz ITask. Esta tarea devuelve true, lo que indica que se ha ejecutado correctamente.
Código
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;
}
}
}
Ejemplo
Descripción
Esta clase de Visual C# muestra una tarea que deriva de la clase auxiliar Task. Tiene una propiedad de cadena requerida y provoca un evento que aparece en todos los registradores registrados.
Código
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;
}
}
}
Ejemplo
Descripción
El ejemplo siguiente muestra un archivo de proyecto que invoca la tarea del ejemplo anterior, SimpleTask3.
Código
<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>