タスクの作成Task Writing

タスクでは、ビルド プロセスの間に実行するコードを指定します。Tasks provide the code that runs during the build process. タスクはターゲットに含まれます。Tasks are contained in targets. 一般的なタスクのライブラリは MSBuildMSBuild に付属します。独自のタスクを作成することもできます。A library of typical tasks is included with MSBuildMSBuild, and you can also create your own tasks. MSBuildMSBuild に付属するタスク ライブラリの詳細については、タスク リファレンスを参照してください。For more information about the library of tasks that are included with MSBuildMSBuild, see Task Reference.

[タスク]Tasks

タスクには、1 つまたは複数のファイルをコピーする Copy、ディレクトリを作成する MakeDirVisual C#Visual C# ソース コード ファイルをコンパイルする Csc などがあります。Examples of tasks include Copy, which copies one or more files, MakeDir, which creates a directory, and Csc, which compiles Visual C#Visual C# source code files. 各タスクは、Microsoft.Build.Framework.dll アセンブリで定義されている ITask インターフェイスを実装する .NET クラスとして実装されます。Each task is implemented as a .NET class that implements the ITask interface, which is defined in the Microsoft.Build.Framework.dll assembly.

タスクを実装するには 2 つの方法があります。There are two approaches you can use when implementing a task:

  • ITask インターフェイスを直接実装します。Implement the ITask interface directly.

  • Microsoft.Build.Utilities.dll アセンブリで定義されているヘルパー クラス Task からクラスを継承します。Derive your class from the helper class, Task, which is defined in the Microsoft.Build.Utilities.dll assembly. Task は ITask を実装し、一部の ITask メンバーの既定の実装を提供します。Task implements ITask and provides default implementations of some ITask members. また、ログは簡単に記録できます。Additionally, logging is easier.

    いずれの場合でも、クラスを Execute という名前のメソッドに追加する必要があります。これは、タスクの実行時に呼び出されるメソッドです。In both cases, you must add to your class a method named Execute, which is the method that is called when the task runs. このメソッドはパラメーターを取らず、Boolean 値を返します。タスクが成功した場合は true を、失敗した場合は false を返します。This method takes no parameters and returns a Boolean value: true if the task succeeded or false if it failed. 次は、何のアクションも実行せず、true を返すタスクの例です。The following example shows a task that performs no action and returns true.

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

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

次のプロジェクト ファイルはこのタスクを実行します。The following project file runs this task:

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

タスクが実行されるとき、タスク クラスで .NET プロパティを作成する場合、プロジェクト ファイルからも入力を受け取ります。When tasks run, they can also receive inputs from the project file if you create .NET properties on the task class. MSBuildMSBuild は、タスクの Execute メソッドを呼び出す直前にこれらのプロパティを設定します。 sets these properties immediately before calling the task's Execute method. 文字列プロパティを作成するには、次のようなタスク コードを使用します。To create a string property, use task code such as:

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

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

        private string myProperty;  
        public string MyProperty  
        {  
            get { return myProperty; }  
            set { myProperty = value; }  
        }  
    }  
}  

次のプロジェクト ファイルはこのタスクを実行し、与えられた値に MyProperty を設定します。The following project file runs this task and sets MyProperty to the given value:

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

タスクの登録Registering Tasks

プロジェクトがタスクを実行する場合、タスク クラスが含まれるアセンブリを見つける方法を MSBuildMSBuild に与えている必要があります。If a project is going to run a task, MSBuildMSBuild must know how to locate the assembly that contains the task class. タスクは UsingTask 要素 (MSBuild) で登録されます。Tasks are registered using the UsingTask Element (MSBuild).

MSBuildMSBuild ファイルの Microsoft.Common.Tasks は、MSBuildMSBuild に付属するすべてのタスクを登録する UsingTask 要素の一覧が含まれるプロジェクト ファイルです。The MSBuildMSBuild file Microsoft.Common.Tasks is a project file that contains a list of UsingTask elements that register all the tasks that are supplied with MSBuildMSBuild. このファイルは、あらゆるプロジェクトのビルド時に自動的に追加されます。This file is automatically included when building every project. Microsoft.Common.Tasks に登録されているタスクが現在のプロジェクト ファイルにも登録されている場合、現在のプロジェクト ファイルに優先権が与えられます。つまり、既定のタスクが、同じ名前を持つ独自のタスクでオーバーライドされます。If a task that is registered in Microsoft.Common.Tasks is also registered in the current project file, the current project file takes precedence; that is, you can override a default task with your own task that has the same name.

