Comparaison des propriétés et des élémentsComparing Properties and Items

Les propriétés et les éléments MSBuild permettent de transmettre des informations aux tâches, d’évaluer des conditions et de stocker les valeurs qui peuvent être référencées dans le fichier projet.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.

  • Les propriétés sont des paires nom-valeur.Properties are name-value pairs. Pour plus d’informations, consultez l’article Propriétés MSBuild.For more information, see MSBuild Properties.

  • Les éléments sont des objets qui représentent généralement des fichiers.Items are objects that typically represent files. Des collections de métadonnées peuvent être associées aux objets d’élément.Item objects can have associated metadata collections. Les métadonnées sont des paires nom-valeur.Metadata are name-value pairs. Pour plus d’informations, consultez l’article Éléments.For more information, see Items.

Scalaires et vecteursScalars and Vectors

Comme les propriétés MSBuild sont des paires nom-valeur qui ont seulement une valeur de chaîne, elles sont souvent décrites en tant que scalaires.Because MSBuild properties are name-value pairs that have just one string value, they are often described as scalar. Comme les types d’élément MSBuild sont des listes d’éléments, ils sont souvent décrits comme des vecteurs.Because MSBuild item types are lists of items, they are often described as vector. Toutefois, en pratique, les propriétés peuvent représenter plusieurs valeurs, et les types d’élément peuvent posséder zéro ou un élément.However, in practice, properties can represent multiple values, and item types can have zero or one items.

Injection de dépendances ciblesTarget Dependency Injection

Pour voir comment les propriétés peuvent représenter plusieurs valeurs, examinez un modèle d’utilisation courante pour ajouter une cible à la liste des cibles à générer.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. Cette liste est généralement représentée par une valeur de propriété, les noms des cibles étant séparés par des points-virgules.This list is typically represented by a property value, with the target names separated by semicolons.

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

La propriété BuildDependsOn est généralement utilisée comme argument d’un attribut DependsOnTargets cible, le convertissant effectivement en une liste d’éléments.The BuildDependsOn property is typically used as the argument of a target DependsOnTargets attribute, effectively converting it to an item list. Cette propriété peut être remplacée pour ajouter une cible ou modifier l’ordre d’exécution des cibles.This property can be overridden to add a target or to change the target execution order. Par exemple :For example,

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

ajoute la cible CustomBuild à la liste des cibles, donnant ainsi à la propriété BuildDependsOn la valeur BeforeBuild;CoreBuild;AfterBuild;CustomBuild.adds the CustomBuild target to the target list, giving BuildDependsOn the value BeforeBuild;CoreBuild;AfterBuild;CustomBuild.

Depuis MSBuild 4.0, l’injection de dépendances cibles est dépréciée.Starting with MSBuild 4.0, target dependency injection is deprecated. L’utilisation des attributs AfterTargets et BeforeTargets est préférable.Use the AfterTargets and BeforeTargets attributes instead. Pour plus d’informations, consultez l’article Ordre de génération des cibles.For more information, see Target Build Order.

Conversion entre des chaînes et des listes d’élémentsConversions between Strings and Item Lists

MSBuild effectue au besoin les conversions vers et depuis des types d’élément et des valeurs de chaîne.MSBuild performs conversions to and from item types and string values as needed. Pour voir comment une liste d’éléments peut devenir une valeur de chaîne, examinez ce qui se passe lorsqu’un type d’élément est utilisé comme valeur d’une propriété 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>  

Le type d’élément OutputDir possède un attribut Include pourvu de la valeur « KeyFiles\;Certificates\ ».The item type OutputDir has an Include attribute with the value "KeyFiles\;Certificates\". MSBuild analyse cette chaîne en deux éléments : KeyFiles\ et Certificates\.MSBuild parses this string into two items: KeyFiles\ and Certificates\. Si le type d’élément OutputDir est utilisé comme valeur de la propriété OutputDirList, MSBuild convertit ou « aplanit » le type d’élément dans la chaîne séparée par des points-virgules « 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\".

Propriétés et éléments des tâchesProperties and Items in Tasks

