Vyvolání transformace textu v procesu sestavení

Článek
08/25/2023

Transformace textu se dá 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í, když sestavíte řešení z příkazového řádku nebo když zahájíte sestavení 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 při vytváření textové šablony pomocí nástroje MSBuild nemůžete přistupovat k věcem, jako jsou názvy souborů projektu. Pomocí parametrů sestavení ale můžete předávat informace o prostředí do textových šablon a procesorů direktiv.

Konfigurace počítačů

Pokud chcete povolit úlohy sestavení na vývojovém počítači, nainstalujte sadu Modeling SDK pro Visual Studio.

Poznámka:

Komponenta Transformace textové šablony se automaticky nainstaluje jako součást sady funkcí vývoje rozšíření sady Visual Studio. Můžete ho také nainstalovat z karty Jednotlivé komponenty Instalační program pro Visual Studio v kategorii sad SDK, knihoven a architektur. Nainstalujte komponentu Modeling SDK z karty Jednotlivé komponenty .

Pokud váš buildový server běží na počítači, na kterém není nainstalovaná sada Visual Studio, zkopírujte z vývojového počítače následující soubory do počítače sestavení:

%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

Tip

Pokud při spouštění cílů sestavení TextTemplating na buildovém serveru získáte MissingMethodException metodu Microsoft.CodeAnalysis, ujistěte se, že sestavení Roslyn jsou v adresáři s názvem Roslyn , který je ve stejném adresáři jako spustitelný soubor sestavení (například msbuild.exe).

Úprava souboru projektu

Upravte soubor projektu tak, aby nakonfigurovali některé funkce nástroje MSBuild, například import cílů transformace textu.

V Průzkumník řešení zvolte V nabídce projektu po kliknutí pravým tlačítkem myši možnost Uvolnit. Tím umožníte úpravu souborů .csproj nebo .vbproj v editoru XML. Po dokončení úprav zvolte Znovu načíst.

Import cílů transformace textu

V souboru .vbproj nebo .csproj vyhledejte poslední Import Project řádek.

Pokud tento řádek existuje, vložte import šablon textu:

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

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v16.0\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řepsat soubory, které jsou jen pro čtení, například proto, že nejsou rezervované:

<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 MSBuild vygeneruje výstupní soubor, pokud je starší než:
- soubor šablony
- všechny zahrnuté soubory
- všechny soubory, které byly dříve přečtené šablonou nebo procesorem direktiv, který používá
Jedná se o výkonnější test závislostí, než používá příkaz Transformovat všechny šablony v sadě Visual Studio, který porovnává pouze data š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"

Zdrojový ovládací prvek

Systém správy zdrojového kódu není nijak integrován. Můžete ale přidat vlastní rozšíření, například rezervovat a vrátit se změnami vygenerovaný soubor. Úloha transformace textu ve výchozím nastavení zabraňuje přepsání souboru, který je označený jako jen pro čtení. Při výskytu takového souboru se do seznamu chyb sady Visual Studio zaprotokoluje chyba a úloha selže.

Pokud chcete určit, že se soubory určené jen pro čtení mají přepisovat, vložte tuto vlastnost:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Pokud krok postprocessingu nepřizpůsobí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í. Úlohy, které jsou vyvolány před a po transformaci, můžete definovat nastavením vlastností $(BeforeTransform) a $(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>

V AfterTransformaplikaci můžete odkazovat na seznamy souborů:

GeneratedFiles – seznam souborů zapsaných procesem. U souborů, které přepíší existující soubory jen pro čtení, %(GeneratedFiles.ReadOnlyFileOverwritten) budou platit. 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 pro přesměrování je $(IntermediateOutputPath).

Pokud zadáte výstupní název souboru, bude mít přednost před rozšířením zadaným ve výstupní direktivě v šablonách.

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

Zadání OutputFileName nebo OutputFilePath se nedoporučuje, pokud také transformujete šablony v sadě Visual Studio pomocí funkce Transform All nebo spuštěním generátoru souborů. V závislosti na tom, jak jste aktivovali transformaci, skončíte s různými cestami k souborům. To může být matoucí.

Přidání odkazu a cest zahrnutí

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 direktivu šablony. K získání hodnot použijte direktivu parametru:

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

V procesoru direktiv můžete volat ITextTemplatingEngineHost.ResolveParameterValue:

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

Dim value = Host.ResolveParameterValue("-", "-", "parameterName")

Poznámka:

ResolveParameterValue získává data pouze při T4ParameterValues použití nástroje MSBuild. Při transformaci šablony pomocí sady Visual Studio mají parametry výchozí hodnoty.

Použití vlastností projektu v direktivách sestavení a zahrnutí

Makra sady Visual Studio, jako je $(SolutionDir), nefungují v nástroji MSBuild. Místo toho můžete použít vlastnosti projektu.

Upravte soubor .csproj nebo .vbproj a 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.

Otázky a odpovědi

Proč chci transformovat šablony na buildovém serveru? Před vrácením kódu se změnami jsem už transformoval šablony v sadě Visual Studio.

Pokud aktualizujete zahrnutý soubor nebo jiný soubor přečtený šablonou, Visual Studio soubor automaticky transformuje. Transformace šablon v rámci sestavení zajišťuje, že všechno je aktuální.

Jaké jsou další možnosti transformace textových šablon?

Nástroj TextTransform lze použít ve skriptech příkazů. Ve většině případů je jednodušší používat nástroj MSBuild.
Vyvolání transformace textu v rozšíření sady Visual Studio
Textové šablony v době návrhu jsou transformovány sadou Visual Studio.
Textové šablony za běhu se v aplikaci transformují za běhu.

V šabloně T4 MSbuild najdete dobré pokyny na adrese %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets

V šabloně T4 MSbuild najdete dobré pokyny na adrese %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\msbuild\Microsoft\VisualStudio\v16.0\TextTemplating\Microsoft.TextTemplating.targets

Napsání textové šablony T4

Sdílet prostřednictvím

Vyvolání transformace textu v procesu sestavení

Konfigurace počítačů

Úprava souboru projektu

Import cílů transformace textu

Transformace šablon v sestavení

Zdrojový ovládací prvek

Přizpůsobení procesu sestavení

OutputFilePath a OutputFileName

Přidání odkazu a cest zahrnutí

Předání kontextových dat sestavení do šablon

Použití vlastností projektu v direktivách sestavení a zahrnutí

Otázky a odpovědi

Váš názor

Další materiály

Sdílet prostřednictvím

Vyvolání transformace textu v procesu sestavení

Konfigurace počítačů

Úprava souboru projektu

Import cílů transformace textu

Transformace šablon v sestavení

Zdrojový ovládací prvek

Přizpůsobení procesu sestavení

OutputFilePath a OutputFileName

Přidání odkazu a cest zahrnutí

Předání kontextových dat sestavení do šablon

Použití vlastností projektu v direktivách sestavení a zahrnutí

Otázky a odpovědi

Související obsah

Váš názor

Další materiály