Redacción de tareas
Las tareas proporcionan el código que se ejecuta durante el proceso de compilación. Las tareas están contenidas en objetivos. Una biblioteca de tareas típicas se incluye con MSBuild y también puede crear sus propias tareas. Para obtener más información sobre la biblioteca de tareas que se incluyen con MSBuild, consulte Referencia de tareas.
Tareas
Entre los ejemplos de tareas se incluyen Copiar, que copia uno o varios archivos, MakeDir, que crea un directorio y Csc , que compila archivos de código fuente de C#. Cada tarea se implementa como una clase .NET que implementa la interfaz ITask, que se define en el ensamblado Microsoft.Build.Framework.dll.
Hay dos enfoques que puede usar al implementar una tarea:
Implemente directamente la interfaz ITask.
Derive su 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 es más fácil.
En ambos casos, debe agregar a la clase un método denominado Execute, que es el método al que se llama cuando se ejecuta la tarea. Este método no toma parámetros y devuelve un valor de Boolean: true si la tarea se realizó correctamente o false si se produjo un error. En el ejemplo siguiente se muestra una tarea que no realiza ninguna acción y se completa correctamente (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 siguiente archivo de proyecto ejecuta esta tarea:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask />
</Target>
</Project>
Cuando se ejecutan tareas, también pueden recibir entradas del archivo de proyecto si crea propiedades de .NET en la clase de tarea. MSBuild establece estas propiedades inmediatamente antes de llamar al método Execute de la tarea. Para crear una propiedad de cadena, use código de tarea como:
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; }
}
}
El siguiente archivo de proyecto ejecuta esta tarea y establece MyProperty en el valor especificado:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask MyProperty="Value for MyProperty" />
</Target>
</Project>
Registrar tareas
Si un proyecto va a ejecutar una tarea, MSBuild debe saber cómo buscar y ejecutar el ensamblado que contiene la clase de tarea. Las tareas se registran mediante el elemento UsingTask (MSBuild).
Si la tarea tiene dependencias específicas del entorno de ejecución, debe informar a MSBuild que debe ejecutar la tarea en un entorno específico indicando Architecture o Runtime en su UsingTask.
El archivo de MSBuild Microsoft.Common.tasks es un archivo de proyecto que contiene una lista de elementos de UsingTask que registran todas las tareas de que se proporcionan con MSBuild. Este archivo se incluye automáticamente al compilar cualquier proyecto. Si una tarea registrada en Microsoft.Common.tasks también está registrada en el archivo de proyecto actual, el archivo de proyecto actual tiene prioridad, por lo que puede invalidar una tarea predeterminada con su propia tarea que tenga el mismo nombre.
Sugerencia
Puede ver una lista de las tareas que se proporcionan con una versión específica de MSBuild viendo el contenido de su Microsoft.Common.tasks.
Generación de eventos de una tarea
Si la tarea se deriva de la clase auxiliar de Task, puede usar cualquiera de los métodos auxiliares siguientes en la clase Task para generar eventos que los registradores registrados detectarán y mostrarán:
public override bool Execute()
{
Log.LogError("messageResource1", "1", "2", "3");
Log.LogWarning("messageResource2");
Log.LogMessage(MessageImportance.High, "messageResource3");
...
}
Si la tarea implementa ITask directamente, puede seguir produciendo estos eventos, pero debe usar la interfaz IBuildEngine. En el ejemplo siguiente se muestra una tarea que implementa ITask y genera un evento personalizado:
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;
}
}
Requerir que se establezcan parámetros de tarea
Puede marcar determinadas propiedades de tarea como "obligatorias" para que cualquier archivo de proyecto que ejecute la tarea debe establecer valores para estas propiedades o se produce un error en la compilación. Aplique el atributo [Required] a la propiedad .NET de la tarea de la siguiente manera:
[Required]
public string RequiredProperty { get; set; }
El atributo [Required] se define mediante RequiredAttribute en el espacio de nombres Microsoft.Build.Framework.
Cómo MSBuild invoca una tarea
Al invocar una tarea, MSBuild crea primero una instancia de la clase de tarea y, a continuación, llama a los establecedores de propiedades de ese objeto para los parámetros de tarea que se establecen en el elemento de tarea del archivo de proyecto. Si el elemento de tarea no especifica un parámetro o si la expresión especificada en el elemento se evalúa como una cadena vacía, no se llama al establecedor de propiedades.
Por ejemplo, en el proyecto
<Project>
<Target Name="InvokeCustomTask">
<CustomTask Input1=""
Input2="$(PropertyThatIsNotDefined)"
Input3="value3" />
</Target>
</Project>
Solo se llama al establecedor para Input3.
Una tarea no debe depender de ningún orden relativo de invocación de establecedor de propiedad de parámetros.
Tipos de parámetros de tarea
MSBuild controla de forma nativa las propiedades de tipo string, bool, ITaskItem y ITaskItem[]. Si una tarea acepta un parámetro de un tipo diferente, MSBuild invoca ChangeType para convertir de string (con todas las referencias de propiedades y elementos expandidas) al tipo de destino. Si se produce un error en la conversión para cualquier parámetro de entrada, MSBuild emite un error y no llama al método Execute() de la tarea.
Empaquetado de la tarea
La manera recomendada de distribuir una tarea está en un paquete NuGet. El paquete debe agrupar todas las dependencias. Este tema se explica exhaustivamente en un tutorial que le guía a través de la creación de una tarea personalizada. Consulte Creación de un paquete NuGet.
Ejemplo 1
Descripción
Esta siguiente clase de C# muestra una tarea derivada de la clase auxiliar Task. Esta tarea devuelve true, lo que indica que se realizó 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 2
Descripción
Esta siguiente clase de C# muestra una tarea que implementa la interfaz ITask. Esta tarea devuelve true, lo que indica que se realizó 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.
public IBuildEngine BuildEngine { get; set; }
// 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.
public object HostObject { get; set; }
public bool Execute()
{
// This is where the task would presumably do its work.
return true;
}
}
}
Ejemplo 3
Descripción
Esta clase de C# muestra una tarea que deriva de la clase auxiliar Task. Tiene una propiedad de cadena necesaria y genera un evento que todos los registradores registrados muestran.
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 4
Descripción
En el ejemplo siguiente se muestra un archivo de proyecto que invoca la tarea de ejemplo anterior, SimpleTask3.
Código
<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>