Bagikan melalui

Penulisan tugas

  • Artikel

Tugas menyediakan kode yang berjalan selama proses build. Tugas terkandung 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 termasuk Copy, yang menyalin satu atau beberapa file, MakeDir, yang membuat direktori, dan Csc, yang mengkompilasi file kode sumber C#. Setiap tugas diimplementasikan sebagai kelas .NET yang mengimplementasikan antarmuka ITask, yang didefinisikan dalam rakitan Microsoft.Build.Framework.dll.

Ada dua pendekatan yang dapat Anda gunakan saat menerapkan tugas:

  • Terapkan antarmuka ITask secara langsung.

  • Dapatkan kelas Anda dari kelas pembantu Task, yang didefinisikan 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, Anda harus menambahkan ke kelas Anda metode bernama Execute, yang merupakan metode yang dipanggil saat tugas berjalan. Metode ini tidak mengambil parameter dan mengembalikan nilai Boolean: true jika tugas berhasil atau false jika gagal. Contoh berikut menunjukkan tugas yang tidak melakukan tindakan 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, mereka juga dapat menerima input dari file proyek jika Anda membuat properti .NET di 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 terhadap waktu proses, Anda harus memberi tahu MSBuild bahwa tugas tersebut harus dijalankan dalam lingkungan tertentu dengan menunjukkan Architecture dan/atau Runtime dalamUsingTask-nya.

File MSBuild Microsoft.Common.tasks adalah file proyek yang berisi daftar elemen UsingTask yang mendaftarkan semua tugas yang disediakan 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 lebih diutamakan, sehingga Anda dapat mengambil alih tugas default dengan tugas Anda sendiri yang memiliki nama yang sama.

Tips

Anda dapat melihat daftar tugas yang disediakan dengan versi MSBuild tertentu dengan melihat konten Microsoft.Common.tasks.

Menaikkan peristiwa dari tugas

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

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

Jika tugas Anda menerapkan ITask secara langsung, Anda masih dapat menghasilkan peristiwa tersebut, tetapi Anda harus menggunakan antarmuka IBuildEngine. Contoh berikut menunjukkan sebuah tugas yang mengimplementasikan ITask dan memicu peristiwa khusus.

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

Mewajibkan agar parameter tugas diatur

Anda dapat 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 Microsoft.Build.Framework.

Bagaimana MSBuild memanggil tugas

Saat memanggil tugas, MSBuild terlebih dahulu membuat instans kelas tugas, lalu memanggil setter 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 mengevaluasi ke string kosong, setter properti tidak dipanggil.

Misalnya, dalam proyek

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

hanya setter untuk Input3 yang dipanggil.

Sebuah tugas tidak boleh bergantung pada urutan relatif dari pemanggilan setter di properti parameter.

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.

Mengemas tugas

Cara yang disarankan untuk mendistribusikan tugas ada dalam paket NuGet. Paket perlu mengemas semua ketergantungan. Topik ini dijelaskan secara menyeluruh dalam tutorial yang memandu Anda membuat tugas kustom. Lihat Membuat paket NuGet.

Contoh 1

Deskripsi

Kelas C# berikut ini menunjukkan tugas yang berasal dari kelas pembantu Task. Tugas ini mengembalikan true, 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, 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 berasal dari kelas pembantu Task. Ini memiliki properti string yang wajib, dan memicu sebuah peristiwa yang ditampilkan oleh semua pencatat log 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 memanggil contoh tugas 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