ヒント

Microsoft.Common.Tasks のコンテンツを表示することで、MSBuildMSBuild に付属するタスクの一覧を確認できます。You can see a list of the tasks that are supplied with MSBuildMSBuild by viewing the contents of Microsoft.Common.Tasks.

タスクからイベントを生成するRaising Events from a Task

タスクが Task ヘルパー クラスから派生する場合、Task クラスで次のいずれかのヘルパー メソッドを利用して生成したイベントは、登録されているあらゆるロガーで記録され、表示されます。If your task derives from the Task helper class, you can use any of the following helper methods on the Task class to raise events that will be caught and displayed by any registered loggers:

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

このようなイベントは、タスクが ITask を直接実装する場合でも生成できますが、IBuildEngine インターフェイスを利用する必要があります。If your task implements ITask directly, you can still raise such events but you must use the IBuildEngine interface. 次は、ITask を実装し、カスタム イベントを生成するタスクの例です。The following example shows a task that implements ITask and raises a custom event:

public class SimpleTask : ITask  
{  
    private IBuildEngine buildEngine;  
    public IBuildEngine BuildEngine  
    {  
        get{ return buildEngine; }  
        set{ buildEngine = value; }  
    }  

    public override bool Execute()  
    {  
        TaskEventArgs taskEvent =  
            new TaskEventArgs(BuildEventCategory.Custom,  
            BuildEventImportance.High, "Important Message",  
           "SimpleTask");  
        BuildEngine.LogBuildEvent(taskEvent);  
        return true;  
    }  
}  

タスク パラメーターの設定を要求するRequiring Task Parameters to be Set

特定のタスク プロパティを "必須" に設定できます。必須にすると、タスクを実行するプロジェクト ファイルで、必須のプロパティに値を設定する必要があります。設定しないと、ビルドに失敗します。You can mark certain task properties as "required" so that any project file that runs the task must set values for these properties or the build fails. 次のように、タスクの .NET プロパティに [Required] 属性を適用します。Apply the [Required] attribute to the .NET property in your task as follows:

private string requiredProperty;  

[Required]  
public string RequiredProperty  
{  
    get { return requiredProperty; }  
    set { requiredProperty = value; }  
}  

[Required] 属性は Microsoft.Build.Framework 名前空間の RequiredAttribute によって定義されます。The [Required] attribute is defined by RequiredAttribute in the Microsoft.Build.Framework namespace.

Example

説明Description

次の Visual C#Visual C# クラスは、Task ヘルパー クラスから派生されるタスクを示します。This following Visual C#Visual C# class demonstrates a task deriving from the Task helper class. このタスクは成功を示す true を返します。This task returns true, indicating that it succeeded.

コードCode

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

Example

説明Description

次の Visual C#Visual C# クラスは、ITask インターフェイスを実装するタスクを示します。This following Visual C#Visual C# class demonstrates a task implementing the ITask interface. このタスクは成功を示す true を返します。This task returns true, indicating that it succeeded.

コードCode

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.  
        private IBuildEngine buildEngine;  
        public IBuildEngine BuildEngine  
        {  
            get  
            {  
                return buildEngine;  
            }  
            set  
            {  
                buildEngine = value;  
            }  
         }  

        // 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.  
        private Object hostObject;  
        public Object HostObject  
        {  
            get  
            {  
                return hostObject;  
            }  

            set  
            {  
                hostObject = value;  
            }  
        }  

        public bool Execute()  
        {  
            // This is where the task would presumably do its work.  
            return true;  
        }  
    }  
}  

Example

説明Description

この Visual C#Visual C# クラスは、Task ヘルパー クラスから派生されるタスクを示します。This Visual C#Visual C# class demonstrates a task that derives from the Task helper class. 必須の文字列プロパティがあり、登録されているすべてのロガーで表示されるイベントを生成します。It has a required string property, and raises an event that is displayed by all registered loggers.

コードCode

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

Example

説明Description

次は、前のサンプル タスク SimpleTask3 を呼び出すプロジェクト ファイルの例です。The following example shows a project file invoking the previous example task, SimpleTask3.

コードCode

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

参照See Also

Task Reference (タスク リファレンス) Task Reference
Task Reference (タスク リファレンス)Task Reference