Builds incrémentiellesIncremental builds

Les builds incrémentielles sont des builds optimisées qui permettent de ne pas exécuter les cibles dont les fichiers de sortie sont à jour par rapport à leurs fichiers d’entrée correspondants.Incremental builds are builds that are optimized so that targets that have output files that are up-to-date with respect to their corresponding input files are not executed. Un élément cible peut avoir à la fois un attribut Inputs, qui indique les éléments que la cible attend comme entrée, et un attribut Outputs qui indique les éléments qu’il produit comme sortie.A target element can have both an Inputs attribute, which indicates what items the target expects as input, and an Outputs attribute, which indicates what items it produces as output. MSBuild tente de trouver une correspondance « 1 à 1 » entre les valeurs de ces attributs.MSBuild attempts to find a 1-to-1 mapping between the values of these attributes. Si une correspondance « 1 à 1 » existe, MSBuild compare l’horodatage de chaque élément d’entrée avec celui de l’élément de sortie correspondant.If a 1-to-1 mapping exists, MSBuild compares the time stamp of every input item to the time stamp of its corresponding output item. Les fichiers de sortie sans correspondance « 1 à 1 » sont comparés à tous les fichiers d’entrée.Output files that have no 1-to-1 mapping are compared to all input files. Un élément est considéré comme à jour si son fichier de sortie a une date de création identique ou antérieure à celle du ou des fichiers d’entrée.An item is considered up-to-date if its output file is the same age or newer than its input file or files.

Notes

Lorsque MSBuild évalue les fichiers d’entrée, seul le contenu de la liste dans l’exécution actuelle est pris en compte.When MSBuild evaluates the input files, only the contents of the list in the current execution are considered. Les modifications apportées à la liste à partir de la dernière version ne rendent pas automatiquement une cible périmée.Changes in the list from the last build do not automatically make a target out-of-date.

Si tous les éléments de sortie sont à jour, MSBuild ignore la cible.If all output items are up-to-date, MSBuild skips the target. Cette build incrémentielle de la cible peut améliorer considérablement la vitesse de génération.This incremental build of the target can significantly improve the build speed. Si seuls certains fichiers sont à jour, MSBuild exécute la cible en ignorant les éléments à jour, pour que tous les éléments soient à jour.If only some files are up-to-date, MSBuild executes the target but skips the up-to-date items, and thereby brings all items up-to-date. Ce processus est appelé « build incrémentielle partielle ».This process is known as a partial incremental build.

Les correspondances « 1 à 1 » sont généralement produites par des transformations d’éléments.1-to-1 mappings are typically produced by item transformations. Pour plus d’informations, consultez l’article Transforms (Transformations MSBuild).For more information, see Transforms.

Examinons la cible suivante.Consider the following target.

<Target Name="Backup" Inputs="@(Compile)"
    Outputs="@(Compile->'$(BackupFolder)%(Identity).bak')">
    <Copy SourceFiles="@(Compile)" DestinationFiles=
        "@(Compile->'$(BackupFolder)%(Identity).bak')" />
</Target>

Le jeu de fichiers représenté par le type d’élément Compile est copié dans un répertoire de sauvegarde.The set of files represented by the Compile item type is copied to a backup directory. Les fichiers de sauvegarde ont l’extension de nom de fichier .bak.The backup files have the .bak file name extension. Si les fichiers représentés par le type d’élément Compile, ou les fichiers de sauvegarde correspondants, ne sont pas supprimés ou modifiés après l’exécution de la cible de sauvegarde, celle-ci est ignorée dans les builds suivantes.If the files represented by the Compile item type, or the corresponding backup files, are not deleted or modified after the Backup target is run, then the Backup target is skipped in subsequent builds.

Inférence de sortieOutput inference

