Partager via

Configurer les cibles et les tâches

  • Article

Les tâches MSBuild sélectionnées peuvent être définies pour s’exécuter dans l’environnement qu’elles ciblent, lorsque l’ordinateur de développement prend en charge l’environnement cible. Par exemple, quand vous utilisez un ordinateur Windows 64 bits pour générer une application ciblant une architecture Windows 32 bits, les tâches sélectionnées sont exécutées dans un processus 32 bits.

Notes

Si une tâche de génération est écrite dans un langage .NET, comme Visual C# ou Visual Basic, et qu’elle n’utilise pas des ressources natives ou des outils natifs, elle est exécutée dans un contexte cible sans adaptation.

Attributs UsingTask et paramètres de tâche

Les attributs UsingTask suivants affectent toutes les opérations d’une tâche dans un processus de génération spécifique :

  • L’attribut Runtime, s’il est présent, définit la version du common language runtime (CLR) et peut prendre une des valeurs suivantes : CLR2, CLR4, CurrentRuntime ou * (n’importe quel runtime).

  • L’attribut Architecture, s’il est présent, définit la plateforme et le nombre de bits, et peut prendre une des valeurs suivantes : x86, x64, CurrentArchitecture ou * (n’importe quelle architecture).

  • L’attribut TaskFactory, s’il est présent, définit la fabrique de tâches qui crée et exécute l’instance de tâche, et il prend uniquement la valeur TaskHostFactory. Pour plus d’informations, consultez la section Fabriques de tâches plus loin dans ce document.

<UsingTask TaskName="SimpleTask"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v3.5.dll" />

Vous pouvez également utiliser les paramètres MSBuildRuntime et MSBuildArchitecture pour définir le contexte cible d’une invocation de tâche individuelle.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Avant que MSBuild exécute une tâche, il recherche un attribut UsingTask qui a le même contexte cible. Les paramètres spécifiés dans l’attribut UsingTask mais qui ne sont pas dans la tâche correspondante sont considérés comme étant en correspondance. Les paramètres spécifiés dans la tâche mais qui ne sont pas dans l’attribut UsingTask correspondant sont également considérés comme étant en correspondance. Si des valeurs de paramètre ne sont pas spécifiées dans l’attribut UsingTask ou dans la tâche, leur valeur par défaut est * (n’importe quel paramètre).

Avertissement

S’il existe plus d’un UsingTask et que tous ont des attributs TaskName, Runtime et Architecture correspondants, le premier à être évalué remplace les autres. Cela diffère du comportement des éléments Property et Target.

Si des paramètres sont définis sur la tâche, MSBuild tente de trouver un attribut UsingTask qui correspond à ces paramètres ou qui au moins n’est pas en conflit avec ceux-ci. Plusieurs attributs UsingTask peuvent spécifier le contexte cible de la même tâche. Par exemple, une tâche qui a des exécutables différents pour des environnements cibles différents peut se présenter comme ceci :

<UsingTask TaskName="MyTool"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.v2.0.dll" />

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Remplacement de la valeur par défaut UsingTasks

Par défaut, MSBuild gère UsingTask comme « le premier gagne ». À partir de la version 17.2, MSBuild prend en charge le remplacement de ce comportement via le paramètre Override. Un UsingTask avec le paramètre Override défini sur true prendra la priorité sur n’importe quel autre UsingTask du même TaskName.

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    Override="true"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

Avertissement

Cette opération ne peut être effectuée qu’une seule fois par tâche. Les builds qui tentent d’ajouter plusieurs remplacements pour la même tâche recevront l’erreur MSBuild MSB4275.

Fabriques de tâches

Le tableau suivant montre les fabriques de tâches fournies par l’installation de MSBuild :

Fabrique de tâches Description
AssemblyTaskFactory Il s’agit de la valeur par défaut. Exécute la tâche in-process.
TaskHostFactory Exécute la tâche hors processus.
RoslynCodeTaskFactory Pour les tâches inline écrites en C# ou Visual Basic et ciblant .NET Standard ; fonctionne à la fois avec msbuild.exe et dotnet build.
CodeTaskFactory Pour les tâches inline écrites en C# ou Visual Basic et ciblant .NET Framework ; fonctionne uniquement avec msbuild.exe.

Le mécanisme de fabrique de tâches est extensible. Vous pouvez donc également utiliser celles créées par des tiers ou créer les vôtres. Vous pourriez par exemple vouloir en créer une pour prendre en charge un autre langage pour l’écriture de tâches inline.

