Pisanie zadań
Zadania zapewniają kod uruchamiany podczas procesu kompilacji. Zadania są zawarte w elementach docelowych. Biblioteka typowych zadań jest dołączona do programu MSBuild i można również tworzyć własne zadania. Aby uzyskać więcej informacji na temat biblioteki zadań dołączonych do programu MSBuild, zobacz Informacje o zadaniach.
Zadania
Przykłady zadań to Kopiowanie, które kopiuje co najmniej jeden plik, MakeDir, który tworzy katalog i Csc, który kompiluje pliki kodu źródłowego C#. Każde zadanie jest implementowane jako klasa platformy .NET, która implementuje ITask interfejs zdefiniowany w zestawie Microsoft.Build.Framework.dll .
Istnieją dwa podejścia, których można użyć podczas implementowania zadania:
Zaimplementuj ITask interfejs bezpośrednio.
Utwórz klasę na podstawie klasy Taskpomocniczej , która jest zdefiniowana w zestawie Microsoft.Build.Utilities.dll . Zadanie implementuje ITask i zapewnia domyślne implementacje niektórych elementów członkowskich ITask. Ponadto rejestrowanie jest łatwiejsze.
W obu przypadkach należy dodać do klasy metodę o nazwie Execute, czyli metodę wywoływaną podczas uruchamiania zadania. Ta metoda nie przyjmuje parametrów i zwraca Boolean wartość: true jeśli zadanie zakończyło się pomyślnie lub false jeśli zakończyło się niepowodzeniem. W poniższym przykładzie pokazano zadanie, które nie wykonuje żadnej akcji i kończy się pomyślnie (zwraca wartość true).
using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace MyTasks
{
public class SimpleTask : Task
{
public override bool Execute()
{
return true;
}
}
}
Następujący plik projektu uruchamia to zadanie:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask />
</Target>
</Project>
Po uruchomieniu zadań mogą również odbierać dane wejściowe z pliku projektu, jeśli tworzysz właściwości platformy .NET w klasie zadań. Program MSBuild ustawia te właściwości bezpośrednio przed wywołaniem metody zadania Execute . Aby utworzyć właściwość ciągu, użyj kodu zadania, takiego jak:
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; }
}
}
Następujący plik projektu uruchamia to zadanie i ustawia MyProperty na daną wartość:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="MyTarget">
<SimpleTask MyProperty="Value for MyProperty" />
</Target>
</Project>
Rejestrowanie zadań
Jeśli projekt ma uruchomić zadanie, program MSBuild musi wiedzieć, jak zlokalizować i uruchomić zestaw zawierający klasę zadań. Zadania są rejestrowane przy użyciu elementu UsingTask (MSBuild).
Jeśli zadanie ma zależności specyficzne dla środowiska uruchomieniowego, należy poinformować program MSBuild, że powinno ono uruchomić zadanie w określonym środowisku, wskazując element Architecture i/lub Runtime w elemencie UsingTask.
Plik MSBuild Microsoft.Common.tasks to plik projektu zawierający listę UsingTask elementów rejestrujących wszystkie zadania dostarczane z programem MSBuild. Ten plik jest automatycznie dołączany podczas kompilowania dowolnego projektu. Jeśli zadanie zarejestrowane w pliku Microsoft.Common.tasks jest również zarejestrowane w bieżącym pliku projektu, bieżący plik projektu ma pierwszeństwo, dzięki czemu można zastąpić zadanie domyślne własnym zadaniem o tej samej nazwie.
Napiwek
Możesz wyświetlić listę zadań dostarczanych z określoną wersją programu MSBuild, wyświetlając zawartość jego pliku Microsoft.Common.tasks.
Zgłaszanie zdarzeń z zadania
Jeśli zadanie pochodzi z klasy pomocniczej Task , możesz użyć dowolnej z następujących metod pomocnika w Task klasie, aby zgłosić zdarzenia, które zostaną przechwycone i wyświetlone przez zarejestrowane rejestratory:
public override bool Execute()
{
Log.LogError("messageResource1", "1", "2", "3");
Log.LogWarning("messageResource2");
Log.LogMessage(MessageImportance.High, "messageResource3");
...
}
Jeśli zadanie implementuje ITask się bezpośrednio, nadal można zgłaszać takie zdarzenia, ale musisz użyć interfejsu IBuildEngine. W poniższym przykładzie pokazano zadanie, które implementuje ITask i zgłasza zdarzenie niestandardowe:
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;
}
}
Wymagaj ustawienia parametrów zadania
Niektóre właściwości zadania można oznaczyć jako "wymagane", aby każdy plik projektu, który uruchamia zadanie, musi ustawić wartości dla tych właściwości lub kompilacja kończy się niepowodzeniem. [Required] Zastosuj atrybut do właściwości .NET w zadaniu w następujący sposób:
[Required]
public string RequiredProperty { get; set; }
Atrybut [Required] jest definiowany przez RequiredAttribute element Microsoft.Build.Framework w przestrzeni nazw.
Jak program MSBuild wywołuje zadanie
Podczas wywoływania zadania program MSBuild najpierw tworzy wystąpienie klasy zadań, a następnie wywołuje zestawy właściwości tego obiektu dla parametrów zadań ustawionych w elemecie zadania w pliku projektu. Jeśli element zadania nie określi parametru lub jeśli wyrażenie określone w elemecie zwróci wartość pustego ciągu, zestaw właściwości nie jest wywoływany.
Na przykład w projekcie
<Project>
<Target Name="InvokeCustomTask">
<CustomTask Input1=""
Input2="$(PropertyThatIsNotDefined)"
Input3="value3" />
</Target>
</Project>
wywoływana jest tylko właściwość setter dla Input3 .
Zadanie nie powinno zależeć od względnej kolejności wywołania właściwości parametrów.
Typy parametrów zadania
Program MSBuild natywnie obsługuje właściwości typu string, boolITaskItem i ITaskItem[]. Jeśli zadanie akceptuje parametr innego typu, program MSBuild wywołuje ChangeType metodę konwersji z string (ze wszystkimi odwołaniami do właściwości i elementów rozszerzonymi) na typ docelowy. Jeśli konwersja nie powiedzie się dla dowolnego parametru wejściowego, program MSBuild emituje błąd i nie wywołuje metody zadania Execute() .
Pakowanie zadania
Zalecanym sposobem dystrybucji zadania jest pakiet NuGet. Pakiet musi zawierać wszystkie zależności. Ten temat został dokładnie wyjaśniony w samouczku, który przeprowadzi Cię przez proces tworzenia zadania niestandardowego. Zobacz Tworzenie pakietu NuGet.
Przykład 1
opis
W poniższej klasie języka C# pokazano zadanie pochodzące z klasy pomocniczej Task . To zadanie zwraca wartość truewskazującą, że powiodło się.
Kod
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;
}
}
}
Przykład 2
opis
W poniższej klasie języka C# pokazano zadanie implementowania interfejsu ITask . To zadanie zwraca wartość truewskazującą, że powiodło się.
Kod
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;
}
}
}
Przykład 3
opis
Ta klasa języka C# demonstruje zadanie pochodzące z klasy pomocniczej Task . Ma wymaganą właściwość ciągu i zgłasza zdarzenie wyświetlane przez wszystkie zarejestrowane rejestratory.
Kod
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;
}
}
}
Przykład 4
opis
W poniższym przykładzie pokazano plik projektu wywołujący poprzednie przykładowe zadanie SimpleTask3.
Kod
<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>