Escritura de tareas para MSBuild

Las tareas se incluyen en destinos de MSBuild y proporcionan el código que se ejecuta durante el proceso de compilación. MSBuild incluye una biblioteca de tareas típicas y también puede crear sus propias tareas. Para obtener más información sobre la biblioteca de tareas que incluye MSBuild, consulte Referencia de tareas de MSBuild.

Prerrequisitos

Un proyecto de Visual Studio que se compila con MSBuild.

Tareas

Algunos ejemplos de tareas de MSBuild son 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 ITask interfaz definida en el ensamblado Microsoft.Build.Framework.dll .

Puede usar cualquiera de los enfoques siguientes 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. Task implementa ITask y proporciona implementaciones predeterminadas de algunos miembros de ITask. El registro también es más fácil.

En ambos casos, debe agregar un método a la clase denominada Execute, 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, se completa correctamente 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 siguiente archivo de proyecto de MSBuild ejecuta la tarea anterior:

<Project>
    <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 el ejemplo siguiente:

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>
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Cómo invoca MSBuild las tareas

Cuando MSBuild invoca una tarea, primero crea 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 task 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 siguiente proyecto, solo se llama al establecedor de Input3 .

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

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, boolITaskItemy ITaskItem[]. Si una tarea acepta un parámetro de un tipo diferente, MSBuild invoca ChangeType para convertir de string, con todas las referencias de propiedad y elemento 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 de Execute() la tarea.

Registrar tareas

Para ejecutar una tarea, MSBuild debe saber cómo localizar 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 dirigir a MSBuild para ejecutar la tarea en un entorno específico indicando los atributos Architecture o Runtime en su elemento UsingTask. Para obtener más información, consulte UsingTask attributes and task parameters (Uso de atributos y parámetros de tarea).

El archivo de MSBuild Microsoft.Common.tasks es un archivo de proyecto que enumera los UsingTask elementos que registran todas las tareas proporcionadas con MSBuild. Este archivo se incluye automáticamente cuando MSBuild compila 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 con 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 archivo Microsoft.Common.tasks .

Requerir que se establezcan propiedades de tarea

Puede marcar determinadas propiedades de tarea según sea necesario, por lo 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.

Generación de eventos de una tarea

Si la tarea se deriva de la Task clase auxiliar, puede usar cualquiera de los siguientes métodos auxiliares en la Task clase para generar eventos detectados y mostrados por todos los registradores registrados:

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

Si ITask se implementa directamente en la tarea, todavía puede generar 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;
    }
}

Empaquetar la tarea

La manera recomendada de distribuir una tarea está en un paquete NuGet. El paquete debe agrupar todas las dependencias. Para ver un tutorial que le guiará a través de la creación de una tarea personalizada, consulte Creación de un paquete NuGet.

Ejemplo 1

La siguiente clase de C# muestra una tarea derivada de la Task clase auxiliar. Esta tarea devuelve true, lo que indica que se realizó correctamente.

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

La siguiente clase de C# muestra una tarea que implementa la ITask interfaz. Esta tarea devuelve true, lo que indica que se realizó correctamente.

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;
        }
    }
}

Ejemplo 3

Esta clase de C# muestra una tarea que deriva de la clase auxiliar Task. La tarea tiene una propiedad de cadena necesaria y genera un evento que se muestra en todos los registradores registrados.

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

En el ejemplo siguiente se muestra un archivo de proyecto que invoca la tarea de ejemplo anterior, SimpleTask3.

<Project>
    <UsingTask TaskName="SimpleTask3.SimpleTask3"
        AssemblyFile="SimpleTask3\bin\debug\simpletask3.dll"/>

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

Comentarios

Resultoulle útil esta páxina?

Last updated on 2025-12-12