Zápis úloh

Úlohy poskytují kód, který se spouští během procesu sestavení. Úkoly jsou obsaženy v cílech. k dispozici je knihovna typických úloh, které jsou součástí MSBuild, a můžete také vytvářet vlastní úkoly. další informace o knihovně úloh, které jsou součástí MSBuild, naleznete v tématu Task reference.

Úkoly

Mezi příklady úloh patří kopírování, které kopíruje jeden nebo více souborů, MakeDir –, které vytvoří adresář a CSC, který kompiluje soubory zdrojového kódu jazyka C#. Každá úloha je implementována jako třída .NET, která implementuje ITask rozhraní, které je definováno v sestavení Microsoft.Build.Framework.dll .

Existují dva přístupy, které můžete použít při implementaci úlohy:

  • Implementujte ITask rozhraní přímo.

  • Odvodit třídu z pomocné třídy, Task , která je definována v sestavení Microsoft.Build.Utilities.dll . Úloha implementuje ITask a poskytuje výchozí implementace některých ITask členů. Protokolování je navíc jednodušší.

V obou případech je nutné přidat do třídy a metodu s názvem Execute , což je metoda, která je volána při spuštění úlohy. Tato metoda nepřijímá žádné parametry a vrací Boolean hodnotu: true Pokud úloha proběhla úspěšně, nebo false Pokud se nezdařila. Následující příklad ukazuje úlohu, která neprovede žádnou akci a vrátí true .

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace MyTasks
{
    public class SimpleTask : Task
    {
        public override bool Execute()
        {
            return true;
        }
    }
}

Následující soubor projektu spouští tuto úlohu:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <SimpleTask />
    </Target>
</Project>

Když jsou spouštěny úlohy, mohou také přijímat vstupy ze souboru projektu, pokud vytvoříte vlastnosti rozhraní .NET pro třídu Task. MSBuild tyto vlastnosti nastaví těsně před voláním metody úkolu Execute . Chcete-li vytvořit řetězcovou vlastnost, použijte kód úlohy, například:

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; }
    }
}

Následující soubor projektu spustí tuto úlohu a nastaví MyProperty na danou hodnotu:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Registrovat úlohy

pokud projekt spustí úlohu, MSBuild musí znát, jak najít sestavení, které obsahuje třídu task. Úkoly jsou registrovány pomocí elementu UsingTask (MSBuild).

soubor MSBuild Microsoft. Common. tasks je soubor projektu, který obsahuje seznam UsingTask prvků, které registrují všechny úkoly, které jsou součástí MSBuild. Tento soubor je automaticky zahrnut při sestavování všech projektů. Pokud úkol, který je zaregistrován v Microsoft. Common. Tasks , je zaregistrován také v aktuálním souboru projektu, aktuální soubor projektu má přednost. To znamená, že můžete přepsat výchozí úkol vlastní úlohou, která má stejný název.

Tip

seznam úkolů dodaných s MSBuild zobrazíte zobrazením obsahu Microsoft. Common. tasks.

Vyvolání událostí z úkolu

Pokud je úloha odvozena z Task pomocné třídy, můžete použít jakoukoli z následujících pomocných metod Task třídy k vyvolání událostí, které budou zachyceny a zobrazeny všemi registrovanými protokolovacími nástroji:

public override bool Execute()
{
    Log.LogError("messageResource1", "1", "2", "3");
    Log.LogWarning("messageResource2");
    Log.LogMessage(MessageImportance.High, "messageResource3");
    ...
}

Pokud úloha přímo implementuje ITask , můžete i nadále vyvolávat takové události, ale je nutné použít rozhraní IBuildEngine. Následující příklad ukazuje úlohu, která implementuje ITask a vyvolá vlastní událost:

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;
    }
}

Vyžadovat nastavení parametrů úkolu

Některé vlastnosti úlohy můžete označit jako "požadováno", aby všechny soubory projektu, které spouštějí úlohu, musely nastavovat hodnoty pro tyto vlastnosti nebo sestavení selhalo. Použijte [Required] atribut na vlastnost .NET v úkolu následujícím způsobem:

[Required]
public string RequiredProperty { get; set; }

[Required]Atribut je definován RequiredAttribute v Microsoft.Build.Framework oboru názvů.

způsob, jakým MSBuild vyvolá úlohu

když vyvolá úlohu, MSBuild nejprve vytvoří instanci třídy task a pak zavolá metodu setter vlastností tohoto objektu pro parametry úlohy, které jsou nastaveny v elementu task v souboru projektu. Pokud element Task nespecifikuje parametr, nebo pokud je výraz zadaný v elementu vyhodnocen jako prázdný řetězec, vlastnost setter není volána.

Například v projektu

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

je volána pouze metoda setter pro Input3 .

Úkol by neměl záviset na jakémkoli pořadí volání setter vlastnosti parametru.

Typy parametrů úlohy

MSBuild nativně zpracovává vlastnosti typu string , bool , ITaskItem a ITaskItem[] . pokud úkol akceptuje parametr jiného typu, MSBuild vyvolá ChangeType převod z string (se všemi rozbalenými odkazy na vlastnosti a položky) na cílový typ. pokud se převod nezdařil pro jakýkoliv vstupní parametr, MSBuild emituje chybu a nevolá Execute() metodu úkolu.

Příklad 1

Popis

Tato následující třída jazyka C# ukazuje úlohu odvozenou z Task pomocné třídy. Tato úloha vrátí hodnotu true , která označuje, že byla úspěšná.

Kód

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;
        }
    }
}

Příklad 2

Popis

Tato následující třída jazyka C# ukazuje úlohu implementující ITask rozhraní. Tato úloha vrátí hodnotu true , která označuje, že byla úspěšná.

Kód

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;
        }
    }
}

Příklad 3

Popis

Tato třída jazyka C# ukazuje úkol, který je odvozen z Task pomocné třídy. Má požadovanou řetězcovou vlastnost a vyvolá událost, která se zobrazí ve všech zaregistrovaných protokolovacích nástrojích.

Kód

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;
        }
    }
}

Příklad 4

Popis

Následující příklad ukazuje soubor projektu, který volá předchozí příklad úlohy SimpleTask3.

Kód

<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>

Viz také