Richiamare la trasformazione testo nel processo di compilazione

La trasformazione del testo può essere richiamata come parte del processo di compilazione di una soluzione di Visual Studio. Esistono attività di compilazione che sono specializzate nella trasformazione del testo. Le attività di compilazione di T4 eseguono modelli di testo della fase di progettazione e compilano anche modelli di testo (pre-elaborati) della fase di esecuzione.

Esistono alcune differenze in ciò che le attività di compilazione possono fare, a seconda del motore di compilazione utilizzato. Quando si compila la soluzione in Visual Studio, un modello di testo può accedere all'API di Visual Studio (EnvDTE) se è impostato l'attributo hostspecific="true". Ma questo non è vero quando si compila la soluzione dalla riga di comando o quando si avvia una compilazione del server tramite Visual Studio. In questi casi, la compilazione viene eseguita da MSBuild e viene utilizzato un diverso host T4. Ciò significa che non è possibile accedere ad elementi come i nomi di file di progetto nello stesso modo in cui si compila un modello di testo usando MSBuild. Tuttavia, è possibile passare informazioni sull'ambiente in modelli di testo e processori di direttiva usando i parametri di compilazione.

Configurare i computer

Per abilitare le attività di compilazione nel computer di sviluppo, installare Modeling SDK per Visual Studio.

Nota

Il componente Trasformazione modello di testo viene installato automaticamente come parte del carico di lavoro sviluppo di estensioni di Visual Studio. È anche possibile installarlo dalla scheda Singoli componenti di Programma di installazione di Visual Studio, nella categoria SDK, librerie e framework. Installare il componente Modeling SDK dalla scheda Singoli componenti .

Se il server di compilazione viene eseguito in un computer in cui Non è installato Visual Studio, copiare i file seguenti nel computer di compilazione dal computer di sviluppo:

• %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\Assemblies\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

Suggerimento

Se si ottiene un MissingMethodException oggetto per un metodo Microsoft.CodeAnalysis durante l'esecuzione di destinazioni di compilazione TextTemplating in un server di compilazione, assicurarsi che gli assembly Roslyn si trovino in una directory denominata Roslyn che si trova nella stessa directory dell'eseguibile di compilazione , ad esempio msbuild.exe.

Modificare il file di progetto

Modificare il file di progetto per configurare alcune delle funzionalità in MSBuild, ad esempio importando le destinazioni di trasformazione del testo.

In Esplora soluzioni scegliere Scarica dal menu di scelta rapida del progetto. Ciò consente di modificare il file con estensione csproj o vbproj nell'editor XML. Al termine della modifica, scegliere Ricarica.

Importare le destinazioni di trasformazione del testo

Nel file con estensione vbproj o csproj trovare l'ultima Import Project riga.

Dopo tale riga, se esistente, inserire l'importazione di Modelli di testo:

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

Trasformare i modelli in una compilazione

Esistono alcune proprietà che è possibile inserire all'interno del file di progetto per controllare le attività di trasformazione:

• Eseguire l'attività di trasformazione all'inizio di ogni compilazione:

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

• Sovrascrivere i file di sola lettura, ad esempio perché non vengono estratti:

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

• Trasforma ogni modello ogni volta:

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

  Per impostazione predefinita, l'attività MSBuild T4 rigenera un file di output se è precedente a:

  • file di modello
  • tutti i file inclusi
  • tutti i file che sono stati letti in precedenza dal modello o da un processore di direttiva che utilizza

  Si tratta di un test di dipendenza più potente di quello usato dal comando Trasforma tutti i modelli in Visual Studio, che confronta solo le date del modello e del file di output.

Per eseguire solo le trasformazioni di testo nel progetto, richiamare l'attività TransformAll:

msbuild myProject.csproj /t:TransformAll

Per trasformare un modello di testo specifico:

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

È possibile usare i caratteri jolly in TransformFile:

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

Controllo del codice sorgente

Non esiste un'integrazione incorporata specifica con un sistema di controllo del codice sorgente. Tuttavia, è possibile aggiungere estensioni personalizzate, ad esempio, per archiviare e archiviare un file generato. Per impostazione predefinita, l'attività di trasformazione del testo evita la sovrascrittura di un file contrassegnato come di sola lettura. Quando viene rilevato un file di questo tipo, viene registrato un errore nell'elenco errori di Visual Studio e l'attività non riesce.