Les propriétés et éléments sont utilisés comme entrées et sorties pour les tâches MSBuild.Properties and items are used as inputs and outputs to MSBuild tasks. Pour plus d’informations, consultez l’article Tâches MSBuild.For more information, see Tasks.

Les propriétés sont transmises aux tâches en tant qu’attributs.Properties are passed to tasks as attributes. Dans la tâche, une propriété MSBuild est représentée par un type de propriété dont la valeur peut être convertie vers et depuis une chaîne.Within the task, an MSBuild property is represented by a property type whose value can be converted to and from a string. Les types de propriété pris en charge incluent bool, char, DateTime, Decimal, Double, int et string, ainsi que tout type pouvant être géré par ChangeType.The supported property types include bool, char, DateTime, Decimal, Double, int, string, and any type that ChangeType can handle.

Les éléments sont passés aux tâches en tant qu’objets ITaskItem.Items are passed to tasks as ITaskItem objects. Dans la tâche, ItemSpec représente la valeur de l’élément, et GetMetadata récupère ses métadonnées.Within the task, ItemSpec represents the value of the item and GetMetadata retrieves its metadata.

La liste d’éléments d’un type d’élément peut être transmise en tant que tableau d’objets ITaskItem.The item list of an item type can be passed as an array of ITaskItem objects. Depuis .NET Framework 3.5, les éléments peuvent être supprimés d’une liste d’éléments dans une cible à l’aide de l’attribut Remove.Beginning with the .NET Framework 3.5, items can be removed from an item list in a target by using the Remove attribute. Comme les éléments peuvent être supprimés d’une liste d’éléments, un type d’élément peut comporter zéro élément.Because items can be removed from an item list, it is possible for an item type to have zero items. Si une liste d’éléments est transmise à une tâche, le code de la tâche doit vérifier cette possibilité.If an item list is passed to a task, the code in the task should check for this possibility.

Ordre d’évaluation des propriétés et des élémentsProperty and Item Evaluation Order

Pendant la phase d’évaluation d’une génération, les fichiers importés sont incorporés à la génération dans l’ordre dans lequel ils apparaissent.During the evaluation phase of a build, imported files are incorporated into the build in the order in which they appear. Les propriétés et les éléments sont définis en trois passes dans l’ordre suivant :Properties and items are defined in three passes in the following order:

  • Les propriétés sont définies et modifiées dans l’ordre dans lequel elles apparaissent.Properties are defined and modified in the order in which they appear.

  • Les définitions d’élément sont créées et modifiées dans l’ordre dans lequel elles apparaissent.Item definitions are defined and modified in the order in which they appear.

  • Les éléments sont définis et modifiés dans l’ordre dans lequel ils apparaissent.Items are defined and modified in the order in which they appear.

    Pendant la phase d’exécution d’une génération, les propriétés et les éléments qui sont définis dans des cibles sont évalués ensemble en une seule phase dans l’ordre dans lequel ils apparaissent.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.

    Néanmoins, ce n’est pas complet.However, this is not the full story. Lorsqu’une propriété, une définition d’élément ou un élément sont définis, leur valeur est évaluée.When a property, item definition, or item is defined, its value is evaluated. L’évaluateur d’expression développe la chaîne qui spécifie la valeur.The expression evaluator expands the string that specifies the value. Le développement de la chaîne dépend de la phase de la génération.The string expansion is dependent on the build phase. Voici un ordre d’évaluation des éléments et des propriétés plus détaillé :Here is a more detailed property and item evaluation order:

  • Pendant la phase d’évaluation d’une génération :During the evaluation phase of a build:

    • Les propriétés sont définies et modifiées dans l’ordre dans lequel elles apparaissent.Properties are defined and modified in the order in which they appear. Les fonctions de propriétés sont exécutées.Property functions are executed. Les valeurs de propriété de la forme $(PropertyName) sont développées dans des expressions.Property values in the form $(PropertyName) are expanded within expressions. La valeur de propriété est définie sur l’expression développée.The property value is set to the expanded expression.

    • Les définitions d’élément sont créées et modifiées dans l’ordre dans lequel elles apparaissent.Item definitions are defined and modified in the order in which they appear. Les fonctions de propriétés ont déjà été développées dans des expressions.Property functions have already been expanded within expressions. Les valeurs de métadonnées sont définies sur les expressions développées.Metadata values are set to the expanded expressions.

    • Les types d’élément sont définis et modifiés dans l’ordre dans lequel ils apparaissent.Item types are defined and modified in the order in which they appear. Les valeurs d’éléments de la forme @(ItemType) sont développées.Item values in the form @(ItemType) are expanded. Les transformations d’élément sont également développées.Item transformations are also expanded. Les fonctions et valeurs de propriétés ont déjà été développées dans des expressions.Property functions and values have already been expanded within expressions. La liste d’éléments et les valeurs de métadonnées sont définies sur les expressions développées.The item list and metadata values are set to the expanded expressions.

  • Pendant la phase d’exécution d’une génération :During the execution phase of a build:

    • Les propriétés et les éléments qui sont définis dans des cibles sont évalués ensemble dans l’ordre dans lequel ils apparaissent.Properties and items that are defined within targets are evaluated together in the order in which they appear. Les fonctions de propriétés sont exécutées, et les valeurs de propriétés sont développées dans des expressions.Property functions are executed and property values are expanded within expressions. Les valeurs d’éléments et les transformations d’élément sont également développées.Item values and item transformations are also expanded. Les valeurs de propriétés, les valeurs de types d’élément et les valeurs de métadonnées sont définies sur les expressions développées.The property values, item type values, and metadata values are set to the expanded expressions.

