Pisanie zadań

  • Artykuł

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 .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() .

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>

Powiązana zawartość