Per specificare che i file di sola lettura devono essere sovrascritti, inserire questa proprietà:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

A meno che non si personalizza il passaggio di post-elaborazione, verrà registrato un avviso nell'elenco errori quando un file viene sovrascritto.

Personalizzare il processo di compilazione

Nel processo di compilazione, la trasformazione del testo si verifica prima delle altre attività. È possibile definire le attività che vengono chiamati prima e dopo la trasformazione, impostando le proprietà $(BeforeTransform) e $(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>

In AfterTransform, è possibile fare riferimento a elenchi di file:

• GeneratedFiles - un elenco di file scritti dal processo. Per i file che sovrascriveranno i file di sola lettura esistenti, %(GeneratedFiles.ReadOnlyFileOverwritten) sarà true. È possibile estrarre questi file dal controllo del codice sorgente.

• NonGeneratedFiles - un elenco di file di sola lettura che non sono stati sovrascritti.

Ad esempio, si definisce un'attività per estrarre GeneratedFiles.

OutputFilePath e OutputFileName

Queste proprietà sono utilizzate solo da MSBuild. Non influiscono sulla generazione di codice in Visual Studio. Effettuano il reindirizzamento del file di output generato su una cartella o un file diverso. La cartella di destinazione deve esistere.

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

Una cartella utile a cui eseguire il reindirizzamento è $(IntermediateOutputPath).

Se si specifica un nome file di output, ha la precedenza sull'estensione specificata nella direttiva di output nei modelli.

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

Non è consigliabile specificare outputFileName o OutputFilePath se si stanno trasformando anche modelli all'interno di Visual Studio usando Transform All o eseguendo il generatore di file singolo. Si otterranno percorsi di file diversi a seconda del modo in cui è stata attivata la trasformazione. Questo può generare confusione.

Aggiungere percorsi di riferimento e inclusione

L'host dispone di un set predefinito di percorsi in cui cercare gli assembly a cui si fa riferimento nei modelli. Per aggiungere a questo set:

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

Per impostare le cartelle in cui verranno cercati i file di inclusione, fornire un elenco separato da punti e virgola. In genere si aggiunge all'elenco di cartelle esistenti.

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

Passare i dati del contesto di compilazione nei modelli

È possibile impostare i valori dei parametri nel file di progetto. Ad esempio, è possibile passare le proprietà di compilazione e le variabili di ambiente:

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

In un modello di testo, impostare hostspecific nella direttiva del modello. Usare la direttiva parameter per ottenere i valori:

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

In un processore di direttiva è possibile chiamare ITextTemplatingEngineHost.ResolveParameterValue:

C#

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

VB

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

Nota

ResolveParameterValue ottiene i dati da T4ParameterValues solo quando si usa MSBuild. Quando si trasforma il modello usando Visual Studio, i parametri hanno valori predefiniti.

Usare le proprietà del progetto nell'assembly e nelle direttive di inclusione

Le macro di Visual Studio come $(SolutionDir) non funzionano in MSBuild. È possibile utilizzare le proprietà del progetto.

Modificare il file con estensione csproj o vbproj per definire una proprietà del progetto. Questo esempio definisce una proprietà denominata 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>

È possibile utilizzare la proprietà del progetto in un assembly e includere le direttive:

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

Queste direttive ottengono valori da T4parameterValues in MSBuild e negli host di Visual Studio.

Domande e risposte

Perché è consigliabile trasformare i modelli nel server di compilazione? I modelli sono già stati trasformati in Visual Studio prima di archiviare il codice.

Se si aggiorna un file incluso o un altro file letto dal modello, Visual Studio non trasforma automaticamente il file. La trasformazione dei modelli come parte della compilazione garantisce che tutto sia aggiornato.

Quali altre opzioni sono disponibili per la trasformazione dei modelli di testo?

• L'utilità TextTransform può essere usata negli script dei comandi. Nella maggior parte dei casi, è più facile usare MSBuild.

• Richiamare la trasformazione Testo in un'estensione di Visual Studio.

• I modelli di testo in fase di progettazione vengono trasformati da Visual Studio.

• I modelli di testo in fase di esecuzione vengono trasformati in fase di esecuzione nell'applicazione.

Contenuto correlato

• Sono disponibili indicazioni valide nel modello MSbuild T4 all'indirizzo %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets

• Scrivere un modello di testo T4