MSBuild インライン タスクMSBuild Inline Tasks

MSBuild タスクは通常、ITask インターフェイスを実装するクラスをコンパイルして作成します。MSBuild tasks are typically created by compiling a class that implements the ITask interface. 詳細については、タスクに関する記事を参照してください。For more information, see Tasks.

.NET Framework Version 4 以降では、プロジェクト ファイルでタスクをインラインで作成できます。Starting in .NET Framework version 4, you can create tasks inline in the project file. 個別のアセンブリを作成してタスクをホストする必要はありません。You do not have to create a separate assembly to host the task. これにより、ソース コードの追跡やタスクの配置が簡単になります。This makes it easier to keep track of source code and easier to deploy the task. ソース コードはスクリプトに統合されます。The source code is integrated into the script.

インライン タスクの構造The Structure of an Inline Task

インライン タスクは UsingTask 要素に格納されます。An inline task is contained by a UsingTask element. インライン タスクとそれを格納する UsingTask 要素は通常、.targets ファイルに含められ、必要に応じて他のプロジェクト ファイルにインポートされます。The inline task and the UsingTask element that contains it are typically included in a .targets file and imported into other project files as required. 基本的なインライン タスクの例を次に示します。Here is a basic inline task. このタスクでは何も実行されないことに注意してください。Notice that it does nothing.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <!-- This simple inline task does nothing. -->  
  <UsingTask  
    TaskName="DoNothing"  
    TaskFactory="CodeTaskFactory"  
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup />  
    <Task>  
      <Reference Include="" />  
      <Using Namespace="" />  
      <Code Type="Fragment" Language="cs">  
      </Code>  
    </Task>  
  </UsingTask>  
</Project>  

