Share via

Penulisan tugas

  • Artikel

Tugas menyediakan kode yang berjalan selama proses build. Tugas ada dalam target. Pustaka tugas umum disertakan dengan MSBuild, dan Anda juga dapat membuat tugas Anda sendiri. Untuk informasi selengkapnya tentang pustaka tugas yang disertakan dengan MSBuild, lihat Referensi tugas.

Tugas

Contoh tugas mencakup Salin, yang menyalin satu atau beberapa file, MakeDir, yang membuat direktori, dan Csc, yang mengompilasi file kode sumber C#. Setiap tugas diimplementasikan sebagai kelas .NET yang mengimplementasikan antarmuka ITask, yang ditentukan dalam rakitan Microsoft.Build.Framework.dll.

Ada dua pendekatan yang dapat Anda gunakan saat menerapkan tugas:

  • Terapkan antarmuka secara ITask langsung.

  • Turunkan kelas Anda dari kelas pembantu Task, yang ditentukan dalam rakitan Microsoft.Build.Utilities.dll. Tugas mengimplementasikan ITask dan menyediakan implementasi default dari beberapa anggota ITask. Selain itu, pengelogan lebih mudah.

Dalam kedua kasus tersebut, Anda harus menambahkan ke kelas Anda sebuah metode bernama Execute, yang merupakan metode yang dipanggil saat tugas berjalan. Metode ini tidak menggunakan parameter dan mengembalikan nilai Boolean: true jika tugas berhasil atau false jika gagal. Contoh berikut menunjukkan tugas yang tidak melakukan tindakan apa pun dan berhasil diselesaikan (mengembalikan true).

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

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

File proyek berikut menjalankan tugas ini:

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

Saat tugas berjalan, tugas juga dapat menerima input dari file proyek jika Anda membuat properti .NET pada kelas tugas. MSBuild mengatur properti ini segera sebelum memanggil metode Execute tugas. Untuk membuat properti string, gunakan kode tugas seperti:

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

File proyek berikut menjalankan tugas ini dan mengatur MyProperty ke nilai yang diberikan:

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

Mendaftarkan tugas

Jika proyek akan menjalankan tugas, MSBuild harus tahu cara menemukan dan menjalankan rakitan yang berisi kelas tugas. Tugas didaftarkan menggunakan elemen UsingTask (MSBuild).

Jika tugas Anda memiliki dependensi khusus runtime, Anda harus memberi tahu MSBuild bahwa tugas tersebut harus menjalankan tugas di lingkungan tertentu dengan menunjukkan Architecture dan/atau Runtime di UsingTask.

File MSBuild Microsoft.Common.tasks adalah file proyek yang berisi daftar elemen UsingTask yang mendaftarkan semua tugas yang disertakan dengan MSBuild. File ini secara otomatis disertakan saat membangun proyek apa pun. Jika tugas yang terdaftar di Microsoft.Common.tasks juga terdaftar dalam file proyek saat ini, file proyek saat ini akan diprioritaskan, sehingga Anda dapat mengganti tugas default dengan tugas Anda sendiri yang memiliki nama yang sama.

Tip

Anda dapat melihat daftar tugas yang disertakan dengan versi MSBuild tertentu dengan melihat konten Microsoft.Common.tasks-nya.

Memunculkan peristiwa dari tugas

Jika tugas Anda berasal dari kelas pembantu Task, Anda dapat menggunakan salah satu metode pembantu berikut di kelas Task untuk memunculkan peristiwa yang akan ditangkap dan ditampilkan oleh pencatat terdaftar:

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

Jika tugas Anda mengimplementasikan ITask secara langsung, Anda masih dapat memunculkan peristiwa tersebut tetapi Anda harus menggunakan antarmuka IBuildEngine. Contoh berikut menunjukkan tugas yang mengimplementasikan ITask dan memunculkan peristiwa kustom:

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

Memerlukan parameter tugas untuk diatur

Anda bisa menandai properti tugas tertentu sebagai "diperlukan" sehingga file proyek apa pun yang menjalankan tugas harus mengatur nilai untuk properti ini atau build gagal. Terapkan atribut [Required] ke properti .NET dalam tugas Anda sebagai berikut:

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

Atribut [Required] ditentukan oleh RequiredAttribute di namespace layanan Microsoft.Build.Framework.

Bagaimana MSBuild memanggil tugas

Saat memanggil tugas, MSBuild terlebih dahulu membuat instans kelas tugas, lalu memanggil pengatur properti objek tersebut untuk parameter tugas yang diatur dalam elemen tugas dalam file proyek. Jika elemen tugas tidak menentukan parameter, atau jika ekspresi yang ditentukan dalam elemen dievaluasi menjadi string kosong, pengatur properti tidak dipanggil.

Misalnya, dalam proyek

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

hanya pengatur untuk Input3 yang dipanggil.

Tugas tidak boleh bergantung pada urutan relatif pemanggilan pengatur parameter-properti.

Jenis parameter tugas

MSBuild secara asli menangani properti jenis string, bool, ITaskItem dan ITaskItem[]. Jika tugas menerima parameter dari jenis yang berbeda, MSBuild memanggil ChangeType untuk mengonversi dari string (dengan semua referensi properti dan item diperluas) ke jenis tujuan. Jika konversi gagal untuk parameter input apa pun, MSBuild mengeluarkan kesalahan dan tidak memanggil metode Execute() tugas.

Contoh 1

Deskripsi

Kelas C# berikut ini menunjukkan tugas yang diturunkan dari kelas pembantu Task. Tugas ini mengembalikan true, yang menunjukkan bahwa tugas berhasil.

Kode

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

Contoh 2

Deskripsi

Kelas C# berikut ini menunjukkan tugas yang mengimplementasikan antarmuka ITask. Tugas ini mengembalikan true, yang menunjukkan bahwa tugas berhasil.

Kode

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

Contoh 3

Deskripsi

Kelas C# ini menunjukkan tugas yang diturunkan dari kelas pembantu Task. Ini memiliki properti string yang diperlukan, dan memunculkan peristiwa yang ditampilkan oleh semua pencatat terdaftar.

Kode

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

Contoh 4

Deskripsi

Contoh berikut menunjukkan file proyek yang menjalankan tugas contoh sebelumnya, SimpleTask3.

Kode

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

Konten terkait