Partager via

Appeler la transformation de texte dans le processus de build

La transformation de texte peut être appelée dans le cadre du processus de génération d’une solution Visual Studio. Il existe des tâches de génération conçues pour la transformation de texte. Les tâches de génération T4 exécutent des modèles de texte au moment du design et compilent également des modèles de texte au moment de l’exécution (prétraités).

Il existe des différences dans ce que peuvent faire les tâches de build, en fonction du moteur de build que vous utilisez. Lorsque vous générez la solution dans Visual Studio, un modèle de texte peut accéder à l’API Visual Studio (EnvDTE) si l’attribut hostspecific="true » est défini. Toutefois, cela n’est pas vrai lorsque vous générez la solution à partir de la ligne de commande ou lorsque vous lancez une build de serveur via Visual Studio. Dans ce cas, la build est effectuée par MSBuild et un autre hôte T4 est utilisé. Cela signifie que vous ne pouvez pas accéder aux éléments tels que les noms de fichiers projet de la même façon lorsque vous générez un modèle de texte à l’aide de MSBuild. Toutefois, vous pouvez transmettre des informations d’environnement dans des modèles de texte et des processeurs de directive à l’aide de paramètres de build.

Configurer vos machines

Pour activer les tâches de génération sur votre ordinateur de développement, installez le Kit de développement logiciel (SDK) de modélisation pour Visual Studio.

Note

Le Composant de Transformation de modèle de texte est automatiquement installé dans le cadre de la charge de travail de développement d’extensions pour Visual Studio. Vous pouvez également l’installer à partir de l’onglet Composants individuels de Visual Studio Installer, sous la catégorie SDK, bibliothèques et frameworks. Installez le composant sdk de modélisation à partir de l’onglet Composants individuels .

Si votre serveur de build s’exécute sur un ordinateur sur lequel Visual Studio n’est pas installé, copiez les fichiers suivants sur l’ordinateur de build à partir de votre ordinateur de développement :

  • %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating

    • Microsoft.VisualStudio.TextTemplating.Sdk.Host.15.0.dll
    • Microsoft.TextTemplating.Build.Tasks.dll
    • Microsoft.TextTemplating.targets

  • %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblyes\v4.0

    • Microsoft.VisualStudio.TextTemplating.15.0.dll
    • Microsoft.VisualStudio.TextTemplating.Interfaces.15.0.dll
    • Microsoft.VisualStudio.TextTemplating.VSHost.15.0.dll

  • %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies

    • Microsoft.VisualStudio.TextTemplating.Modeling.15.0.dll

Conseil / Astuce

Si vous obtenez un MissingMethodException pour une méthode Microsoft.CodeAnalysis lors de l’exécution de cibles de build TextTemplating sur un serveur de build, vérifiez que les assemblies Roslyn se trouvent dans un répertoire nommé Roslyn, dans le même répertoire que l’exécutable de build (par exemple, msbuild.exe).

Modifier le fichier projet

Modifiez votre fichier projet pour configurer certaines des fonctionnalités de MSBuild, par exemple en important les cibles de transformation de texte.

Dans l’Explorateur de solutions, choisissez Décharger dans le menu contextuel de votre projet. Cela vous permet de modifier le fichier .csproj ou .vbproj dans l’éditeur XML. Une fois la modification terminée, choisissez Recharger.

Importer les cibles de transformation de texte

Dans le fichier .vbproj ou .csproj, recherchez la dernière Import Project ligne.

Après cette ligne, s’il existe, insérez l’importation de création de modèles de texte :

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />

Transformer des modèles dans une build

Il existe certaines propriétés que vous pouvez insérer dans votre fichier projet pour contrôler la tâche de transformation :

  • Exécutez la tâche Transform au début de chaque build :

    <PropertyGroup>
    <TransformOnBuild>true</TransformOnBuild>
</PropertyGroup>

  • Remplacez les fichiers en lecture seule, par exemple, car ils ne sont pas extraits :

    <PropertyGroup>
    <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
</PropertyGroup>

  • Transformez chaque modèle chaque fois :

    <PropertyGroup>
    <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
</PropertyGroup>

    Par défaut, la tâche T4 MSBuild régénère un fichier de sortie s’il est antérieur à :

    • son fichier de modèle
    • tous les fichiers inclus
    • tous les fichiers qui ont déjà été lus par le modèle ou par un processeur de directive qu’il utilise

    Il s’agit d’un test de dépendance plus puissant que celui utilisé par la commande Transform All Templates dans Visual Studio, qui compare uniquement les dates du modèle et du fichier de sortie.

Pour effectuer uniquement les transformations de texte dans votre projet, appelez la tâche TransformAll :

msbuild myProject.csproj /t:TransformAll

Pour transformer un modèle de texte spécifique :

msbuild myProject.csproj /t:Transform /p:TransformFile="Template1.tt"

Vous pouvez utiliser des caractères génériques dans TransformFile :

msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"

Gestion des sources

Il n’existe aucune intégration intégrée spécifique à 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é en lecture seule. Lorsqu’un tel fichier est rencontré, une erreur est enregistré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 cette propriété :

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Sauf si vous personnalisez l’étape de post-traitement, un avertissement est consigné dans la liste d’erreurs lorsqu’un fichier est remplacé.

