MSBuild (tâche)

  • Article

Génère des projets MSBuild à partir d’un autre projet MSBuild.

Paramètres

Le tableau ci-dessous décrit les paramètres de la tâche MSBuild .

Paramètre Description
BuildInParallel Paramètre Boolean facultatif.

Si true, les projets spécifiés dans le paramètre Projects sont générés en parallèle dans la mesure du possible. La valeur par défaut est false.
Projects Paramètre ITaskItem[] obligatoire.

Spécifie les fichiers projet à générer.
Properties Paramètre String facultatif.

Liste délimitée par des points-virgules de paires nom/valeur de propriété à appliquer en tant que propriétés globales au projet enfant. Si vous spécifiez ce paramètre, son fonctionnement revient à définir des propriétés dotées du commutateur -property lors du build avec MSBuild.exe. Par exemple :

Properties="Configuration=Debug;Optimize=$(Optimize)"

Quand vous passez des propriétés au projet via le paramètre Properties, MSBuild peut créer une instance du projet même si le fichier projet a déjà été chargé. MSBuild crée une seule instance de projet pour un chemin de projet donné ainsi qu’un ensemble unique de propriétés globales. Par exemple, ce comportement vous permet de créer plusieurs tâches MSBuild qui appellent myproject.proj avec Configuration=Release, et vous obtenez une seule instance de myproject.proj (si aucune propriété unique n’est spécifiée dans la tâche). Si vous spécifiez une propriété qui n’a pas encore été vue par MSBuild, ce dernier crée une instance du projet, qui peut être générée parallèlement à d’autres instances du projet. Par exemple, une configuration Release peut être générée en même temps qu’une configuration Debug.
RebaseOutputs Paramètre Boolean facultatif.

Si true, les chemins d’accès relatifs des éléments de sortie cibles des projets générés sont modifiés par rapport au projet appelant. La valeur par défaut est false.
RemoveProperties Paramètre String facultatif.

Spécifie l’ensemble des propriétés globales à supprimer.
RunEachTargetSeparately Paramètre Boolean facultatif.

Si true, la tâche MSBuild appelle une à une chaque cible de la liste transmise à MSBuild, au lieu de les appeler toutes en même temps. Définir ce paramètre sur true garantit que les cibles ultérieures seront appelées même en cas d’échec des cibles précédemment appelées. Dans le cas contraire, une erreur de génération arrêterait l’appel de toutes les cibles suivantes. La valeur par défaut est false.
SkipNonexistentProjects Paramètre Boolean facultatif.

Si true, les fichiers projet qui n’existent pas sur le disque sont ignorés. Dans le cas contraire, ces projets provoquent une erreur. La valeur par défaut est false.
SkipNonexistentTargets Paramètre Boolean facultatif.

Si true, les fichiers projet qui existent mais qui ne contiennent pas le Targets nommé sont ignorés. Dans le cas contraire, ces projets provoquent une erreur. La valeur par défaut est false. Introduit dans MSBuild 15.5.
StopOnFirstFailure Paramètre Boolean facultatif.

Si true, en cas d’échec de génération de l’un des projets, aucun autre projet n’est généré. Pour le moment, cela n’est pas pris en charge lors de la génération en parallèle (avec plusieurs processeurs).
TargetAndPropertyListSeparators Paramètre String[] facultatif.

Spécifie une liste de cibles et de propriétés en tant que métadonnées d’élément Project. Avant le traitement, les séparateurs sont retirés de la séquence d’échappement. Par exemple, %3B (caractère « ; » inséré dans une séquence d’échappement) est traité comme s’il s’agissait du caractère « ; » sans séquence d’échappement.
TargetOutputs Paramètre de sortie en lecture seule ITaskItem[] facultatif.

Retourne les sorties des cibles générées à partir de tous les fichiers projet. Seules les sorties des cibles spécifiées sont retournées. Les sorties qui peuvent exister sur les cibles dont dépendent ces cibles ne sont pas retournées.

Le paramètre TargetOutputs contient également les métadonnées suivantes :

- MSBuildSourceProjectFile : fichier projet MSBuild qui contient la cible qui a défini les sorties.
- MSBuildSourceTargetName : cible qui a défini les sorties. Remarque : si vous souhaitez identifier les sorties de chaque fichier projet ou de chaque cible séparément, exécutez la tâche MSBuild séparément pour chaque fichier projet ou cible. Si vous exécutez la tâche MSBuild une seule fois pour générer tous les fichiers projet, les sorties de toutes les cibles sont collectées dans un seul tableau.
Targets Paramètre String facultatif.

Spécifie la ou les cibles à générer dans les fichiers projet. Utilisez un point-virgule pour séparer les noms de cibles dans la liste. Si aucune cible n’est spécifiée dans la tâche MSBuild, les cibles par défaut spécifiées dans les fichiers projet sont créées. Remarque : les cibles doivent exister dans tous les fichiers projet. Si tel n’est pas le cas, une erreur de génération se produit.
ToolsVersion Paramètre String facultatif.

Spécifie la ToolsVersion à utiliser lors de la génération des projets transmis à cette tâche.

