Menulis tugas untuk MSBuild

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

Prasyarat

Proyek Visual Studio yang dibangun dengan MSBuild.

Tugas

Contoh tugas MSBuild termasuk Salin, 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 ITask antarmuka yang ditentukan dalam rakitan Microsoft.Build.Framework.dll .

Anda dapat menggunakan salah satu pendekatan berikut saat menerapkan tugas:

Terapkan antarmuka ITask secara langsung.
Dapatkan kelas Anda dari kelas pembantu Task, yang didefinisikan dalam rakitan Microsoft.Build.Utilities.dll. Task menerapkan ITask dan menyediakan implementasi default dari beberapa anggota ITask. Pengelogan juga lebih mudah.

Dalam kedua kasus, Anda harus menambahkan metode ke kelas bernama Execute, 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, berhasil diselesaikan, dan 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 MSBuild berikut menjalankan tugas sebelumnya:

<Project>
    <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 contoh berikut:

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 diatur MyProperty ke nilai yang diberikan.

<Project>
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Bagaimana MSBuild memanggil tugas

Ketika MSBuild 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 berikut, hanya setter untuk Input3 yang dipanggil.

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

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

Jenis parameter tugas

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

Mendaftarkan tugas

Untuk 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 mengarahkan MSBuild untuk menjalankan tugas di lingkungan tertentu dengan menunjukkan atribut Architecture atau Runtime di dalam elemen UsingTask. Untuk informasi selengkapnya, lihat Atribut UsingTask dan parameter tugas.

File MSBuild Microsoft.Common.tasks adalah file proyek yang mencantumkan UsingTask elemen yang mendaftarkan semua tugas yang disediakan dengan MSBuild. File ini secara otomatis disertakan ketika MSBuild 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 dengan nama yang sama.

Tips

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

Mewajibkan pengaturan properti tugas.

Anda dapat menandai properti tugas tertentu sebagaimana 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.

Menaikkan peristiwa dari tugas

Jika tugas Anda berasal dari kelas pembantu Task, Anda dapat menggunakan salah satu metode bantu berikut pada kelas Task untuk memicu kejadian yang tertangkap dan ditampilkan oleh semua pencatat terdaftar:

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

Jika tugas ITask diterapkan secara langsung, Anda masih dapat memicu peristiwa tersebut, tetapi Anda harus menggunakan antarmuka IBuildEngine. Contoh berikut menunjukkan tugas yang mengimplementasikan ITask dan menaikkan 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;
    }
}

Mengemas tugas

Cara yang disarankan untuk mendistribusikan tugas ada dalam paket NuGet. Paket perlu mengemas semua ketergantungan. Untuk tutorial yang memandu Anda membuat tugas khusus, lihat Membuat paket NuGet.

Contoh 1

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

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

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

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

Contoh 3

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

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

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

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

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-12