Effets discrets de l’ordre d’évaluationSubtle Effects of the Evaluation Order

Dans la phase d’évaluation d’une génération, l’évaluation des propriétés précède celle des éléments.In the evaluation phase of a build, property evaluation precedes item evaluation. Néanmoins, les valeurs de certaines propriétés peuvent sembler dépendre des valeurs d’éléments.Nevertheless, properties can have values that appear to depend on item values. Examinez le script ci-dessous.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>  

L’exécution de la tâche Message affiche ce message :Executing the Message task displays this message:

KeyFileVersion: 1.0.0.3  

C’est parce que la valeur de KeyFileVersion correspond réellement à la chaîne « @(KeyFile->'%(Version)') ».This is because the value of KeyFileVersion is actually the string "@(KeyFile->'%(Version)')". Comme l’élément et les transformations d’élément n’ont pas été développés lorsque la propriété a été définie, la valeur de la chaîne non développée a été affectée à la propriété 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.

Pendant la phase d’exécution de la génération, quand il traite la tâche Message, MSBuild développe la chaîne « @(KeyFile->'%(Version)') » pour générer « 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".

Notez que le même message s’affiche même si les groupes de propriétés et d’éléments ont été annulés dans l’ordre.Notice that the same message would appear even if the property and item groups were reversed in order.

Pour illustrer un deuxième exemple, examinez ce qui peut se produire lorsque des groupes de propriétés et d’éléments se trouvent dans des cibles :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>  

La tâche Message affiche le message suivant :The Message task displays this message:

KeyFileVersion:   

En effet, pendant la phase d’exécution de la génération, les groupes de propriétés et d’éléments définis dans des cibles sont évalués simultanément de haut en bas.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. Lorsque la propriété KeyFileVersion est définie, KeyFile est inconnu.When KeyFileVersion is defined, KeyFile is unknown. Par conséquent, la transformation d’élément se développe en une chaîne vide.Therefore, the item transformation expands to an empty string.

Dans ce cas, l’inversion de l’ordre des groupes de propriétés et d’éléments restaure le message d’origine :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 prend la valeur « 1.0.0.3 » et non « @(KeyFile->'%(Version)') ».The value of KeyFileVersion is set to "1.0.0.3" and not to "@(KeyFile->'%(Version)')". La tâche Message affiche le message suivant :The Message task displays this message:

KeyFileVersion: 1.0.0.3  

Voir aussiSee Also

Concepts avancésAdvanced Concepts