Zápis úloh

  • Článek

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

Úlohy

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 .

Při implementaci úlohy můžete použít dva přístupy:

  • 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 členů ITask. Protokolování je navíc jednodušší.

V obou případech musíte do třídy přidat metodu s názvem Execute, což je metoda, která se volá 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 selhala. Následující příklad ukazuje úlohu, která neprovede žádnou akci a úspěšně se dokončí (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 spustí tuto úlohu:

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

Při spuštění úkolů mohou také přijímat vstupy ze souboru projektu, pokud vytvoříte vlastnosti .NET ve třídě úloh. NÁSTROJ MSBuild tyto vlastnosti nastaví bezprostředně před voláním metody úlohy Execute . Pokud chcete vytvořit vlastnost řetězce, použijte kód úkolu, 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í tento úkol a nastaví MyProperty se na danou hodnotu:

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

Registrace úkolů

Pokud projekt spustí úlohu, nástroj MSBuild musí vědět, jak vyhledat a spustit sestavení, které obsahuje třídu úlohy. Úlohy se registrují pomocí elementu UsingTask (MSBuild).

Pokud má vaše úloha závislosti specifické pro modul runtime, je nutné informovat nástroj MSBuild, že by měl spustit úlohu v určitém prostředí tím , že indikuje Architecture a/nebo Runtime v jeho usingTask.

Soubor MSBuild Microsoft.Common.tasks je soubor projektu, který obsahuje seznam UsingTask prvků, které registrují všechny úkoly, které jsou dodávány pomocí nástroje MSBuild. Tento soubor se automaticky zahrne při sestavování libovolného projektu. Pokud je úkol zaregistrovaný v microsoft.Common.tasks je také registrován v aktuálním souboru projektu, má přednost aktuální soubor projektu, takže můžete přepsat výchozí úkol vlastním úkolem, který má stejný název.

Tip

Zobrazí se seznam úkolů, které jsou dodávány s konkrétní verzí nástroje MSBuild, zobrazením obsahu jeho Microsoft.Common.tasks.

Vyvolání událostí z úkolu

Pokud je úkol odvozen od Task pomocné třídy, můžete použít některou z následujících pomocných metod třídy Task 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 vaše úloha implementuje ITask přímo, můžete tyto události stále vyvolat, ale musíte použít IBuildEngine rozhraní. 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

Určité vlastnosti úkolu můžete označit jako povinné, aby všechny soubory projektu, které spouští úlohu, musely nastavit hodnoty pro tyto vlastnosti nebo sestavení selže. [Required] Použijte atribut na vlastnost .NET ve vaší úloze následujícím způsobem:

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

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

Jak NÁSTROJ MSBuild vyvolá úlohu

Při vyvolání úkolu nástroj MSBuild nejprve vytvoří instanci třídy úkolu a potom zavolá vlastnosti tohoto objektu pro parametry úkolu, které jsou nastaveny v elementu úkolu v souboru projektu. Pokud prvek úkolu nezadá parametr nebo pokud výraz zadaný v elementu vyhodnotí 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>

Volá se pouze setter for Input3 .

Úkol by neměl záviset na žádném relativním pořadí vyvolání vlastnosti parametru.

Typy parametrů úkolů

Nástroj MSBuild nativně zpracovává vlastnosti typu string, boolITaskItem a ITaskItem[]. Pokud úkol přijímá parametr jiného typu, msBuild vyvolá převod z string (se všemi odkazy ChangeType na vlastnost a položky rozbalené) na cílový typ. Pokud převod selže u jakéhokoli vstupního parametru, nástroj MSBuild vygeneruje chybu a nevolá metodu Execute() úlohy.

Příklad 1

Popis

Následující třída jazyka C# ukazuje úlohu odvozenou z Task pomocné třídy. Tento úkol vrátí truehodnotu označující, že byl ú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

Následující třída jazyka C# ukazuje úlohu, která implementuje ITask rozhraní. Tento úkol vrátí truehodnotu označující, že byl ú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# demonstruje úlohu odvozenou z Task pomocné třídy. Má požadovanou vlastnost řetězce a vyvolá událost, která je zobrazena všemi registrovanými protokolovacími rutinami.

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ý vyvolá předchozí ukázkový úkol 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>

Související obsah