Scrittura di attività
Le attività forniscono il codice che viene eseguito durante il processo di compilazione. Le attività sono contenute nelle destinazioni Con MSBuild viene fornita una libreria di attività più comuni, ma è possibile creare attività personalizzate. Per ulteriori informazioni sulla libreria di attività fornita con MSBuild, vedere Riferimenti delle attività MSBuild.
Attività
Alcuni esempi di attività sono Copy, che consente di copiare uno o più file, MakeDir, che consente di creare una directory e Csc, che consente di compilare il file con i codici sorgente in Visual C#. Ogni attività viene implementata come classe .NET che implementa l'interfaccia ITask, definita nell'assembly Microsoft.Build.Framework.dll.
Per implementare un'attività, è possibile utilizzare due approcci diversi:
Implementare direttamente l'interfaccia ITask.
Derivare la classe dalla classe di supporto Task, definita nell'assembly Microsoft.Build.Utilities.dll. L'attività implementa ITask e fornisce le implementazioni predefinite di alcuni membri di ITask. Inoltre, la registrazione è più semplice.
In entrambi i casi è necessario aggiungere alla propria classe un metodo denominato Execute, ossia il metodo che viene richiamato quando viene eseguita l'attività. Questo metodo non assume alcun parametro e restituisce un valore Boolean: true se l'attività ha esito positivo oppure false se ha esito negativo. Nell'esempio seguente è illustrata un'attività che non esegue alcuna azione e 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 seguente file di progetto esegue questa attività:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask />
</Target>
</Project>
Quando le attività vengono eseguite, possono ricevere anche input dal file di progetto se si creano proprietà .NET nella classe dell'attività. In MSBuild queste proprietà vengono impostate immediatamente prima di chiamare il metodo Execute dell'attività. Per creare una proprietà stringa utilizzare il codice 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;
}
private string myProperty;
public string MyProperty
{
get { return myProperty; }
set { myProperty = value; }
}
}
}
Il seguente file di progetto esegue questa attività e imposta MyProperty con un determinato valore:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask MyProperty="Value for MyProperty" />
</Target>
</Project>
Registrazione delle attività
Se il progetto dovrà essere in grado di eseguire un'attività, è necessario specificare in MSBuild come individuare l'assembly che contiene la classe dell'attività. Le attività vengono registrate tramite Elemento UsingTask (MSBuild).
Il file Microsoft.Common.Tasks di MSBuild è un file di progetto che contiene un elenco di elementi UsingTask che registrano tutte le attività fornite con MSBuild. Questo file viene incluso automaticamente ogni volta che si compila un progetto. Se l'attività registrata in Microsoft.Common.Tasks è anche registrata nel file di progetto corrente, il file di progetto corrente ha la precedenza, ossia è possibile sostituire un'attività predefinita con la propria attività avente lo stesso nome.
Suggerimento
Per visualizzare un elenco di attività fornite con MSBuild, visualizzare il contenuto di Microsoft.Common.Tasks.
Generazione di eventi da un'attività
Se l'attività deriva dalla classe di supporto Task, è possibile utilizzare un metodo di supporto qualsiasi nella classe Task per generare gli 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 direttamente ITask, è comunque possibile generare tali eventi ma occorre utilizzare l'interfaccia IBuildEngine. Nell'esempio riportato di seguito viene descritta un'attività che implementa ITask e genera un evento personalizzato:
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;
}
}
Impostazione di parametri di attività obbligatori
È possibile contrassegnare determinate proprietà dell'attività come "obbligatorie", in modo che tutti i file di progetto che eseguono l'attività debbano impostare i valori per tali proprietà, altrimenti la compilazione avrà esito negativo. Applicare nel modo seguente l'attributo [Required] alla proprietà .NET nell'attività:
private string requiredProperty;
[Required]
public string RequiredProperty
{
get { return requiredProperty; }
set { requiredProperty = value; }
}
L'attributo [Required] è definito da RequiredAttribute nello spazio dei nomi Microsoft.Build.Framework.
Esempio
Descrizione
La seguente classe di Visual C# illustra un'attività che deriva dalla classe di supporto Task. Questa attività restituisce true, ad indicare 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
Descrizione
La seguente classe di Visual C# illustra un'attività che implementa l'interfaccia ITask. Questa attività restituisce true, ad indicare 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.
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;
}
}
}
Esempio
Descrizione
La seguente classe di Visual C# illustra un'attività che deriva dalla classe di supporto Task. 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
Descrizione
Nell'esempio riportato di seguito viene illustrato un file di progetto che richiama l'attività dell'esempio precedente, SimpleTask3.
Codice
<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>