プロパティと項目の比較Comparing Properties and Items

MSBuild のプロパティと項目は、いずれもタスクに情報を渡し、条件を評価し、プロジェクト ファイルで参照する値を格納しておくために使用されます。MSBuild properties and items are both used to pass information to tasks, evaluate conditions, and store values that can be referenced throughout the project file.

  • プロパティは名前と値のペアです。Properties are name-value pairs. 詳細については、「MSBuild プロパティ」を参照してください。For more information, see MSBuild Properties.

  • 項目は、一般的にファイルを示すオブジェクトです。Items are objects that typically represent files. 項目オブジェクトには、メタデータ コレクションを関連付けることができます。Item objects can have associated metadata collections. メタデータは名前と値のペアです。Metadata are name-value pairs. 詳細については、「MSBuild 項目」をご覧ください。For more information, see Items.

スカラーとベクターScalars and Vectors

MSBuild プロパティは 1 つの文字列値のみを持つ名前と値のペアなので、多くの場合はスカラーと説明されます。Because MSBuild properties are name-value pairs that have just one string value, they are often described as scalar. MSBuild 項目の種類は項目のリストなので、多くの場合はベクターと説明されます。Because MSBuild item types are lists of items, they are often described as vector. ただし実際には、プロパティで複数の値を表すことがあり、項目の種類の項目数が 0 個または 1 個の場合があります。However, in practice, properties can represent multiple values, and item types can have zero or one items.

ターゲットの依存関係の挿入Target Dependency Injection

プロパティが複数の値を表す方法については、ターゲットをターゲットの一覧に追加して一覧を作成する場合の一般的な使用パターンを考えます。To see how properties can represent multiple values, consider a common usage pattern for adding a target to a list of targets to be built. この一覧は、一般的に、プロパティ値とターゲット名をセミコロン (;) で区切って表します。This list is typically represented by a property value, with the target names separated by semicolons.

<PropertyGroup>  
    <BuildDependsOn>  
        BeforeBuild;  
        CoreBuild;  
        AfterBuild  
    </BuildDependsOn>  
</PropertyGroup>  

通常、BuildDependsOn プロパティは、ターゲットの DependsOnTargets 属性の引数として使用され、項目一覧に変換されます。The BuildDependsOn property is typically used as the argument of a target DependsOnTargets attribute, effectively converting it to an item list. このプロパティを上書きして、ターゲットを追加したり、ターゲットの実行順を変更したりすることができます。This property can be overridden to add a target or to change the target execution order. 次に例を示します。For example,

<PropertyGroup>  
    <BuildDependsOn>  
        $(BuildDependsOn);  
        CustomBuild;  
    </BuildDependsOn>  
</PropertyGroup>  

CustomBuild ターゲットをターゲット一覧に追加し、BuildDependsOn に値 BeforeBuild;CoreBuild;AfterBuild;CustomBuild を付与します。adds the CustomBuild target to the target list, giving BuildDependsOn the value BeforeBuild;CoreBuild;AfterBuild;CustomBuild.

MSBuild 4.0 以降、ターゲットの依存関係の挿入は推奨されていません。Starting with MSBuild 4.0, target dependency injection is deprecated. 代わりに AfterTargets 属性と BeforeTargets 属性を使用してください。Use the AfterTargets and BeforeTargets attributes instead. 詳細については、「ターゲットのビルド順序」を参照してください。For more information, see Target Build Order.

文字列と項目一覧との変換Conversions between Strings and Item Lists

MSBuild は、項目の種類と文字列値の変換を必要に応じて実行します。MSBuild performs conversions to and from item types and string values as needed. 項目一覧を文字列値にする方法については、MSBuild プロパティの値として項目の種類を使用すると何が起こるかを考えます。To see how an item list can become a string value, consider what happens when an item type is used as the value of an MSBuild property:

<ItemGroup>  
    <OutputDir Include="KeyFiles\;Certificates\" />  
  </ItemGroup>  
<PropertyGroup>  
    <OutputDirList>@(OutputDir)</OutputDirList>  
</PropertyGroup>  

項目の種類 OutputDir には、"KeyFiles\;Certificates\" という値の Include 属性があります。The item type OutputDir has an Include attribute with the value "KeyFiles\;Certificates\". MSBuild は、この文字列を 2 つの項目 KeyFiles\ と Certificates\ に解析します。MSBuild parses this string into two items: KeyFiles\ and Certificates\. 項目の種類 OutputDir を OutputDirList プロパティの値として使用している場合、MSBuild は、項目の種類をセミコロン区切りの文字列 "KeyFiles\;Certificates\" に変換または "平坦化" します。When the item type OutputDir is used as the value of the OutputDirList property, MSBuild converts or "flattens" the item type into to the semicolon-separated string "KeyFiles\;Certificates\".

