Génération de code dans un processus de génération
Vous pouvez appeler la transformation de texte dans le cadre du processus de génération d'une solution Visual Studio. Vous pouvez utiliser ceci pour vérifier que les fichiers générés à partir des modèles sont à jour avant leur compilation. Cela vous permet d'éviter une situation où l'utilisateur oublie de cliquer sur Transformer tous les modèles avant de générer le projet ou d'archiver le code. Les tâches de transformation de texte peuvent être effectuées par Visual Studio ou MSBuild, et sur un serveur de builds.
Insertion de tâches de transformation de texte dans les fichiers projet
Installer le Kit de développement logiciel de visualisation et de modélisation
Pour permettre les tâches de génération sur votre ordinateur de développement, installez Visual Studio Visualization and Modeling SDK.
Pour permettre les tâches de génération sur un serveur de builds, consultez Transformation de texte sur un serveur de builds.
Modification du fichier projet
Pour appeler la transformation de texte, vous devez modifier le fichier qui définit votre projet. Ces propriétés ne peuvent pas être modifiées dans l'éditeur de propriétés du projet. Par conséquent, vous devez fermer le projet et le modifier sous forme de fichier texte.
Pour modifier le texte du fichier projet
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis cliquez sur Décharger le projet.
Cliquez de nouveau avec le bouton droit sur le projet, puis cliquez sur Modifier projet.
Le texte du fichier projet s'affiche dans l'éditeur XML.
Pour rouvrir le projet une fois que vous l'avez modifié
Fermez l'éditeur XML.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis cliquez sur Recharger le projet.
Importation des cibles de la transformation de texte
Les tâches de génération de la transformation de texte sont définies dans un fichier unique. Vous devez l'importer après les cibles C# ou Visual Basic standard.
Pour importer les cibles de la transformation de texte
Recherchez dans le fichier une ligne semblable à l'une des suivantes :
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
- ou -
<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
Après cette ligne, insérez l'importation de modèles de texte :
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
Définition de propriétés permettant de contrôler le mode d'exécution de la génération
Insérez le texte suivant dans le fichier projet. Consultez les sections suivantes pour connaître d'autres propriétés pouvant être insérées dans ce groupe de propriétés.
<PropertyGroup>
<TransformOnBuild>true</TransformOnBuild>
<!-- Other properties can be inserted here -->
</PropertyGroup>
TransformOnBuild entraîne l'exécution de tous les modèles du projet lorsque vous générez ce dernier.
Appel d'une transformation
Transformation de tous les modèles d'une build de projet
Si vous incluez la propriété suivante dans le fichier projet, tous les modèles de texte du projet seront exécutés chaque fois que le projet est généré, selon la fonctionnalité de build incrémentielle.
<TransformOnBuild>true</TransformOnBuild>
Vous pouvez appeler des transformations en appuyant sur F5 dans Visual Studio ou en utilisant MSBuild. Par exemple :
msbuild myproject.csproj
Si vous omettez TransformOnBuild ou lui avez affecté la valeur false, les modèles ne seront pas transformés de façon automatique dans le cadre de la build de projet.
Ajout de chemins d'accès des références
Vous pouvez ajouter des éléments à l'ensemble de chemins d'accès dans lesquels l'hôte recherche les assemblys référencés dans les modèles. Par exemple :
<ItemGroup>
<!-- Add VS\...\PublicAssemblies to the list of places
to look for assemblies used by templates. -->
<T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
</ItemGroup>
Transformation de modèles spécifiques
Vous pouvez transformer des fichiers spécifiques en appelant la tâche Transform avec l'utilitaire msbuild. Cette tâche ne dépend pas de la propriété TransformOnBuild et ne compile pas les fichiers projet. Vous devez importer le fichier de cibles de modèles de texte comme indiqué dans une section précédente.
Par exemple, pour transformer un fichier spécifique :
msbuild myproj.proj /t:Transform /p:TransformFile=MyTemplate.tt
Vous pouvez également utiliser des caractères génériques dans le paramètre TransformFile. Par exemple, la commande suivante transforme tous les fichiers .tt se trouvant dans le dossier GeneratedCode :
msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"
Génération incrémentielle
Par défaut, le gestionnaire de génération évite d'exécuter un modèle si son fichier de sortie est à jour. Pour ce faire, il contrôle le système de fichiers pour identifier les fichiers qui sont lus par le code du modèle. À d'autres occasions, il compare les dates de modification de ces fichiers avec la date du fichier de sortie. Il exécute le modèle si un fichier d'entrée a été modifié plus récemment que le fichier de sortie. Le modèle est également exécuté s'il n'existe aucune information concernant les exécutions précédentes de ce modèle.
Il en résulte que le fichier de sortie sera régénéré s'il est plus ancien qu'un des fichiers suivants :
Fichier modèle de texte
Fichiers spécifiés dans les directives <#@include#>
Fichiers lus par le code du modèle
Fichiers qui sont inclus ou lus par un processeur de directive utilisé dans le modèle
Si vous souhaitez vous assurer que tous les modèles sont exécutés dans chaque build, insérez la propriété suivante :
<TransformOutOfDateOnly>false</TransformOutOfDateOnly>
Contrôle de code source
Il n'existe aucune intégration prédéfinie spécifique avec un système de contrôle de code source. Toutefois, vous pouvez ajouter vos propres extensions (par exemple, pour extraire et archiver un fichier généré).
Par défaut, la tâche de transformation de texte évite de remplacer un fichier marqué comme étant en lecture seule ; lorsqu'un tel fichier est détecté, une erreur est consignée dans la liste d'erreurs Visual Studio et la tâche échoue.
Pour spécifier que les fichiers en lecture seule doivent être remplacés, insérez la propriété suivante :
<OverwriteReadOnlyOuputFiles>true</OverwriteReadOnlyOuputFiles>
À moins que vous ne personnalisiez l'étape de post-traitement, un avertissement sera consigné dans la liste d'erreurs lorsqu'un fichier est remplacé.
Personnalisation du processus de génération
Vous pouvez personnaliser le processus de génération (par exemple, pour extraire les fichiers qui ont été remplacés). Deux points de personnalisation, appelés avant et après la transformation, sont fournis.
Pour définir ces points, spécifiez les propriétés $(BeforeTransform) et $(AfterTransform).
Par exemple :
<PropertyGroup>
<BeforeTransform>CustomPreTransform</BeforeTransform>
<AfterTransform>CustomPostTransform;$(AfterTransform)</AfterTransform>
</PropertyGroup>
<Target Name="CustomPreTransform">
<Message Text="In CustomPreTransform..." Importance="High" />
</Target>
<Target Name="CustomPostTransform">
<Message Text="In CustomPostTransform..." Importance="High" />
</Target>
Dans AfterTransform, vous pouvez référencer les listes suivantes :
GeneratedFiles : liste des fichiers écrits par le processus. Pour les fichiers qui ont remplacé des fichiers en lecture seule existants, %(GeneratedFiles.ReadOnlyFileOverwritten) a la valeur true. Ces fichiers peuvent être extraits du contrôle de code source.
NonGeneratedFiles : liste des fichiers en lecture seule qui n'ont pas été remplacés.
À l'aide de ces listes, vous pouvez, par exemple, extraire des fichiers remplacés.
Transformation de texte sur un serveur de builds
Si votre serveur de builds s'exécute sur un ordinateur sur lequel Visual Studio n'est pas installé, vous devez copier les fichiers suivants sur l'ordinateur de build à partir d'un ordinateur sur lequel Kit de développement logiciel (SDK) Visual Studio est installé :
\Program Files\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Common\Assemblies\v4.0\
Microsoft.VisualStudio.TextTemplating.10.0.dll
Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
Microsoft.VisualStudio.TextTemplating.VSHost.10.0.dll
\Program Files\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0\
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll
\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies\
- Microsoft.VisualStudio.TextTemplating.Modeling.10.0.dll
Pour plus d'informations, consultez Créer et utiliser un contrôleur de build.