Personnaliser le processus de génération

La transformation de texte se produit avant d’autres tâches dans le processus de génération. Vous pouvez définir des tâches appelées avant et après la transformation, en définissant les propriétés $(BeforeTransform) et $(AfterTransform):

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform</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 des listes de fichiers :

  • GeneratedFiles : liste de fichiers écrits par le processus. Pour ces fichiers qui remplacent les fichiers en lecture seule existants, %(GeneratedFiles.ReadOnlyFileOverwritten) seront vrais. Ces fichiers peuvent être extraits du contrôle de code source.

  • NonGeneratedFiles : liste de fichiers en lecture seule qui n’ont pas été remplacés.

Par exemple, vous définissez une tâche pour vérifier les FichiersGénérés.

OutputFilePath et OutputFileName

Ces propriétés sont utilisées uniquement par MSBuild. Ils n’affectent pas la génération de code dans Visual Studio. Ils redirigent le fichier de sortie généré vers un autre dossier ou fichier. Le dossier cible doit déjà exister.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFilePath>MyFolder</OutputFilePath>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Un dossier utile à rediriger vers est $(IntermediateOutputPath).

Si vous spécifiez un nom de fichier de sortie, il est prioritaire sur l’extension spécifiée dans la directive de sortie dans les modèles.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFileName>MyOutputFileName.cs</OutputFileName>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

La spécification d’un OutputFileName ou outputFilePath n’est pas recommandée si vous transformez également des modèles à l’intérieur de Visual Studio à l’aide de Transform All ou exécutez le générateur de fichiers unique. Vous obtiendrez des chemins d’accès de fichiers différents en fonction de la façon dont vous avez déclenché la transformation. Cela peut être déroutant.

Ajouter des références et inclure des chemins d’accès

L’hôte a un ensemble par défaut de chemins d’accès où il recherche des assemblys référencés dans des modèles. Pour ajouter à cet ensemble :

<ItemGroup>
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
    <!-- Add more T4ReferencePath items here -->
</ItemGroup>

Pour définir les dossiers qui seront recherchés pour inclure des fichiers, fournissez une liste séparée par des points-virgules. En règle générale, vous ajoutez à la liste de dossiers existante.

<PropertyGroup>
    <IncludeFolders>
$(IncludeFolders);$(MSBuildProjectDirectory)\Include;AnotherFolder;And\Another</IncludeFolders>
</PropertyGroup>

Transmettre des données de contexte de génération dans les modèles

Vous pouvez définir des valeurs de paramètre dans le fichier projet. Par exemple, vous pouvez passer des propriétés de build et des variables d’environnement :

<ItemGroup>
  <T4ParameterValues Include="ProjectFolder">
    <Value>$(ProjectDir)</Value>
    <Visible>false</Visible>
  </T4ParameterValues>
</ItemGroup>

Dans un modèle de texte, définissez hostspecific dans la directive de modèle. Utilisez la directive de paramètre pour obtenir des valeurs :

<#@template language="c#" hostspecific="true"#>
<#@ parameter type="System.String" name="ProjectFolder" #>
The project folder is: <#= ProjectFolder #>

Dans un processeur de directive, vous pouvez appeler ITextTemplatingEngineHost.ResolveParameterValue :

string value = Host.ResolveParameterValue("-", "-", "parameterName");

Note

ResolveParameterValue obtient des données de T4ParameterValues uniquement lorsque vous utilisez MSBuild. Lorsque vous transformez le modèle à l’aide de Visual Studio, les paramètres ont des valeurs par défaut.

Utiliser des propriétés de projet dans l’assembly et inclure des directives

Les macros Visual Studio telles que $(SolutionDir) ne fonctionnent pas dans MSBuild. Vous pouvez utiliser les propriétés du projet à la place.

Modifiez votre fichier .csproj ou .vbproj pour définir une propriété de projet. Cet exemple définit une propriété nommée myLibFolder :

<!-- Define a project property, myLibFolder: -->
<PropertyGroup>
    <myLibFolder>$(MSBuildProjectDirectory)\..\libs</myLibFolder>
</PropertyGroup>

<!-- Tell the MSBuild T4 task to make the property available: -->
<ItemGroup>
    <T4ParameterValues Include="myLibFolder">
      <Value>$(myLibFolder)</Value>
    </T4ParameterValues>
  </ItemGroup>

Vous pouvez maintenant utiliser votre propriété de projet dans l’assembly et inclure des directives :

<#@ assembly name="$(myLibFolder)\MyLib.dll" #>
<#@ include file="$(myLibFolder)\MyIncludeFile.t4" #>

Ces directives obtiennent des valeurs de T4parameterValues à la fois dans MSBuild et dans les hôtes Visual Studio.

Questions et réponses

Pourquoi voudrais-je transformer des modèles dans le serveur de build ? J’ai déjà transformé des modèles dans Visual Studio avant d’avoir archivé mon code.

Si vous mettez à jour un fichier inclus ou un autre fichier lu par le modèle, Visual Studio ne transforme pas automatiquement le fichier. La transformation de modèles dans le cadre de la build garantit que tout est à jour.

Quelles sont les autres options disponibles pour transformer des modèles de texte ?

Contenu connexe

  • Il existe de bons conseils dans le modèle T4 MSbuild à l’adresse %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Last updated on