タスクのプロパティと項目Properties and Items in Tasks

プロパティと項目は、MSBuild タスクの入力と出力として使用されます。Properties and items are used as inputs and outputs to MSBuild tasks. 詳細については、タスクに関する記事を参照してください。For more information, see Tasks.

プロパティは属性としてタスクに渡されます。Properties are passed to tasks as attributes. タスク内の MSBuild プロパティは、値を文字列との間で変換できるプロパティの種類で表されます。Within the task, an MSBuild property is represented by a property type whose value can be converted to and from a string. サポートされるプロパティの種類には、boolcharDateTimeDecimalDoubleintstring に加え、ChangeType が処理できるあらゆる種類が含まれます。The supported property types include bool, char, DateTime, Decimal, Double, int, string, and any type that ChangeType can handle.

項目は ITaskItem オブジェクトとしてタスクに渡されます。Items are passed to tasks as ITaskItem objects. タスク内では、ItemSpec は項目の値を表し、GetMetadata はそのメタデータを取得します。Within the task, ItemSpec represents the value of the item and GetMetadata retrieves its metadata.

項目の種類の項目一覧は、ITaskItem オブジェクトの配列として渡すことができます。The item list of an item type can be passed as an array of ITaskItem objects. .NET Framework 3.5 以降、Remove 属性を使用してターゲットの項目一覧から項目を削除できるようになりました。Beginning with the .NET Framework 3.5, items can be removed from an item list in a target by using the Remove attribute. 項目は項目一覧から削除できるため、アイテムの種類の項目数が 0 個になる可能性があります。Because items can be removed from an item list, it is possible for an item type to have zero items. 項目一覧をタスクに渡す場合、タスクのコードでこの可能性をチェックする必要があります。If an item list is passed to a task, the code in the task should check for this possibility.

プロパティと項目の評価順序Property and Item Evaluation Order

ビルドの評価フェーズでは、インポート対象のファイルは出現順にビルドに組み込まれます。During the evaluation phase of a build, imported files are incorporated into the build in the order in which they appear. プロパティと項目は、次の順に 3 つのパスで定義されます。Properties and items are defined in three passes in the following order:

  • プロパティが出現順に定義および修正されます。Properties are defined and modified in the order in which they appear.

  • 項目定義が出現順に定義および修正されます。Item definitions are defined and modified in the order in which they appear.

  • 項目が出現順に定義および修正されます。Items are defined and modified in the order in which they appear.

    ビルドの実行フェーズでは、ターゲット内で定義されるプロパティおよび項目は、出現順に、1 つの段階でまとめて評価されます。During the execution phase of a build, properties and items that are defined within targets are evaluated together in a single phase in the order in which they appear.

    ただし、これだけでは済みません。However, this is not the full story. プロパティ、項目定義、または項目を定義するときに、その値も評価されます。When a property, item definition, or item is defined, its value is evaluated. 式エバリュエーターで、値を指定する文字列が展開されます。The expression evaluator expands the string that specifies the value. 文字列の展開はビルド フェーズによって変わります。The string expansion is dependent on the build phase. プロパティと項目の詳細な評価順は次のとおりです。Here is a more detailed property and item evaluation order:

  • ビルドの評価フェーズ:During the evaluation phase of a build:

    • プロパティが出現順に定義および修正されます。Properties are defined and modified in the order in which they appear. プロパティ関数が実行されます。Property functions are executed. 式内のフォーム $(PropertyName) のプロパティ値が展開されます。Property values in the form $(PropertyName) are expanded within expressions. プロパティ値が展開された式に設定されます。The property value is set to the expanded expression.

    • 項目定義が出現順に定義および修正されます。Item definitions are defined and modified in the order in which they appear. 式内のプロパティ関数は既に展開されています。Property functions have already been expanded within expressions. メタデータ値が展開された式に設定されます。Metadata values are set to the expanded expressions.

    • 項目の種類が出現順に定義および修正されます。Item types are defined and modified in the order in which they appear. フォーム @(ItemType) の項目値が展開されます。Item values in the form @(ItemType) are expanded. 項目の変換も展開されます。Item transformations are also expanded. 式内のプロパティ関数と値は既に展開されています。Property functions and values have already been expanded within expressions. 項目一覧とメタデータ値が展開された式に設定されます。The item list and metadata values are set to the expanded expressions.

  • ビルドの実行フェーズ:During the execution phase of a build:

    • ターゲット内に定義されているプロパティと項目は、出現順にまとめて評価されます。Properties and items that are defined within targets are evaluated together in the order in which they appear. プロパティ関数が実行され、式内のプロパティ値が展開されます。Property functions are executed and property values are expanded within expressions. 項目値と項目の変換も展開されます。Item values and item transformations are also expanded. プロパティ値、項目の種類値、およびメタデータ値が、展開された式に設定されます。The property values, item type values, and metadata values are set to the expanded expressions.