この例の UsingTask 要素には、タスクとそれをコンパイルするインライン タスク ファクトリを記述した 3 つの属性が含まれています。The UsingTask element in the example has three attributes that describe the task and the inline task factory that compiles it.

  • TaskName 属性は、タスクの名前を指定します。この例では DoNothing と指定しています。The TaskName attribute names the task, in this case, DoNothing.

  • TaskFactory 属性は、インライン タスク ファクトリを実装するクラスの名前を指定します。The TaskFactory attribute names the class that implements the inline task factory.

  • AssemblyFile 属性は、インライン タスク ファクトリの場所を指定します。The AssemblyFile attribute gives the location of the inline task factory. 代わりに、AssemblyName 属性を使用してインライン タスク ファクトリ クラスの完全修飾名を指定することもできます。これは通常、グローバル アセンブリ キャッシュ (GAC: Global Assembly Cache) に配置されます。Alternatively, you can use the AssemblyName attribute to specify the fully qualified name of the inline task factory class, which is typically located in the global assembly cache (GAC).

    DoNothing タスクの残りの要素は空になっていますが、ここではインライン タスクの順序と構造を示すために含めてあります。The remaining elements of the DoNothing task are empty and are provided to illustrate the order and structure of an inline task. 具体的な例については、この後の例を参照してください。A more robust example is presented later in this topic.

  • ParameterGroup 要素は省略可能です。The ParameterGroup element is optional. 指定する場合は、タスクのパラメーターを宣言します。When specified, it declares the parameters for the task. 入力パラメーターと出力パラメーターの詳細については、この後の「入力パラメーターと出力パラメーター」を参照してください。For more information about input and output parameters, see "Input and Output Parameters" later in this topic.

  • Task 要素にはタスクのソース コードを記述して格納します。The Task element describes and contains the task source code.

  • Reference 要素は、コードで使用する .NET アセンブリへの参照を指定します。The Reference element specifies references to the .NET assemblies that you are using in your code. これは、Visual Studio でプロジェクトに参照を追加することに相当します。This is equivalent to adding a reference to a project in Visual Studio. Include 属性は参照アセンブリのパスを指定します。The Include attribute specifies the path of the referenced assembly.

  • Using 要素には、アクセスする名前空間をリストします。The Using element lists the namespaces that you want to access. これは、Visual C# の Using ステートメントに似ています。This resembles the Using statement in Visual C#. Namespace 属性は、含める名前空間を指定します。The Namespace attribute specifies the namespace to include.

    Reference 要素と Using 要素は言語に依存しません。Reference and Using elements are language-agnostic. インライン タスクは、サポートされているどの .NET CodeDom 言語 (Visual Basic や Visual C# など) でも記述できます。Inline tasks can be written in any one of the supported .NET CodeDom languages, for example, Visual Basic or Visual C#.

注意

Task 要素に含まれる要素はタスク ファクトリによって異なります。この例では、コード タスク ファクトリが格納されています。Elements contained by the Task element are specific to the task factory, in this case, the code task factory.

コード要素Code Element

Task 要素内の最後の子要素は Code 要素です。The last child element to appear within the Task element is the Code element. Code 要素では、タスクにコンパイルするコードを記述するか参照します。The Code element contains or locates the code that you want to be compiled into a task. Code 要素に含める内容は、タスクを記述する方法に応じて異なります。What you put in the Code element depends on how you want to write the task.

Language 属性は、コードを記述する言語を指定します。The Language attribute specifies the language in which your code is written. 指定できる値は、cs (C# の場合) または vb (Visual Basic の場合) です。Acceptable values are cs for C#, vb for Visual Basic.

Type 属性は、Code 要素内のコードの種類を指定します。The Type attribute specifies the type of code that is found in the Code element.

  • Type の値が Class の場合、Code 要素には ITask インターフェイスから派生したクラスのコードが含まれます。If the value of Type is Class, then the Code element contains code for a class that derives from the ITask interface.

  • Type の値が Method の場合、コードは Execute インターフェイスの ITask メソッドのオーバーライドを定義します。If the value of Type is Method, then the code defines an override of the Execute method of the ITask interface.

  • Type の値が Fragment の場合、コードは Execute メソッドの内容を定義します。ただし、シグネチャや return ステートメントは含まれません。If the value of Type is Fragment, then the code defines the contents of the Execute method, but not the signature or the return statement.

    コード自体は通常、<![CDATA[ マーカーと ]]> マーカーの間に記述します。The code itself typically appears between a <![CDATA[ marker and a ]]> marker. コードは CDATA セクション内に記述するため、"<" や ">" などの予約文字のエスケープを気にする必要はありません。Because the code is in a CDATA section, you do not have to worry about escaping reserved characters, for example, "<" or ">".

    また、Source 要素の Code 属性を使用して、タスクのコードを含むファイルの場所を指定することもできます。Alternatively, you can use the Source attribute of the Code element to specify the location of a file that contains the code for your task. ソース ファイルのコードの種類は、Type 属性で指定された種類である必要があります。The code in the source file must be of the type that is specified by the Type attribute. Source 属性が指定されている場合、Type の既定値は Class です。If the Source attribute is present, the default value of Type is Class. Source が指定されていない場合の既定値は Fragment です。If Source is not present, the default value is Fragment.

注意

ソース ファイル内のタスク クラスを定義する場合は、クラス名が、対応する UsingTask 要素の TaskName 属性と一致する必要があります。When defining the task class in the source file, the class name must agree with the TaskName attribute of the corresponding UsingTask element.

Hello WorldHello World

具体的なインライン タスクの例を次に示します。Here is a more robust inline task. HelloWorld タスクは、既定のエラー ログ デバイスに "Hello, world!"The HelloWorld task displays "Hello, world!" と表示します。通常、既定のデバイスは、システム コンソールまたは Visual Studio の出力ウィンドウです。on the default error logging device, which is typically the system console or the Visual Studio Output window. この例の Reference 要素は、例を示す目的でのみ含めてあります。The Reference element in the example is included just for illustration.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <!-- This simple inline task displays "Hello, world!" -->  
  <UsingTask  
    TaskName="HelloWorld"  
    TaskFactory="CodeTaskFactory"  
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup />  
    <Task>  
      <Reference Include="System.Xml.dll"/>  
      <Using Namespace="System"/>  
      <Using Namespace="System.IO"/>  
      <Code Type="Fragment" Language="cs">  
<![CDATA[  
// Display "Hello, world!"  
Log.LogError("Hello, world!");  
]]>  
      </Code>  
    </Task>  
  </UsingTask>  
</Project>  

HelloWorld タスクを HelloWorld.targets という名前のファイルに保存すると、次のようにしてプロジェクトから呼び出すことができます。You could save the HelloWorld task in a file that is named HelloWorld.targets, and then invoke it from a project as follows.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <Import Project="HelloWorld.targets" />  
  <Target Name="Hello">  
    <HelloWorld />  
  </Target>  
</Project>  

入力パラメーターと出力パラメーターInput and Output Parameters

インライン タスクのパラメーターは、ParameterGroup 要素の子要素です。Inline task parameters are child elements of a ParameterGroup element. どのパラメーターも、それを定義する要素の名前を受け取ります。Every parameter takes the name of the element that defines it. 次のコードは、Text パラメーターを定義しています。The following code defines the parameter Text.

<ParameterGroup>  
    <Text />  
</ParameterGroup>  

パラメーターには、以下の 1 つ以上の属性を含めることができます。Parameters may have one or more of these attributes:

  • Required は省略可能な属性で、既定値は false です。Required is an optional attribute that is false by default. true の場合、そのパラメーターは必須で、タスクを呼び出す前に値を指定する必要があります。If true, then the parameter is required and must be given a value before calling the task.

  • ParameterType は省略可能な属性で、既定値は System.String です。ParameterType is an optional attribute that is System.String by default. System.Convert.ChangeType を使用して文字列との間で変換できる項目または値の完全修飾型に設定できます It may be set to any fully qualified type that is either an item or a value that can be converted to and from a string by using System.Convert.ChangeType. (つまり、外部タスクとの受け渡しが可能なすべての型)。(In other words, any type that can be passed to and from an external task.)

  • Output は省略可能な属性で、既定値は false です。Output is an optional attribute that is false by default. true の場合、そのパラメーターの値を、Execute メソッドから戻る前に指定する必要があります。If true, then the parameter must be given a value before returning from the Execute method.

    次に例を示します。For example,

<ParameterGroup>  
    <Expression Required="true" />  
      <Files ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />  
    <Tally ParameterType="System.Int32" Output="true" />  
</ParameterGroup>  

この例では、以下の 3 つのパラメーターを定義しています。defines these three parameters:

  • Expression は、System.String 型の必須の入力パラメーターです。Expression is a required input parameter of type System.String.

  • Files は、必須の項目リスト入力パラメーターです。Files is a required item list input parameter.

  • Tally は、System.Int32 型の出力パラメーターです。Tally is an output parameter of type System.Int32.

    Code 要素の Type 属性が Fragment または Method の場合、すべてのパラメーターに対して自動的にプロパティが作成されます。If the Code element has the Type attribute of Fragment or Method, then properties are automatically created for every parameter. それ以外の場合は、タスクのソース コードで明示的にプロパティを宣言する必要があります。プロパティはパラメーター定義と完全に一致している必要があります。Otherwise, properties must be explicitly declared in the task source code, and must exactly match their parameter definitions.

Example

指定されたファイル内のすべてのトークンを指定された値に置き換えるインライン タスクの例を次に示します。The following inline task replaces every occurrence of a token in the given file with the given value.

<Project xmlns='http://schemas.microsoft.com/developer/msbuild/2003' ToolsVersion="15.0">  

  <UsingTask TaskName="TokenReplace" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">  
    <ParameterGroup>  
      <Path ParameterType="System.String" Required="true" />  
      <Token ParameterType="System.String" Required="true" />  
      <Replacement ParameterType="System.String" Required="true" />  
    </ParameterGroup>  
    <Task>  
      <Code Type="Fragment" Language="cs"><![CDATA[  
string content = File.ReadAllText(Path);  
content = content.Replace(Token, Replacement);  
File.WriteAllText(Path, content);  

]]></Code>  
    </Task>  
  </UsingTask>  

  <Target Name='Demo' >  
    <TokenReplace Path="C:\Project\Target.config" Token="$MyToken$" Replacement="MyValue"/>  
  </Target>  
</Project>  

関連項目See Also

タスク Tasks
チュートリアル: インライン タスクの作成Walkthrough: Creating an Inline Task