MSBuild için görev yazma

Görevler MSBuild hedeflerinde bulunur ve derleme işlemi sırasında çalışan kodu sağlar. MSBuild, tipik görevlerden oluşan bir kitaplık içerir ve kendi görevlerinizi de oluşturabilirsiniz. MSBuild'in içerdiği görev kitaplığı hakkında daha fazla bilgi için bkz. MSBuild görev başvurusu.

Önkoşullar

Visual Studio projesi, MSBuild ile derlenir.

Görev

MSBuild görevlerine örnek olarak bir veya daha fazla dosyayı kopyalayan Copy, dizin oluşturan MakeDir ve C# kaynak kod dosyalarını derleyen Csc verilebilir. Her görev, ITask derlemesinde tanımlanan arabirimi uygulayan bir .NET sınıfı olarak uygulanır.

Bir görev uygularken aşağıdaki yaklaşımlardan birini kullanabilirsiniz:

  • ITask arabirimini doğrudan uygulayın.

  • sınıfınızı Task derlemesinde tanımlanan yardımcı sınıfından türetin. Task, ITask'i uygular ve bazı ITask üyelerinin varsayılan uygulamalarını sağlar. Günlük tutma da daha kolaydır.

Her iki durumda da sınıfınıza, görev çalıştırıldığında çağrılan adlı Executebir yöntem eklemeniz gerekir. Bu yöntem parametre almaz ve Boolean bir değer döndürür: görevin başarılı olup olmadığını true veya başarısız olursa false. Aşağıdaki örnekte hiçbir eylem gerçekleştirmeden başarıyla tamamlanan ve döndüren truebir görev gösterilmektedir.

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

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

Aşağıdaki MSBuild proje dosyası önceki görevi çalıştırır:

<Project>
    <Target Name="MyTarget">
        <SimpleTask />
    </Target>
</Project>

Görevler çalıştırıldığında, görev sınıfında .NET özellikleri oluşturursanız proje dosyasından da giriş alabilirler. MSBuild, görevin Execute yöntemini çağırmadan hemen önce bu özellikleri ayarlar. Dize özelliği oluşturmak için aşağıdaki örnek gibi görev kodunu kullanın:

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

Aşağıdaki proje dosyası bu görevi çalıştırır ve verilen değere ayarlar MyProperty .

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

MSBuild görevleri nasıl çağırır?

MSBuild bir görevi çağırdığında, önce görev sınıfını başlatır, sonra proje dosyasındaki görev öğesinde ayarlanan görev parametreleri için nesnenin özellik ayarlayıcılarını çağırır. Görev öğesi bir parametre belirtmezse veya öğesinde belirtilen ifade boş bir dize olarak değerlendirilirse, özellik ayarlayıcısı çağrılmaz.

Örneğin, aşağıdaki projede sadece Input3 için setztirici çağrılır.

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

Bir görev, parametre-özellik ayarlayıcısı çağırmasının göreli sırasına bağlı olmamalıdır.

Görev parametresi türleri

MSBuild, string, bool, ITaskItem ve ITaskItem[] türündeki özellikleri doğal olarak işler. Bir görev farklı türde bir parametre kabul ederse, MSBuild, tüm özellik ve öğe başvuruları genişletilmiş olarak, ChangeType'den hedef türe dönüştürmek için string'ı çağırır. Dönüştürme herhangi bir giriş parametresi için başarısız olursa MSBuild bir hata yayar ve görevin Execute() yöntemini çağırmaz.

Görevleri kaydetme

Bir görevi çalıştırmak için MSBuild, görev sınıfını içeren derlemenin nasıl bulunup çalıştırıldığını bilmelidir. Görevler UsingTask öğesi (MSBuild)kullanılarak kaydedilir.

Görevinizin çalışma zamanına özgü bağımlılıkları varsa, MSBuild'i görevi belirli bir ortamda çalıştırmaya yönlendirmek için Architecture öğesindeki Runtime veya UsingTask özniteliklerini belirtmeniz gerekir. Daha fazla bilgi için bkz . UsingTask öznitelikleri ve görev parametreleri.

MSBuild dosyası Microsoft.Common.tasks, UsingTask kaydeden öğeleri listeleyen bir proje dosyasıdır. MSBuild herhangi bir proje derlediğinde bu dosya otomatik olarak eklenir. Microsoft.Common.tasks dosyasına kaydedilmiş bir görev de geçerli proje dosyasına kayıtlıysa, geçerli proje dosyası önceliklidir, böylece varsayılan görevi aynı ada sahip kendi görevinizle geçersiz kılabilirsiniz.

Bahşiş

Microsoft.Common.tasks dosyasının içeriğini görüntüleyerek MSBuild'in belirli bir sürümüyle sağlanan görevlerin listesini görebilirsiniz.

Görev özelliklerinin ayarlanmasını gerektir

Belirli görev özelliklerini gerektiği gibi işaretleyebilirsiniz, böylece görevi çalıştıran tüm proje dosyalarının bu özellikler için değerler ayarlaması gerekir veya derleme başarısız olur. [Required] özniteliğini görevinizdeki .NET özelliğine aşağıdaki gibi uygulayın:

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

[Required] özniteliği, RequiredAttribute ad alanında Microsoft.Build.Framework tarafından tanımlanır.

Görevden kaynaklanan olayları tetikleme

Göreviniz Task yardımcı sınıfından türetiliyorsa, Task sınıfında, tüm kayıtlı günlüğe kaydedenlerin yakalayıp görüntülediği olayları yükseltmek için aşağıdaki yardımcı yöntemlerden herhangi birini kullanabilirsiniz.

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

Göreviniz ITask'yi doğrudan uyguluyorsa, yine de bu tür olayları tetikleyebilirsiniz, ancak IBuildEngine arabirimini kullanmanız gerekir. Aşağıdaki örnekte, ITask uygulayan ve özel bir olayı tetikleyen bir görev gösterilmektedir.

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

Görevi paketleme

Bir görevi dağıtmanın önerilen yolu NuGet paketindedir. Paketin tüm bağımlılıkları paketlemesi gerekir. Özel görev oluşturma konusunda size yol gösteren bir öğretici için bkz. NuGet paketi oluşturma.

Örnek 1

Aşağıdaki C# sınıfı yardımcı sınıfından Task türetilen bir görevi gösterir. Bu görev, başarılı olduğunu belirten trueolarak döner.

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

Örnek 2

Aşağıdaki C# sınıfı ITask arabirimi uygulayan bir görevi sergiler. Bu görev, başarılı olduğunu belirten trueolarak döner.

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

Örnek 3

Bu C# sınıfı, Task yardımcı sınıfından türetilen bir görevi gösterir. Görevin gerekli bir string özelliği vardır ve tüm kayıtlı günlükçüler tarafından gösterilen bir olayı tetikler.

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

Örnek 4

Aşağıdaki örnekte, önceki örnek görev SimpleTask3olan öğesini çağıran bir proje dosyası gösterilmektedir.

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

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

İlgili içerik

  • Last updated on