MSBuild compare les attributs Inputs et Outputs d’une cible pour déterminer si celle-ci doit être exécutée.MSBuild compares the Inputs and Outputs attributes of a target to determine whether the target has to execute. Dans l’idéal, le jeu de fichiers qui existe après une build incrémentielle doit rester le même, que les cibles associées soient exécutées ou non.Ideally, the set of files that exists after an incremental build is completed should remain the same whether or not the associated targets are executed. Étant donné que les propriétés et les éléments qui sont créés ou modifiés par les tâches peuvent affecter la build, MSBuild doit déduire leurs valeurs, même si la cible associée est ignorée.Because properties and items that are created or altered by tasks can affect the build, MSBuild must infer their values even if the target that affects them is skipped. Ce processus est appelé « inférence de sortie ».This process is known as output inference.

Celle-ci s’utilise dans trois cas :There are three cases:

  • La cible a un attribut Condition dont la valeur est false.The target has a Condition attribute that evaluates to false. Dans ce cas, la cible n’est pas exécutée et n’a aucun effet sur la build.In this case, the target is not run, and has no effect on the build.

  • La cible comprend des sorties obsolètes, et est donc exécutée pour les mettre à jour.The target has out-of-date outputs and is run to bring them up-to-date.

  • La cible ne comprend aucune sortie obsolète, et est donc ignorée.The target has no out-of-date outputs and is skipped. MSBuild évalue la cible et apporte des modifications aux éléments et aux propriétés comme si la cible avait été exécutée.MSBuild evaluates the target and makes changes to items and properties as if the target had been run.

Pour que la compilation incrémentielle soit prise en charge, les tâches doivent vérifier que la valeur de l’attribut TaskParameter d’un élément Output est égale à un paramètre d’entrée de tâche.To support incremental compilation, tasks must ensure that the TaskParameter attribute value of any Output element is equal to a task input parameter. Voici quelques exemples :Here are some examples:

<CreateProperty Value="123">
    <Output PropertyName="Easy" TaskParameter="Value" />
</CreateProperty>

Ce code crée la propriété Easy, dont la valeur est « 123 », que la cible ait été ou non exécutée ou ignorée.This code creates the property Easy, which has the value "123" whether or not the target is executed or skipped.

À compter de MSBuild 3.5, l’inférence de sortie est exécutée automatiquement sur les groupes de propriétés et d’éléments de la cible.Starting in MSBuild 3.5, output inference is performed automatically on item and property groups in a target. Les tâches CreateItem ne sont pas obligatoires dans la cible et doivent être évitées.CreateItem tasks are not required in a target and should be avoided. De plus, les tâches CreateProperty ne doivent être utilisées dans une cible que pour déterminer si celle-ci a été exécutée.Also, CreateProperty tasks should be used in a target only to determine whether a target has been executed.

Avant MSBuild 3.5, vous pouvez utiliser la tâche CreateItem.Prior to MSBuild 3.5, you can use the CreateItem task.

Déterminer si une cible a été exécutéeDetermine whether a target has been run

En raison de l’inférence de sortie, vous devez ajouter une tâche CreateProperty à une cible pour examiner les propriétés et les éléments, et ainsi, déterminer si la cible a été exécutée.Because of output inference, you have to add a CreateProperty task to a target to examine properties and items so that you can determine whether the target has been executed. Ajoutez la tâche CreateProperty à la cible et attribuez-lui un élément Output dont le TaskParameter est défini sur « ValueSetByTask ».Add the CreateProperty task to the target and give it an Output element whose TaskParameter is "ValueSetByTask".

<CreateProperty Value="true">
    <Output TaskParameter="ValueSetByTask" PropertyName="CompileRan" />
</CreateProperty>

Ce code crée la propriété CompileRan et lui attribue la valeur true, mais uniquement si la cible est exécutée.This code creates the property CompileRan and gives it the value true, but only if the target is executed. Si la cible est ignorée, CompileRan n’est pas créé.If the target is skipped, CompileRan is not created.

Voir aussiSee also