Vytvoření kódu v procesu sestavení
Transformaci textu lze vyvolat jako součást procesu sestavení řešení sady Visual Studio.Některé úlohy sestavení se specializují na transformaci textu.Úlohy sestavení T4 spouštějí textové šablony návrhu a rovněž kompilují textové šablony běhu (předzpracované).
V závislosti na tom, který stroj sestavení používáte, jsou určité rozdíly v tom, co úlohy sestavení mohou provádět.Při sestavování řešení v sadě Visual Studio má textová šablona přístup k rozhraní API sady Visual Studio (EnvDTE), pokud je nastaven atribut hostspecific="true".To ale neplatí při sestavování řešení z příkazového řádku nebo při inicializaci sestavení na serveru prostřednictvím sady Visual Studio.V těchto případech provádí sestavení nástroj MSBuild a používá se jiný hostitel T4.
To znamená, že k různým položkám (například k názvům projektů) nelze získat přístup stejně jako při sestavování textové šablony v nástroji MSBuild.Nicméně k předání informací o prostředí do textových šablon a procesorů direktiv lze použít parametry sestavení.
Konfigurace počítačů
Chcete-li povolit sestavení úlohy ve svém vývojovém počítači, nainstalujte modelování sady SDK pro sadu Visual Studio.
Pokud serveru sestavení běží na počítači, ve kterém Visual Studio nejsou nainstalovány, zkopírujte následující soubory do počítače sestavení z vývojářského počítače.Nahraďte hodnotu čísla nejnovější verzí pro "*".
$(ProgramFiles)\MSBuild\Microsoft\VisualStudio\v*.0\TextTemplating
Microsoft.VisualStudio.TextTemplating.Sdk.Host.*.0.dll
Microsoft.TextTemplating.Build.Tasks.dll
Microsoft.TextTemplating.targets
*.0\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0 sady Visual Studio \Microsoft $(ProgramFiles)
Microsoft.VisualStudio.TextTemplating.*.0.dll
Microsoft.VisualStudio.TextTemplating.Interfaces.*.0.dll (několik souborů)
Microsoft.VisualStudio.TextTemplating.VSHost.*.0.dll
*.0\Common7\IDE\PublicAssemblies\ sady Visual Studio \Microsoft $(ProgramFiles)
- Microsoft.VisualStudio.TextTemplating.Modeling.*.0.dll
Úprava souboru projektu
Některé funkce nástroje MSBuild budete muset nakonfigurovat úpravou souboru projektu.
V Průzkumníku řešení zvolte v kontextové nabídce projektu příkaz Uvolnit.Tím umožníte úpravu souborů .csproj nebo .vbproj v editoru XML.
Po dokončení úprav klikněte na příkaz Načíst znovu.
Import cílů transformace textu
V souboru .vbproj nebo .csproj vyhledejte řádek podobný následujícímu:
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
-nebo-
<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
Za tento řádek vložte import šablonování textu:
<!-- Optionally make the import portable across VS versions -->
<PropertyGroup>
<!-- Get the Visual Studio version – defaults to 10: -->
<VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">10.0</VisualStudioVersion>
<!-- Keep the next element all on one line: -->
<VSToolsPath Condition="'$(VSToolsPath)' == ''">$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)</VSToolsPath>
</PropertyGroup>
<!-- This is the important line: -->
<Import Project="$(VSToolsPath)\TextTemplating\Microsoft.TextTemplating.targets" />
Transformace šablon v sestavení
Do souboru projektu lze vložit některé vlastnosti, které slouží k řízení úlohy transformace:
Spuštění úlohy transformace na začátku každého sestavení:
<PropertyGroup> <TransformOnBuild>true</TransformOnBuild> </PropertyGroup>Přepsání souborů, které jsou určeny jen pro čtení, protože například nejsou rezervovány:
<PropertyGroup> <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles> </PropertyGroup>Transformace všech šablon při každém spuštění:
<PropertyGroup> <TransformOutOfDateOnly>false</TransformOutOfDateOnly> </PropertyGroup>Ve výchozím nastavení úloha T4 nástroje MSBuild znovu vygeneruje výstupní soubor, pokud je starší než její soubory šablony, nebo všechny vložené soubory, nebo všechny soubory, které byly předtím čteny šablonou nebo procesorem direktiv, který používá.Jedná se o mnohem komplexnější test závislostí, než jaký používá příkaz Transformovat všechny šablony v sadě Visual Studio, který pouze porovnává datum šablony a výstupního souboru.
Pokud chcete v projektu provést pouze transformace textu, vyvolejte úlohu TransformAll:
msbuild myProject.csproj /t:TransformAll
Transformace konkrétní textové šablony:
msbuild myProject.csproj /t:Transform /p:TransformFile="Template1.tt"
U příkazu TransformFile lze použít zástupné znaky:
msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"
Správa zdrojového kódu
Systém správy zdrojového kódu není nijak integrován.Můžete však přidat vlastní rozšíření, například pro rezervaci a vrácení vygenerovaného souboru. Úloha transformace textu ve výchozím nastavení zabraňuje přepsání souboru, který je určený jen pro čtení, a když na takový soubor narazí, bude do seznamu chyb sady Visual Studio zaprotokolována chyba a tato úloha selže.
Pokud chcete určit, že se soubory určené jen pro čtení mají přepisovat, vložte tuto vlastnost:
<OverwriteReadOnlyOuputFiles>true</OverwriteReadOnlyOuputFiles>
Dokud tento krok následného zpracování neupravíte, při přepsání souboru se do seznamu chyb zaprotokoluje upozornění.
Přizpůsobení procesu sestavení
Transformace textu se provede před všemi ostatními úlohami v procesu sestavení.Nastavením vlastností $(BeforeTransform) a $(AfterTransform) lze definovat úlohy, které jsou vyvolány před a po transformaci:
<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>
Ve vlastnosti AfterTransform lze odkazovat na seznamy souborů:
GeneratedFiles – seznam souborů zapsaných procesem.U souborů, které přepsaly existující soubory určené jen pro čtení, bude mít %(GeneratedFiles.ReadOnlyFileOverwritten) hodnotu true.Tyto soubory lze rezervovat ze správy zdrojového kódu.
NonGeneratedFiles – seznam souborů určených jen pro čtení, které nebyly přepsány.
Lze například definovat úlohu, která rezervuje GeneratedFiles.
OutputFilePath a OutputFileName
Tyto vlastnosti používá pouze nástroj MSBuild.Neovlivňují generování kódu v sadě Visual Studio.Slouží k přesměrování vygenerovaného výstupního souboru do jiné složky nebo souboru.Cílová složka již musí existovat.
<ItemGroup>
<None Include="MyTemplate.tt">
<Generator>TextTemplatingFileGenerator</Generator>
<OutputFilePath>MyFolder</OutputFilePath>
<LastGenOutput>MyTemplate.cs</LastGenOutput>
</None>
</ItemGroup>
Užitečnou složkou k přesměrování je $(IntermediateOutputPath).
Zadáte-li název výstupního souboru, bude mít přednost před příponou zadanou v direktivě output v šablonách.
<ItemGroup>
<None Include="MyTemplate.tt">
<Generator>TextTemplatingFileGenerator</Generator>
<OutputFileName>MyOutputFileName.cs</OutputFileName>
<LastGenOutput>MyTemplate.cs</LastGenOutput>
</None>
</ItemGroup>
Nastavení OutputFileName nebo OutputFilePath není doporučeno, pokud rovněž transformujete šablony v sadě VS pomocí příkazu Transformovat vše nebo spuštěním generátoru jednotlivých souborů.Skončíte s odlišnými cestami souborů v závislosti na tom, jak jste transformaci spustili.To může být velmi matoucí.
Přidání odkazu a cest k vkládaným souborům
Hostitel má nastavenu výchozí sadu cest, kde hledá sestavení odkazovaná v šablonách.Tuto sadu přidáte takto:
<ItemGroup>
<T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
<!-- Add more T4ReferencePath items here -->
</ItemGroup>
Chcete-li nastavit složky, ve kterých se budou hledat vkládané soubory, zadejte seznam s prvky oddělenými středníkem.Obvykle složku přidáte do existujícího seznamu složek.
<PropertyGroup>
<IncludeFolders>
$(IncludeFolders);$(MSBuildProjectDirectory)\Include;AnotherFolder;And\Another</IncludeFolders>
</PropertyGroup>
Předání kontextových dat sestavení do šablon
Hodnoty parametru lze nastavit v souboru projektu.Můžete například předat vlastnosti sestavení a proměnné prostředí:
<ItemGroup>
<T4ParameterValues Include="ProjectFolder">
<Value>$(ProjectDir)</Value>
<Visible>false</Visible>
</T4ParameterValues>
</ItemGroup>
V textové šabloně nastavte hostspecific v direktivě šablony.K získání hodnot použijte direktivu parameter:
<#@template language="c#" hostspecific="true"#>
<#@ parameter type="System.String" name="ProjectFolder" #>
The project folder is: <#= ProjectFolder #>
V procesoru direktiv lze zavolat ResolveParameterValue:
string value = Host.ResolveParameterValue("-", "-", "parameterName");
Dim value = Host.ResolveParameterValue("-", "-", "parameterName")
[!POZNÁMKA]
ResolveParameterValue získá data z T4ParameterValues pouze při použití nástroje MSBuild.Při transformaci šablony pomocí sady Visual Studio budou mít parametry výchozí hodnoty.
Použití vlastností projektu v direktivách assembly a include
Makra sady Visual Studio, například $(SolutionDir), nefungují v nástroji MSBuild.Místo toho můžete použít vlastnosti projektu.
Úpravou souboru .csproj nebo .vbproj definujte vlastnost projektu.Tento příklad definuje vlastnost s názvem 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>
Nyní můžete vlastnost projektu použít v direktivách assembly a include:
<#@ assembly name="$(myLibFolder)\MyLib.dll" #>
<#@ include file="$(myLibFolder)\MyIncludeFile.t4" #>
Tyto direktivy získají z T4parameterValues hodnoty v hostitelích MSBuild i Visual Studio.
Dotazy a odpovědi
Proč mám chtít, aby se šablony transformovaly na sestavovacím serveru? Před vrácením kódu se šablony již transformovaly v sadě Visual Studio.
Při aktualizaci vkládaného souboru nebo jiného souboru čteného šablonou netransformuje Visual Studio tento soubor automaticky.Transformace šablon během sestavení zajišťuje, že je vše v aktuálním stavu.
Jaké jsou další možnosti transformace textových šablon?
V příkazových skriptech lze použít nástroj TextTransform.Ve většině případů je jednodušší použít nástroj MSBuild.
Textové šablony návrhu jsou transformovány sadou Visual Studio.
Textové šablony běhu jsou transformovány při běhu aplikace.
Další informace
Dobrý návod poskytuje šablona T4 nástroje MSbuild, $(VSToolsPath)\TextTemplating\Microsoft.TextTemplating.targets.