Derleme işleminde metin dönüştürmeyi çağırma

Makale
10/10/2023

Metin dönüştürme , Visual Studio çözümünün derleme sürecinin bir parçası olarak çağrılabilir. Metin dönüştürme için özelleştirilmiş yapı görevleri vardır. T4 yapı görevleri tasarım zamanı metin şablonlarını çalıştırır ve aynı zamanda çalışma zamanı (önişlenmiş) metin şablonlarını derler.

Kullandığınız oluşturma motoruna bağlı olarak, yapı görevleri farklı işlevleri yerine getirebilirler. Çözümü Visual Studio'da oluşturduğunuzda, hostspecific="true" özniteliği ayarlandıysa bir metin şablonu Visual Studio API'sine (EnvDTE) erişebilir. Ancak, çözümü komut satırından oluşturduğunuzda veya Visual Studio aracılığıyla bir sunucu derlemesi başlattığınızda bu doğru değildir. Bu durumlarda, yapı MSBuild tarafından oluşturulur ve farklı bir T4 ana bilgisayar kullanılır. Başka bir deyişle, MSBuild kullanarak bir metin şablonu oluştururken proje dosya adları gibi şeylere aynı şekilde erişemezsiniz. Ancak, derleme parametrelerini kullanarak ortam bilgilerini metin şablonlarına ve yönerge işlemcilerine geçirebilirsiniz.

Makinelerinizi yapılandırma

Geliştirme bilgisayarınızda derleme görevlerini etkinleştirmek için Visual Studio için Modelleme SDK'sını yükleyin.

Not

Metin Şablonu Dönüştürme bileşeni, Visual Studio uzantısı geliştirme iş yükünün bir parçası olarak otomatik olarak yüklenir. Ayrıca Visual Studio Yükleyicisi Tek tek bileşenler sekmesinden SDK'lar, kitaplıklar ve çerçeveler kategorisinin altından da yükleyebilirsiniz. Tek tek bileşenler sekmesinden Modelleme SDK'sı bileşenini yükleyin.

Derleme sunucunuz Visual Studio yüklü olmayan bir bilgisayarda çalışıyorsa, aşağıdaki dosyaları geliştirme makinenizden derleme bilgisayarına kopyalayın:

%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

İpucu

Derleme sunucusunda TextTemplating derleme hedeflerini çalıştırırken Microsoft.CodeAnalysis için bir yöntemi alırsanızMissingMethodException, Roslyn derlemelerinin derleme yürütülebilir dosyasıyla aynı dizinde (örneğin, msbuild.exe) Roslyn adlı bir dizinde olduğundan emin olun.

Proje dosyasını düzenleme

MSBuild'de metin dönüştürme hedeflerini içeri aktarma gibi bazı özellikleri yapılandırmak için proje dosyanızı düzenleyin.

Çözüm Gezgini'da projenizin sağ tıklama menüsünden Kaldır'ı seçin. Bu .csproj veya .vbproj dosyasını XML düzenleyicisinde düzenlemenize olanak tanır. Düzenlemeyi bitirdiğinizde Yeniden Yükle'yi seçin.

Metin dönüştürme hedeflerini içeri aktarma

.vbproj veya .csproj dosyasında son Import Project satırı bulun.

Bu satırdan sonra, varsa Metin Şablon oluşturma içeri aktarmasını ekleyin:

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

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

Derlemedeki şablonları dönüştürme

Dönüştürme görevini kontrol etmek için proje dosyanızın içine ekleyebileceğiniz bazı özellikler vardır:

Dönüştürme görevini her yapı başlangıcında çalıştır:

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

Örneğin, kullanıma alınmadıkları için salt okunur dosyaların üzerine yazın:

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