Permet à une tâche MSBuild de générer un projet qui cible une version du .NET Framework différente de celle spécifiée dans le projet. Les valeurs valides sont 2.0, 3.0 et 3.5. La valeur par défaut est 3.5.

Notes

En plus des paramètres énumérés ci-dessus, cette tâche hérite des paramètres de la classe TaskExtension , qui elle-même hérite de la classe Task . Pour obtenir la liste de ces paramètres supplémentaires et leurs descriptions, consultez Classe de base TaskExtension.

Contrairement à l’utilisation de la tâche Exec pour démarrer MSBuild.exe, cette tâche utilise le même processus MSBuild pour générer les projets enfants. La liste des cibles déjà générées qui peuvent être ignorées est partagée entre la génération parente et les générations enfants. Cette tâche est également plus rapide, car aucun nouveau processus MSBuild n’est créé.

Cette tâche peut traiter non seulement les fichiers projet, mais également les fichiers solution.

Toute configuration requise par MSBuild pour permettre la génération simultanée des projets, même si la configuration implique une infrastructure distante (par exemple, des ports, protocoles, délais d’attente, tentatives, etc.) doit être rendue configurable à l’aide d’un fichier de configuration. Dans la mesure du possible, il convient de spécifier les éléments de configuration comme paramètres de tâche dans la tâche MSBuild.

Depuis MSBuild 3.5, les projets solution surfacent TargetOutputs depuis tous les sous-projets générés.

Transmettre des propriétés aux projets

Dans les versions de MSBuild antérieures à 3.5, la transmission des différents ensembles de propriétés aux différents projets répertoriés dans l’élément MSBuild était difficile. Si vous utilisiez l’attribut Properties de la tâche MSBuild, son paramètre était appliqué à tous les projets générés à moins que vous n’ayez traité par lot la tâche MSBuild et fourni de façon conditionnelle des propriétés différentes pour chaque projet de la liste d’éléments.

MSBuild 3.5 propose néanmoins deux nouveaux éléments de métadonnées réservés, Properties et AdditionalProperties, qui vous permettent de passer de manière flexible les différentes propriétés de plusieurs projets en cours de génération à l’aide de la tâche MSBuild.

Notes

Ces nouveaux éléments de métadonnées s’appliquent uniquement aux éléments transmis dans l’attribut Projects de la tâche MSBuild.

Avantages de la génération multiprocesseur

L’un des principaux avantages liés à l’utilisation de ces nouvelles métadonnées se présente lorsque vous générez vos projets en parallèle sur un système multiprocesseur. Les métadonnées vous permettent de consolider tous les projets dans un seul et même appel de tâche MSBuild sans devoir effectuer de traitement par lot ou de tâches MSBuild conditionnelles. Si vous appelez une seule tâche MSBuild, tous les projets répertoriés dans l’attribut Projects sont générés en parallèle. (Toutefois cela se produit uniquement si l’attribut BuildInParallel=true est présent dans la tâche MSBuild.) Pour plus d’informations, consultez Générer plusieurs projets en parallèle.

Métadonnées Properties

Quand elles sont spécifiées, les métadonnées Properties remplacent le paramètre Propriétés de la tâche, alors que les métadonnées AdditionalProperties sont ajoutées aux définitions du paramètre.

Lorsque vous générez plusieurs fichiers solution à l’aide de la tâche MSBuild, il est courant d’utiliser uniquement différentes configurations de build. Vous souhaiterez peut-être générer la solution a1 à l’aide de la configuration Debug, et la solution a2 à l’aide de la configuration Release. Dans MSBuild 2.0, ce fichier projet ressemblerait à ce qui suit :

Notes

Dans l’exemple suivant, « ... » représente des fichiers solution supplémentaires.

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

En utilisant les métadonnées Properties, vous pouvez néanmoins simplifier cela pour utiliser une seule tâche MSBuild, comme indiqué ci-après :

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

- ou -

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln..."/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Debug"/>
    </Target>
</Project>

Métadonnées AdditionalProperties

Considérez le scénario suivant où vous générez deux fichiers solution à l’aide de la tâche MSBuild, tous deux utilisant la configuration Release, mais l’un avec l’architecture x86 et l’autre avec l’architecture ia64. Dans MSBuild 2.0, vous devriez créer plusieurs instances de la tâche MSBuild : l’une pour générer le projet à l’aide de la configuration Release avec l’architecture x86, et l’autre à l’aide de la configuration Release avec l’architecture ia64. Votre fichier projet ressemblerait à ce qui suit :

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Release;
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release;
          Architecture=ia64"/>
    </Target>
</Project>

En utilisant les métadonnées AdditionalProperties, vous pouvez simplifier cela pour utiliser une seule tâche MSBuild de la manière suivante :

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Release"/>
    </Target>
</Project>

Exemple

L’exemple suivant utilise la tâche MSBuild pour générer les projets spécifiés par la collection d’éléments ProjectReferences. Les sorties cibles obtenues sont stockées dans la collection d’éléments AssembliesBuiltByChildProjects.

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

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

Voir aussi