Aracılığıyla paylaş

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

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ş derleme görevleri vardır. T4 derleme görevleri tasarım zamanı metin şablonlarını çalıştırır ve ayrıca çalışma zamanı (önceden işlenmiş) metin şablonlarını derler.

Hangi derleme altyapısını kullandığınıza bağlı olarak, derleme görevlerinin yapabilecekleri konusunda bazı farklılıklar vardır. Çö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 gibi durumlarda derleme MSBuild tarafından gerçekleştirilir ve farklı bir T4 konağı 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.

Uyarı

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. Bunu Visual Studio Yükleyicisi'nin 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

Tip

Derleme sunucusunda TextTemplating derleme hedeflerini çalıştırırken Microsoft.CodeAnalysis yöntemi için bir MissingMethodException alırsanız, 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'nde projenizin sağ tıklama menüsünden Kaldır'ı seçin. Bu, XML düzenleyicisinde .csproj veya .vbproj dosyasını düzenlemenizi sağlar. 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, eğer varsa, Metin Şablonlama içeri aktarmasını ekleyin.

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

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

Dönüştürme görevini denetlemek için proje dosyanıza ekleyebileceğiniz bazı özellikler vardır:

  • Dönüştürme görevini her derlemenin başında çalıştırın:

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

  • Salt okunur olan ve örneğin henüz çıkış yapılmamış dosyaların üzerine yazın:

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

  • Her şablonu her seferinde dönüştürün:

    <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 bir metin şablonunu 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 sistemiyle belirli bir yerleşik 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 şu özelliği ekleyin:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

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

Derleme işlemini özelleştirme

Metin dönüştürme, derleme işlemindeki diğer görevlerden önce 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>

AfterTransform içinde 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 dışarı alınabilir.

  • 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 oluşturmayı etkilemez. Oluşturulan çıkış dosyasını farklı bir klasöre veya dosyaya yönlendirir. Hedef klasör zaten var olmalıdır.

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

Referans ve ekleme yolları ekle

Ana makine, şablonlarda başvurulan derlemeleri aramak için varsayılan bir dizin kümesine sahiptir. Bu kümeye eklemek için:

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

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

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

Yapı bağlam verilerini şablonlara geçirme

Proje dosyasında parametre değerleri 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");

Uyarı

ResolveParameterValue, yalnızca MSBuild kullandığınızda T4ParameterValues'den veri 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 proje özelliğinizi kullanabilir ve yönergelerini ekleyebilirsiniz:

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

Bu yönergeler hem MSBuild'de hem de Visual Studio konaklarında T4parameterValues'tan değerler alır.

Sorular ve Yanıtlar

Derleme sunucusunda şablonları neden dönüştürmek isteyeyim? Kodumu depolamadan önce Visual Studio'daki şablonları zaten dönüştürdü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?

İlgili içerik

  • 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
  • Last updated on