Her şablonu her zaman dönüştür:
```
<PropertyGroup>
    <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
</PropertyGroup>
```
Varsayılan olarak, T4 MSBuild görevi aşağıdakilerden daha eskiyse bir çıkış dosyasını yeniden oluşturur:
- şablon dosyası
- dahil edilen tüm dosyalar
- şablon veya kullandığı yönerge işlemcisi tarafından daha önce okunmuş tüm dosyalar
Bu, Visual Studio'daki Tüm Şablonları Dönüştür komutu tarafından kullanılandan daha güçlü bir bağımlılık testidir ve bu test yalnızca şablonun ve çıktı dosyasının tarihlerini karşılaştırır.

Projenizde yalnızca metin dönüştürmeleri gerçekleştirmek için TransformAll görevini çağırın:

msbuild myProject.csproj /t:TransformAll

Belirli metin şablonu dönüştürmek için:

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

TransformFile içinde joker karakterler kullanabilirsiniz:

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

Kaynak denetimi

Kaynak denetim sistemi ile yerleşik herhangi bir tümleştirme yoktur. Ancak, oluşturulan bir dosyayı kullanıma almak ve iade etmek için kendi uzantılarınızı ekleyebilirsiniz. Varsayılan olarak, metin dönüştürme görevi salt okunur olarak işaretlenmiş bir dosyanın üzerine yazılmasını önler. Böyle bir dosyayla karşılaşıldığında, Visual Studio Hata Listesi'ne bir hata kaydedilir ve görev başarısız olur.

Salt okunur dosyaların üzerine yazılması gerektiğini belirtmek için bu özelliği ekleyin:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

İşlem sonrası adımı özelleştirmediğiniz sürece, bir dosyanın üzerine yazıldığında Hata Listesi'nde bir uyarı günlüğe kaydedilir.

Derleme işlemini özelleştirme

Oluşturma işleminde diğer görevlerden önce metin dönüştürme gerçekleşir. ve özelliklerini $(BeforeTransform) $(AfterTransform)ayarlayarak dönüştürmeden önce ve sonra çağrılan görevleri tanımlayabilirsiniz:

<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>

içinde AfterTransform, dosya listelerine başvurabilirsiniz:

GeneratedFiles - işlem tarafından yazılan dosyaların listesi. Var olan salt okunur dosyaların üzerine yazan dosyalar %(GeneratedFiles.ReadOnlyFileOverwritten) için true olacaktır. Bu dosyalar kaynak denetiminden denetlenebilir.
NonGeneratedFiles - üzerine yazılmamış, salt okunur dosyaların listesi.

Örneğin, GeneratedFiles'ı kullanıma almak için bir görev tanımlarsınız.

OutputFilePath ve OutputFileName

Bu özellikler yalnızca MSBuild tarafından kullanılır. Visual Studio'da kod üretimi etkilemez. Bunlar, oluşturulan çıktı dosyasını farklı bir klasör veya dosyaya yeniden yönlendirir. Hedef klasörün zaten bulunması gerekir.

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

Yeniden yönlendirilecek kullanışlı bir klasördür $(IntermediateOutputPath).

Bir çıkış dosya adı belirtirseniz, şablonlarda çıkış yönergesinde belirtilen uzantıdan önceliklidir.

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

Visual Studio içindeki şablonları Tümünü Dönüştür'ü kullanarak veya tek bir dosya oluşturucuyu çalıştırarak da dönüştürüyorsanız OutputFileName veya OutputFilePath belirtmeniz önerilmez. Dönüşümü nasıl tetiklediğinize bağlı olarak farklı dosya yollarınız olur. Bu kafa karıştırıcı olabilir.

Başvuru ekleme ve yol ekleme

Ana bilgisayar, şablonlarda başvurulan derlemeler için arama yaptığı varsayılan bir grup yola sahiptir. Bu gruba ekleme yapmak için:

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

Ekleme kodu dosyalarının aranacağı klasörleri ayarlamak için, noktalı virgülle ayrılmış bir liste sağlayın. Genellikle varolan klasör listesine eklersiniz.

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

