Scrittura di attività

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à proprie. 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 helper , definita Task 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 queste proprietà immediatamente prima di chiamare il metodo Execute dell'attività. 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 di attività. 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 Architecture e/o nella relativa Runtime usingTask.

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

Suggerimento

È possibile visualizzare un elenco delle attività fornite con una versione specifica di MSBuild visualizzando il contenuto del relativo oggetto 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 di attività, quindi chiama i setter di proprietà dell'oggetto per i parametri dell'attività impostati nell'elemento attività nel file di progetto. Se l'elemento attività non specifica un parametro o se l'espressione specificata nell'elemento restituisce una stringa vuota, il setter di proprietà non viene chiamato.

Ad esempio, nel progetto

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

viene chiamato solo il metodo Input3 setter per .

Un'attività non deve dipendere da un ordine relativo di chiamata del setter di proprietà di parametro.

Tipi di parametro dell'attività

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

Esempio 1

Descrizione

Questa classe C# seguente illustra un'attività che deriva dalla classe Task 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 ITask l'interfaccia . 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 classe Task 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>

Vedi anche