Udostępnij za pośrednictwem

Pisanie zadań

  • Artykuł

Zadania dostarczają kod uruchamiany podczas procesu budowania. 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 Dokumentacja zadań.

Zadania

Przykłady zadań obejmują Copy, który kopiuje jeden lub więcej plików, MakeDir, który tworzy katalog, i Csc, który kompiluje pliki kodu źródłowego C#. Każde zadanie jest implementowane jako klasa .NET, która implementuje interfejs ITask zdefiniowany w zestawie Microsoft.Build.Framework.dll.

Istnieją dwa podejścia, których można użyć podczas implementowania zadania:

  • Zaimplementuj interfejs ITask bezpośrednio.

  • Utwórz klasę na podstawie klasy pomocniczej Task, która jest zdefiniowana w zestawie Microsoft.Build.Utilities.dll. Zadanie implementuje ITask i zapewnia domyślne implementacje niektórych członków 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 żadnych parametrów i zwraca wartość Boolean: true, jeśli zadanie zakończyło się pomyślnie lub false w przypadku niepowodzenia. W poniższym przykładzie pokazano zadanie, które nie wykonuje żadnej akcji i kończy się pomyślnie (zwraca 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 Execute zadania. 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ć MSBuild, że powinno ono uruchomić zadanie w określonym środowisku przez wskazanie Architecture i/lub Runtime w UsingTask.

Plik MSBuild Microsoft.Common.tasks to plik projektu zawierający listę elementów UsingTask rejestrujących wszystkie zadania dostarczane z programem MSBuild. Ten plik jest automatycznie dołączany podczas kompilowania dowolnego projektu. Jeśli zadanie zarejestrowane w 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 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 klasie Task, 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 bezpośrednio, nadal można zgłaszać takie zdarzenia, ale należy użyć interfejsu IBuildEngine. W poniższym przykładzie przedstawiono zadanie, które implementuje ITask i wywołuje zdarzenie własne.

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. Zastosuj atrybut [Required] 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 w przestrzeni nazw Microsoft.Build.Framework.

Jak program MSBuild wywołuje zadanie

Podczas wywoływania zadania program MSBuild najpierw tworzy wystąpienie klasy zadania, a następnie wywołuje ustawienia właściwości tego obiektu dla parametrów zadania ustawionych w elemencie 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 funkcja ustawiająca (setter) dla Input3.

Zadanie nie powinno zależeć od żadnej relatywnej kolejności wywołania ustawień właściwości parametrów.

Typy parametrów zadania

Program MSBuild natywnie obsługuje właściwości typu string, bool, ITaskItem i ITaskItem[]. Jeśli zadanie akceptuje parametr innego typu, program MSBuild wywołuje ChangeType, aby przekonwertować z string (ze wszystkimi odwołaniami do właściwości i elementów rozwiniętymi) do typu docelowego. Jeśli konwersja nie powiedzie się dla dowolnego parametru wejściowego, program MSBuild emituje błąd i nie wywołuje metody Execute() zadania.

Pakowanie zadania

Zalecanym sposobem dystrybucji zadania jest pakiet NuGet. Pakiet musi zawierać wszystkie zależności. Temat ten jest szczegółowo omówiony w samouczku, który przeprowadzi Cię przez tworzenie zadania dostosowanego do potrzeb. Zobacz Tworzenie pakietu NuGet.

Przykład 1

Opis

Ta następująca klasa języka C# demonstruje zadanie pochodzące z klasy pomocniczej Task. To zadanie zwraca true, co oznacza, ż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# przedstawiono zadanie implementowania interfejsu ITask. To zadanie zwraca true, co oznacza, ż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, które jest 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>

Powiązana zawartość