Derleme bağlam verilerini şablonlara geçirme

Proje dosyasında parametre değerlerini ayarlayabilirsiniz. Örneğin, derleme özelliklerini ve ortam değişkenlerini geçirebilirsiniz:

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

Metin şablonunda, şablon yönergesinde ayarlayın hostspecific . Değerleri almak için parametre yönergesini kullanın:

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

Yönerge işlemcisinde ITextTemplatingEngineHost.ResolveParameterValue çağırabilirsiniz:

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

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

Not

ResolveParameterValue yalnızca MSBuild kullandığınızda veri T4ParameterValues alır. Visual Studio kullanarak şablonu dönüştürdüğünüzde, parametreler varsayılan değerlere sahiptir.

Derleme ve ekleme yönergelerinde proje özelliklerini kullanma

$(SolutionDir) gibi Visual Studio makroları MSBuild'de çalışmaz. Bunun yerine, proje özelliklerini kullanabilirsiniz.

Proje özelliğini tanımlamak için .csproj veya .vbproj dosyanızı düzenleyin. Bu örnek myLibFolder adlı bir özelliği tanımlar:

<!-- 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>

Artık derlemede ve ekleme yönergelerinde proje özelliklerini kullanabilirsiniz:

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

Bu yönergeler, hem MSBuild içinde hem de Visual Studio ana bilgisayarlarında T4parameterValues değerlerini alır.

Sorular ve Yanıtlar

Derleme sunucusunda şablonları neden dönüştürmek isteyeyim? Kodumu iade etmeden önce Visual Studio'daki şablonları zaten dönüştürmüş durumdayım.

Eklenen bir dosyayı veya şablon tarafından okunan başka bir dosyayı güncelleştirirseniz, Visual Studio dosyayı otomatik olarak dönüştürmez. Şablonları derlemenin bir parçası olarak dönüştürmek, her şeyin güncel olmasını sağlar.

Metin şablonlarını dönüştürmek için başka hangi seçenekler vardır?

TextTransform yardımcı programı komut betiklerinde kullanılabilir. Çoğu durumda MSBuild kullanmak daha kolaydır.
Visual Studio uzantısında Metin Dönüştürmeyi çağırma.
Tasarım zamanı metin şablonları Visual Studio tarafından dönüştürülür.
Çalışma zamanı metin şablonları , uygulamanızda çalışma zamanında dönüştürülür.

T4 MSbuild şablonunda şu konumda iyi yönergeler vardır: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets

T4 MSbuild şablonunda şu konumda iyi yönergeler vardır: %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\msbuild\Microsoft\VisualStudio\v16.0\TextTemplating\Microsoft.TextTemplating.targets

T4 metin şablonu yazma

Aracılığıyla paylaş

Derleme işleminde metin dönüştürmeyi çağırma

Makinelerinizi yapılandırma

Proje dosyasını düzenleme

Metin dönüştürme hedeflerini içeri aktarma

Derlemedeki şablonları dönüştürme

Kaynak denetimi

Derleme işlemini özelleştirme

OutputFilePath ve OutputFileName

Başvuru ekleme ve yol ekleme

Derleme bağlam verilerini şablonlara geçirme

Derleme ve ekleme yönergelerinde proje özelliklerini kullanma

Sorular ve Yanıtlar

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

Derleme işleminde metin dönüştürmeyi çağırma

Makinelerinizi yapılandırma

Proje dosyasını düzenleme

Metin dönüştürme hedeflerini içeri aktarma

Derlemedeki şablonları dönüştürme

Kaynak denetimi

Derleme işlemini özelleştirme

OutputFilePath ve OutputFileName

Başvuru ekleme ve yol ekleme

Derleme bağlam verilerini şablonlara geçirme

Derleme ve ekleme yönergelerinde proje özelliklerini kullanma

Sorular ve Yanıtlar

İlgili içerik

Geri Bildirim

Ek kaynaklar