TaskHostFactory

Avant d’exécuter une tâche, MSBuild vérifie si elle est désignée pour s’exécuter dans le contexte logiciel actif. Si la tâche est bien désignée pour cela, MSBuild la passe à AssemblyTaskFactory, qui s’exécute dans le processus actif ; dans le cas contraire, MSBuild passe la tâche à TaskHostFactory, qui exécute la tâche dans un processus qui correspond au contexte cible. Même si le contexte actif et le contexte cible correspondent, vous pouvez forcer une tâche à s’exécuter hors processus (pour l’isolation, la sécurité ou pour d’autres raisons) en définissant TaskFactory sur TaskHostFactory.

<UsingTask TaskName="MisbehavingTask"
    TaskFactory="TaskHostFactory"
    AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll">
</UsingTask>

Quand TaskHostFactory est spécifié explicitement, le processus qui exécute la tâche est de courte durée. Cela permet au système d’exploitation de nettoyer toutes les ressources liées à la tâche immédiatement après son exécution. Pour cette raison, spécifiez TaskHostFactory lors du référencement des tâches générées dans le même processus de build que leur utilisation, afin d’éviter les erreurs de fichier en cours d’utilisation lors de la mise à jour de l’assembly de tâches après une build.

RoslynCodeTaskFactory

RoslynCodeTaskFactory fournit un mécanisme par lequel vous pouvez écrire du code C# ou Visual Basic pour une tâche dans un fichier projet pour une utilisation immédiate. Le code est compilé lors du processus de génération pour produire une tâche que vous pouvez exécuter dans cette même version. Le code que vous écrivez cible .NET Standard, afin qu’il puisse être utilisé lors de l’exécution de dotnet build, qui utilise la version .NET Core (et .NET 5 et versions ultérieures) de MSBuild, ainsi que msbuild.exe, qui utilise .NET Framework. RoslynCodeTaskFactory est préférable pour les personnalisations qui sont un peu trop difficiles à faire en logique MSBuild, mais pas assez pour justifier la création d’un projet distinct. Consultez Créer une tâche inlined MSBuild avec RoslynCodeTaskFactory.

CodeTaskFactory

CodeTaskFactory est une version antérieure de RoslynCodeTaskFactory, limitée à la version .NET Framework de MSBuild. Consultez Tâches inline MSBuild. Cette fabrique de tâches est prise en charge, mais le code plus récent doit utiliser RoslynCodeTaskFactory pour une applicabilité plus large.

Paramètres de tâche fantôme

Comme tous les autres paramètres de tâche, MSBuildRuntime et MSBuildArchitecture peuvent être définis à partir de propriétés de génération.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <FrameworkVersion>3.0</FrameworkVersion>
    </PropertyGroup>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="$(FrameworkVerion)" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Contrairement à d’autres paramètres de tâche, MSBuildRuntime et MSBuildArchitecture ne sont pas visibles pour la tâche elle-même. Pour écrire une tâche qui tient compte du contexte dans lequel elle s’exécute, vous devez tester le contexte en appelant le .NET Framework ou utiliser les propriétés de la build pour passer les informations de contexte avec d’autres paramètres de la tâche.

Notes

Les attributs UsingTask peuvent être définis à partir des propriétés d’ensemble d’outils et d’environnement.

Les paramètres MSBuildRuntime et MSBuildArchitecture représentent le moyen le plus simple de définir le contexte cible, mais également le plus limité en portée. D’une part, comme ils sont définis sur l’instance de tâche et ne sont pas évalués tant que la tâche n’est pas sur le point d’être exécutée, ils peuvent dériver leur valeur à partir de la portée complète des propriétés disponibles au moment de l’évaluation et au moment de la génération. D’autre part, ces paramètres s’appliquent uniquement à une instance particulière d’une tâche dans une cible particulière.

Notes

Les paramètres de tâche sont évalués dans le contexte du nœud parent et non dans le contexte de l’hôte de tâche. Les variables d’environnement qui dépendent du runtime ou de l’architecture (par exemple, l’emplacement des fichiers programme) correspondent à la valeur associée au nœud parent. Toutefois, si la même variable d’environnement est lue directement par la tâche, elle est correctement évaluée dans le contexte de l’hôte de tâche.

Contenu connexe