Tâches inline MSBuild
En général, les tâches MSBuild sont créées en compilant une classe qui implémente l'interface ITask. Pour plus d'informations, consultez Tâches MSBuild.
A partir de .NET Framework version 4, créez des tâches inline dans le fichier projet. Vous n'avez pas besoin de créer un assembly séparé pour héberger la tâche. Cela simplifie le suivi du code source et le déploiement de la tâche. Le code source est intégré dans le script.
Structure d'une tâche inline
Une tâche inline est contenue par un élément UsingTask. En général, la tâche inline et l'élément UsingTask qui la contient sont inclus dans un fichier .targets et importés dans d'autres fichiers projet selon les besoins. Voici une tâche inline de base. Remarquez qu'elle ne fait rien.
<Project ToolsVersion="12.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<!-- This simple inline task does nothing. -->
<UsingTask
TaskName="DoNothing"
TaskFactory="CodeTaskFactory"
AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v12.0.dll" >
<ParameterGroup />
<Task>
<Reference Include="" />
<Using Namespace="" />
<Code Type="Fragment" Language="cs">
</Code>
</Task>
</UsingTask>
</Project>
L'élément UsingTask de l'exemple comporte trois attributs qui décrivent la tâche et la fabrique de tâches inline qui la compile.
L'attribut TaskName nomme la tâche, dans ce cas, DoNothing.
L'attribut TaskFactory nomme la classe qui implémente la fabrique de tâches inline.
L'attribut AssemblyFile donne l'emplacement de la fabrique de tâches inline. Vous pouvez également utiliser l'attribut AssemblyName pour spécifier le nom qualifié complet de la classe de la fabrique de tâches inline, qui se situe généralement dans le Global Assembly Cache (GAC).
Les éléments restants de la tâche DoNothing sont vides ; ils sont fournis pour illustrer l'ordre et la structure d'une tâche inline. Un exemple plus pertinent est présenté plus loin dans cette rubrique.
L'attribut ParameterGroup est facultatif. S'il est spécifié, il déclare les paramètres de la tâche. Pour plus d'informations sur les paramètres d'entrée et de sortie, consultez « Paramètres d'entrée et de sortie » plus loin dans cette rubrique.
L'élément Task décrit et contient le code source de tâche.
L'élément Reference spécifie des références aux assemblys .NET que vous utilisez dans votre code. Cela équivaut à ajouter une référence à un projet dans Visual Studio. L'attribut Include spécifie le chemin d'accès de l'assembly référencé.
L'élément Using répertorie les espaces de noms auxquels vous souhaitez accéder. Cela ressemble à l'instruction Using dans Visual C#. L'attribut Namespace spécifie l'espace de noms à inclure.
Les éléments Reference et Using n'ont pas de langage spécifié. Les tâches inline peuvent être écrites dans l'un des langages CodeDom .NET pris en charge, par exemple, Visual Basic ou Visual C#.
Notes
Les éléments contenus par l'élément Task sont spécifiques à la fabrique de tâches, dans ce cas, la fabrique de tâches de code.
Élément Code
Le dernier élément enfant à apparaître dans l'élément Task est l'élément Code. L'élément Code contient ou trouve le code à compiler dans une tâche. Ce que vous mettez dans l'élément Code dépend de la manière dont vous souhaitez écrire la tâche.
L'attribut Language spécifie le langage dans lequel le code est écrit. Les valeurs acceptables sont cs pour C#, vb pour Visual Basic.
L'attribut Type spécifie le type de code trouvé dans l'élément Code.
Si la valeur de Type est Classe, l'élément Code contient le code pour une classe qui dérive de l'interface ITask.
Si la valeur de Type est Méthode, le code définit une substitution de la méthode Execute de l'interface ITask.
Si la valeur de Type est Fragment, le code définit le contenu de la méthode Execute, mais pas la signature ou l'instruction return.
Le code lui-même apparaît généralement entre un marqueur <![CDATA[ et un marqueur ]]>. Étant donné que le code se trouve dans une section CDATA, vous n'avez pas à vous préoccuper de l'échappement de caractères réservés, par exemple, "<" ou ">".
Vous pouvez également utiliser l'attribut Source de l'élément Code afin de spécifier l'emplacement d'un fichier qui contient le code pour votre tâche. Le code dans le fichier source doit avoir le type spécifié par l'attribut Type. Si l'attribut Source est présent, la valeur par défaut de Type est Classe. Si Source n'est pas présent, la valeur par défaut est Fragment.
Notes
Lors de la définition de la classe de tâche dans le fichier source, le nom de classe doit être cohérent avec l'attribut TaskName de l'élément UsingTask correspondant.
Hello World
Voici une tâche inline plus fiable. La tâche HelloWorld affiche « Hello, world! » sur le périphérique de journalisation des erreurs par défaut, qui est généralement la console système ou la fenêtre Sortie de Visual Studio. L'élément Reference dans l'exemple est inclus à des fins d'illustration uniquement.
<Project ToolsVersion="12.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<!-- This simple inline task displays "Hello, world!" -->
<UsingTask
TaskName="HelloWorld"
TaskFactory="CodeTaskFactory"
AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v4.0.dll" >
<ParameterGroup />
<Task>
<Reference Include="System.Xml.dll"/>
<Using Namespace="System"/>
<Using Namespace="System.IO"/>
<Code Type="Fragment" Language="cs">
<![CDATA[
// Display "Hello, world!"
Log.LogError("Hello, world!");
]]>
</Code>
</Task>
</UsingTask>
</Project>
Vous pouvez enregistrer la tâche HelloWorld dans un fichier nommé HelloWorld.targets, puis l'appeler à partir d'un projet, comme suit.
<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<Import Project="HelloWorld.targets" />
<Target Name="Hello">
<HelloWorld />
</Target>
</Project>
Paramètres d'entrée et de sortie
Les paramètres de tâche inline sont des éléments enfants d'un élément ParameterGroup. Chaque paramètre prend le nom de l'élément qui le définit. Le code suivant définit le paramètre Text.
<ParameterGroup>
<Text />
</ParameterGroup>
Les paramètres peuvent avoir un ou plusieurs de ces attributs :
Required est un attribut facultatif avec la valeur false par défaut. S'il a la valeur true, le paramètre est obligatoire et une valeur doit lui être affectée avant l'appel de la tâche.
ParameterType est un attribut facultatif avec la valeur System.String par défaut. Il peut avoir tout type qualifié complet qui correspond à un élément ou une valeur pouvant être converti depuis et vers une chaîne à l'aide de System.Convert.ChangeType. (En d'autres termes, tout type qui peut être passé à et depuis une tâche externe.)
Output est un attribut facultatif avec la valeur false par défaut. S'il a la valeur true, le paramètre doit se voir affecter une valeur avant le retour de la méthode Execute.
Par exemple :
<ParameterGroup>
<Expression Required="true" />
<Files ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />
<Tally ParameterType="System.Int32" Output="true" />
</ParameterGroup>
définit ces trois paramètres :
Expression est un paramètre d'entrée obligatoire de type System.String.
Files est un paramètre d'entrée de liste d'éléments obligatoire.
Tally est un paramètre de sortie de type System.Int32.
Si l'élément Code a l'attribut Type avec la valeur Fragment ou Méthode, les propriétés sont créées automatiquement pour chaque paramètre. Sinon, les propriétés doivent être déclarées explicitement dans le code source de tâche et doivent correspondre exactement à leurs définitions de paramètre.
Exemple
La tâche inline suivante remplace chaque occurrence d'un jeton dans le fichier donné par la valeur donnée.
<Project xmlns='https://schemas.microsoft.com/developer/msbuild/2003' ToolsVersion="12.0">
<UsingTask TaskName="TokenReplace" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v12.0.dll">
<ParameterGroup>
<Path ParameterType="System.String" Required="true" />
<Token ParameterType="System.String" Required="true" />
<Replacement ParameterType="System.String" Required="true" />
</ParameterGroup>
<Task>
<Code Type="Fragment" Language="cs"><![CDATA[
string content = File.ReadAllText(Path);
content = content.Replace(Token, Replacement);
File.WriteAllText(Path, content);
]]></Code>
</Task>
</UsingTask>
<Target Name='Demo' >
<TokenReplace Path="C:\Project\Target.config" Token="$MyToken$" Replacement="MyValue"/>
</Target>
</Project>
Voir aussi
Tâches
Procédure pas à pas : création d'une tâche inline