Sdílet prostřednictvím

Psaní úkolů

  • Č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 Referenční informace o úloze.

Úkoly

Mezi příklady úkolů patří kopírovat, 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 rozhraní ITask, jež je definováno v sestavení Microsoft.Build.Framework.dll.

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

  • Přímo implementujte rozhraní ITask.

  • Odvoďte svou 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í hodnotu Boolean: 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. MSBuild tyto vlastnosti nastaví bezprostředně před voláním metody Execute úlohy. Pokud chcete vytvořit vlastnost řetězce, použijte kód úlohy, jako 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 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 jsou registrovány pomocí UsingTask element (MSBuild).

Pokud má vaše úloha závislosti specifické pro modul runtime, musíte informovat nástroj MSBuild, že by měl spustit úlohu v konkrétním prostředí označující Architecture a/nebo Runtime v jehoUsingTask .

Soubor MSBuild Microsoft.Common.tasks je soubor projektu, který obsahuje seznam UsingTask elementů, které registrují všechny úkoly, které jsou součástí 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á aktuální soubor projektu přednost, takže můžete přepsat výchozí úkol vlastním úkolem, který má stejný název.

Spropitné

Seznam úkolů, které jsou dodány s konkrétní verzí nástroje MSBuild, můžete zobrazit zobrazením obsahu jeho Microsoft.Common.tasks.

Vyvolejte události z úkolu

Pokud je úkol odvozený z pomocné třídy Task, můžete v Task třídě použít některou z následujících pomocných metod 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. Na vlastnost .NET v úloze použijte atribut [Required] následujícím způsobem:

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

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

Jak MSBuild spustí ú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 pro 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, bool, ITaskItem a ITaskItem[]. Pokud úloha přijme parametr jiného typu, nástroj MSBuild vyvolá ChangeType pro převod z string (s rozbalenými odkazy na všechny vlastnosti a položky) 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.

Zabalení úkolu

Doporučený způsob distribuce úlohy je v balíčku NuGet. Balíček musí zahrnovat všechny závislosti. Toto téma je podrobně vysvětleno v kurzu, který vás provede vytvořením vlastní úlohy. Viz Vytvoření balíčku NuGet.

Příklad 1

Popis

Následující třída jazyka C# ukazuje úlohu odvozenou z pomocné třídy Task. Tento úkol vrátí true, což znamená, že bylo ú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, která implementuje ITask rozhraní. Tento úkol vrátí true, což znamená, že bylo ú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 úlohu, která je odvozena z pomocné třídy Task. 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