評価順のわかりにくい効果Subtle Effects of the Evaluation Order

ビルドの評価フェーズでは、プロパティの評価が項目の評価よりも先に実行されます。In the evaluation phase of a build, property evaluation precedes item evaluation. それでも、プロパティ値が項目値に依存しているように見えることがあります。Nevertheless, properties can have values that appear to depend on item values. 次のスクリプトがあるとします。Consider the following script.

<ItemGroup>  
    <KeyFile Include="KeyFile.cs">  
        <Version>1.0.0.3</Version>  
    </KeyFile>  
</ItemGroup>  
<PropertyGroup>  
    <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>  
</PropertyGroup>  
<Target Name="AfterBuild">  
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />  
</Target>  

Message タスクを実行すると、次のメッセージが表示されます。Executing the Message task displays this message:

KeyFileVersion: 1.0.0.3  

これは、KeyFileVersion の値が実際には文字列 "@(KeyFile->'%(Version)')" であるためです。This is because the value of KeyFileVersion is actually the string "@(KeyFile->'%(Version)')". プロパティが最初に定義されたときに項目と項目の変換が展開されなかったため、KeyFileVersion プロパティには展開されていない文字列値が割り当てられました。Item and item transformations were not expanded when the property was first defined, so the KeyFileVersion property was assigned the value of the unexpanded string.

ビルドの実行フェーズで Message タスクを処理するときに、MSBuild は文字列 "@(KeyFile->'%(Version)')" を展開して "1.0.0.3" を生成します。During the execution phase of the build, when it processes the Message task, MSBuild expands the string "@(KeyFile->'%(Version)')" to yield "1.0.0.3".

プロパティと項目グループの順序が変わった場合でも、同じメッセージが表示されます。Notice that the same message would appear even if the property and item groups were reversed in order.

2 つ目の例として、プロパティと項目グループがターゲット内にあるときに生じる状況を考えてみましょう。As a second example, consider what can happen when property and item groups are located within targets:

<Target Name="AfterBuild">  
    <PropertyGroup>  
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>  
    </PropertyGroup>  
    <ItemGroup>  
        <KeyFile Include="KeyFile.cs">  
            <Version>1.0.0.3</Version>  
        </KeyFile>  
    </ItemGroup>  
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />  
</Target>  

Message タスクを実行すると、次のメッセージが表示されます。The Message task displays this message:

KeyFileVersion:   

これは、ビルドの実行フェーズ中に、ターゲット内で定義されているプロパティと項目グループが上から下の順にまとめて評価されるためです。This is because during the execution phase of the build, property and item groups defined within targets are evaluated top to bottom at the same time. KeyFileVersion の定義時に KeyFile は不明です。When KeyFileVersion is defined, KeyFile is unknown. そのため、項目の変換によって空の文字列に展開されます。Therefore, the item transformation expands to an empty string.

この場合、プロパティと項目グループの順序を逆にすることで、元のメッセージが復元されます。In this case, reversing the order of the property and item groups restores the original message:

<Target Name="AfterBuild">  
    <ItemGroup>  
        <KeyFile Include="KeyFile.cs">  
            <Version>1.0.0.3</Version>  
        </KeyFile>  
    </ItemGroup>  
    <PropertyGroup>  
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>  
    </PropertyGroup>  
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />  
</Target>  

KeyFileVersion の値は "@(KeyFile->'%(Version)')" ではなく "1.0.0.3" に設定されます。The value of KeyFileVersion is set to "1.0.0.3" and not to "@(KeyFile->'%(Version)')". Message タスクを実行すると、次のメッセージが表示されます。The Message task displays this message:

KeyFileVersion: 1.0.0.3  

関連項目See Also

詳細な概念Advanced Concepts