Dela via

Skrivning av uppgifter

  • Artikel

Uppgifter tillhandahåller den kod som körs under byggprocessen. Uppgifter finns i mål. Ett bibliotek med vanliga uppgifter ingår i MSBuild och du kan också skapa egna uppgifter. Mer information om biblioteket med uppgifter som ingår i MSBuild finns i uppgiftsreferens.

Uppgifter

Exempel på uppgifter är Kopiera, som kopierar en eller flera filer, MakeDir, som skapar en katalog och Csc, som kompilerar C#-källkodsfiler. Varje uppgift implementeras som en .NET-klass som implementerar ITask-gränssnittet, som definieras i Microsoft.Build.Framework.dll sammansättning.

Det finns två metoder som du kan använda när du implementerar en uppgift:

  • Implementera ITask-gränssnittet direkt.

  • Härled klassen från hjälpklassen Task, som definieras i sammansättningen Microsoft.Build.Utilities.dll. Task implementerar ITask och tillhandahåller standardimplementeringar av vissa medlemmar i ITask. Dessutom är loggning enklare.

I båda fallen måste du lägga till en metod med namnet Executei klassen, vilket är den metod som anropas när aktiviteten körs. Den här metoden tar inga parametrar och returnerar ett Boolean värde: true om uppgiften lyckades eller false om den misslyckades. I följande exempel visas en uppgift som inte utför någon åtgärd och slutförs (returnerar true).

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

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

Följande projektfil kör den här uppgiften:

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

När aktiviteter körs kan de också ta emot indata från projektfilen om du skapar .NET-egenskaper i aktivitetsklassen. MSBuild anger dessa egenskaper omedelbart innan aktivitetens Execute-metod anropas. Om du vill skapa en strängegenskap använder du aktivitetskod som:

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

Följande projektfil kör den här uppgiften och anger MyProperty till det angivna värdet:

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

Registrera uppgifter

Om ett projekt ska köra en aktivitet måste MSBuild veta hur man hittar och kör sammansättningen som innehåller aktivitetsklassen. Uppgifter registreras med hjälp av elementet UsingTask (MSBuild).

Om din uppgift har körspecifika beroenden måste du informera MSBuild om att det ska köra uppgiften i en specifik miljö genom att angiver Architecture och/eller Runtime i dess UsingTask.

MSBuild-filen Microsoft.Common.tasks är en projektfil som innehåller en lista över UsingTask element som registrerar alla uppgifter som medföljer MSBuild. Den här filen inkluderas automatiskt när du skapar ett projekt. Om en aktivitet som är registrerad i Microsoft.Common.tasks också är registrerad i den aktuella projektfilen har den aktuella projektfilen företräde, så att du kan åsidosätta en standardaktivitet med din egen uppgift som har samma namn.

Tips

Du kan se en lista över de uppgifter som levereras med en viss version av MSBuild genom att visa innehållet i dess Microsoft.Common.tasks.

Skapa händelser från en aktivitet

Om din uppgift härleds från hjälpklassen Task kan du använda någon av följande hjälpmetoder i klassen Task för att skapa händelser som fångas och visas av registrerade loggare:

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

Om din uppgift implementerar ITask direkt kan du fortfarande skapa sådana händelser, men du måste använda gränssnittet IBuildEngine. I följande exempel visas en uppgift som implementerar ITask och genererar en anpassad händelse:

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

Kräv att aktivitetsparametrar anges

Du kan markera vissa aktivitetsegenskaper som "obligatoriska" så att alla projektfiler som kör aktiviteten måste ange värden för dessa egenskaper, annars misslyckas bygget. Använd attributet [Required] för .NET-egenskapen i din uppgift på följande sätt:

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

Attributet [Required] definieras av RequiredAttribute i namnområdet Microsoft.Build.Framework.

Så här anropar MSBuild en uppgift

När du anropar en aktivitet instansierar MSBuild först aktivitetsklassen och anropar sedan objektets egenskapsuppsättningar för uppgiftsparametrar som anges i aktivitetselementet i projektfilen. Om aktivitetselementet inte anger någon parameter, eller om uttrycket som anges i elementet utvärderas till en tom sträng, anropas inte egenskapsinställningen.

Till exempel i projektet

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

endast setter för Input3 anropas.

En uppgift ska inte vara beroende av någon relativ ordning på parameter-property setter-anrop.

Typer av aktivitetsparameter

MSBuild hanterar internt egenskaper av typen string, bool, ITaskItem och ITaskItem[]. Om en uppgift accepterar en parameter av en annan typ anropar MSBuild ChangeType att konvertera från string (med alla egenskaps- och objektreferenser expanderade) till måltypen. Om konverteringen misslyckas för någon indataparameter genererar MSBuild ett fel och anropar inte aktivitetens Execute()-metod.

Paketera uppgiften

Det rekommenderade sättet att distribuera en uppgift är i ett NuGet-paket. Paketet måste paketera alla beroenden. Det här avsnittet beskrivs noggrant i en självstudiekurs som vägleder dig genom att skapa en anpassad uppgift. Se Skapa ett NuGet-paket.

Exempel 1

Beskrivning

Följande C#-klass visar en uppgift som härleds från hjälpklassen Task. Den här aktiviteten returnerar truesom anger att den lyckades.

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

Exempel 2

Beskrivning

Följande C#-klass visar en uppgift som implementerar ITask-gränssnittet. Den här aktiviteten returnerar truesom anger att den lyckades.

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

Exempel 3

Beskrivning

Den här C#-klassen visar en uppgift som härleds från hjälpklassen Task. Den har en obligatorisk strängegenskap och genererar en händelse som visas av alla registrerade loggare.

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

Exempel 4

Beskrivning

I följande exempel visas en projektfil som anropar föregående exempelaktivitet, 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>

Relaterat innehåll