Zápis úkolů pro MSBuild

Úlohy jsou obsaženy v cílech MSBuild a poskytují kód, který se spouští během procesu sestavení. Nástroj MSBuild obsahuje knihovnu typických úloh a můžete také vytvořit vlastní úlohy. Další informace o knihovně úloh obsažené v MSBuild najdete v tématu Odkaz na úlohy MSBuild.

Požadavky

Projekt sady Visual Studio, který se sestavuje pomocí nástroje MSBuild.

Úkoly

Mezi příklady úloh NÁSTROJE MSBuild patří copy, 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í definované v Microsoft.Build.Framework.dll sestavení.

Při implementaci úlohy můžete použít některý z následujících přístupů:

  • 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. Task implementuje ITask a poskytuje výchozí implementace některých ITask členů. Protokolování je také jednodušší.

V obou případech musíte přidat metodu do vaší třídy s názvem Execute, 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, úspěšně dokončí 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 MSBuild spustí předchozí úlohu:

<Project>
    <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 úkolu, například následující pří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>
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Jak MSBuild vyvolává úlohy

Když NÁSTROJ MSBuild vyvolá úlohu, 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 se výraz zadaný v elementu vyhodnotí jako prázdný řetězec, není volána vlastnost setter.

Například v následujícím projektu se volá pouze setter for Input3 .

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

Úloha by neměla 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á ChangeType převod z string, se všemi vlastnostmi a odkazy na položky rozbalené, na cílový typ. Pokud převod selže pro jakýkoli vstupní parametr, nástroj MSBuild vyvolá chybu a nevolá metodu Execute() úlohy.

Registrace úkolů

Chcete-li spustit úlohu, MSBuild musí vědět, jak najít 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 směrovat nástroj MSBuild ke spuštění úlohy v určitém prostředí tím, že indikuje Architecture nebo Runtime atributy v jeho UsingTask prvku. Další informace naleznete v tématu atributy UsingTask a parametry úkolů.

Soubor MSBuild Microsoft.Common.tasks je projektový soubor se seznamem UsingTask prvků, které registrují všechny úkoly dodané s MSBuild. Tento soubor se automaticky zahrne, když MSBuild sestaví libovolný projekt. Pokud je v aktuálním souboru projektu zaregistrovaný také úkol zaregistrovaný v microsoft.Common.tasks , bude mít přednost aktuální soubor projektu, takže můžete přepsat výchozí úkol vlastním úkolem se stejným názvem.

Spropitné

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

Vyžadovat, aby byly nastaveny vlastnosti úkolu

Určité vlastnosti úkolu můžete označit jako povinné, takže každý soubor projektu, který spouští úlohu, musí 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.

Vyvolejte události 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í zachycených a zobrazených 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 přesto vyvolat, ale musíte použít IBuildEngine rozhraní. Následující příklad ukazuje úlohu, která implementuje ITask a vyvolává 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;
    }
}

Zabalení úkolu

Doporučený způsob distribuce úlohy je v balíčku NuGet. Balíček musí zahrnovat všechny závislosti. Kurz, který vás provede vytvořením vlastní úlohy, najdete v tématu Vytvoření balíčku NuGet.

Příklad 1

Následující třída jazyka C# ukazuje úlohu odvozenou z Task pomocné třídy. Tento úkol vrátí true, což znamená, že bylo úspěšné.

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

Následující třída jazyka C# ukazuje úlohu, která implementuje ITask rozhraní. Tento úkol vrátí true, což znamená, že bylo úspěšné.

using System;
using Microsoft.Build.Framework;

namespace SimpleTask2
{
    public class SimpleTask2: ITask
    {
        //When implementing the ITask interface, it's 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's 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 does its work.
            return true;
        }
    }
}

Příklad 3

Tato třída jazyka C# ukazuje úlohu, která je odvozena z pomocné třídy Task. Úloha má požadovanou vlastnost řetězce a vyvolá událost zobrazenou všemi registrovanými protokolovacími rutinami.

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

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

<Project>
    <UsingTask TaskName="SimpleTask3.SimpleTask3"
        AssemblyFile="SimpleTask3\bin\debug\simpletask3.dll"/>

    <Target Name="MyTarget">
        <SimpleTask3 MyProperty="Hello!"/>
    </Target>
</Project>

Související obsah

  • Last updated on