Scrittura di attività

  • Articolo

Le attività forniscono il codice che viene eseguito durante il processo di compilazione. Le attività sono contenute nelle destinazioni. Una libreria di attività tipiche è inclusa in MSBuild ed è anche possibile creare attività personalizzate. Per altre informazioni sulla libreria di attività incluse in MSBuild, vedere Informazioni di riferimento sulle attività.

Attività

Esempi di attività includono Copy, che copia uno o più file, MakeDir, che crea una directory e Csc, che compila i file di codice sorgente C#. Ogni attività viene implementata come classe .NET che implementa l'interfaccia ITask, definita nell'assembly Microsoft.Build.Framework.dll.

È possibile implementare un'attività in due modi:

  • Implementare direttamente l'interfaccia ITask.

  • Derivare la classe dalla classe Taskhelper , definita nell'assembly Microsoft.Build.Utilities.dll . L'attività implementa ITask e specifica le implementazioni predefinite di alcuni membri di ITask. Inoltre, la registrazione è più semplice.

In entrambi i casi è necessario aggiungere alla classe un metodo denominato Execute, ovvero il metodo che viene chiamato quando l'attività è in esecuzione. Questo metodo non accetta parametri e restituisce un valore Boolean: true se l'attività ha avuto esito positivo o false se ha avuto esito negativo. Nell'esempio seguente viene illustrata un'attività che non esegue alcuna azione e viene completata correttamente (restituisce true).

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

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

Il file di progetto seguente esegue questa attività:

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

Durante l'esecuzione, le attività possono anche ricevere input dal file di progetto se si creano proprietà .NET per la classe dell'attività. MSBuild imposta queste proprietà immediatamente prima di chiamare il metodo dell'attività Execute . Per creare una proprietà stringa, usare il codice dell'attività, ad esempio:

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

Il seguente file di progetto esegue questa attività e imposta MyProperty sul valore specificato:

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

Registrazione di attività

Se un progetto eseguirà un'attività, MSBuild deve sapere come individuare ed eseguire l'assembly che contiene la classe task. Le attività vengono registrate usando l'elemento UsingTask (MSBuild).

Se l'attività ha dipendenze specifiche del runtime, è necessario informare MSBuild che deve eseguire l'attività in un ambiente specifico indicando e Architecture /o Runtime nel relativo UsingTask.

Il file MSBuild Microsoft.Common.tasks è un file di progetto che contiene un elenco di UsingTask elementi che registrano tutte le attività fornite con MSBuild. Questo file viene incluso automaticamente durante la compilazione di un progetto. Se anche un'attività registrata in Microsoft.Common.tasks viene registrata nel file di progetto corrente, il file di progetto corrente ha la precedenza, in modo da poter eseguire l'override di un'attività predefinita con la propria attività con lo stesso nome.

Suggerimento

È possibile visualizzare un elenco delle attività fornite con una versione specifica di MSBuild visualizzando il contenuto delle attività Microsoft.Common.tasks.

Generazione di eventi da un'attività

Se l'attività deriva dalla classe helper Task, è possibile usare uno qualsiasi dei seguenti metodi helper per la classe Task per generare eventi che verranno intercettati e visualizzati da tutti i logger registrati:

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

Se l'attività implementa ITask direttamente, è comunque possibile generare tali eventi, ma è necessario usare l'interfaccia IBuildEngine. Nell'esempio seguente viene illustrata un'attività che implementa ITask e genera un evento personalizzato:

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

Richiesta dell'impostazione dei parametri dell'attività

È possibile contrassegnare determinate proprietà dell'attività come "obbligatorie" in modo che i file di progetto che eseguono l'attività siano obbligati a impostare valori per queste proprietà altrimenti la compilazione non riesce. Applicare l'attributo [Required] alla proprietà .NET nell'attività come segue:

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

L'attributo [Required] è definito da RequiredAttribute nello spazio dei nomi Microsoft.Build.Framework.

Come MSBuild richiama un'attività

Quando si richiama un'attività, MSBuild crea innanzitutto un'istanza della classe task, quindi chiama i setter di proprietà dell'oggetto per i parametri attività impostati nell'elemento task nel file di progetto. Se l'elemento task non specifica un parametro o se l'espressione specificata nell'elemento restituisce una stringa vuota, il setter della proprietà non viene chiamato.

Ad esempio, nel progetto

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

viene chiamato solo il setter per Input3 .

Un'attività non deve dipendere da un ordine relativo di chiamata al setter della proprietà dei parametri.

Tipi di parametri dell'attività

MSBuild gestisce in modo nativo le proprietà di tipo string, ITaskItemboole ITaskItem[]. Se un'attività accetta un parametro di un tipo diverso, MSBuild richiama ChangeType per eseguire la conversione da string (con tutti i riferimenti a proprietà e elementi espansi) al tipo di destinazione. Se la conversione non riesce per qualsiasi parametro di input, MSBuild genera un errore e non chiama il metodo dell'attività Execute() .

Esempio 1

Descrizione

Questa classe C# seguente illustra un'attività che deriva dalla Task classe helper. L'attività restituisce true, che indica che ha avuto esito positivo.

Codice

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

Esempio 2

Descrizione

Questa classe C# seguente illustra un'attività che implementa l'interfaccia ITask . L'attività restituisce true, che indica che ha avuto esito positivo.

Codice

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

Esempio 3

Descrizione

Questa classe C# illustra un'attività che deriva dalla Task classe helper. Ha una proprietà stringa obbligatoria e genera un evento che viene visualizzato da tutti i logger registrati.

Codice

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

Esempio 4

Descrizione

L'esempio seguente illustra un file di progetto che richiama l'attività dell'esempio precedente, SimpleTask3.

Codice

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

Contenuto correlato