빌드 프로세스에서 텍스트 변환 호출

  • 아티클

Visual Studio 솔루션 빌드 프로세스의 일부로 텍스트 변환을 호출할 수 있습니다. 이는 텍스트 변형에 대해 특수화된 빌드 작업입니다. T4 빌드 작업은 디자인 타임 텍스트 템플릿을 실행하고 전처리된 런타임 텍스트 템플릿을 컴파일합니다.

사용하는 빌드 엔진에 따라 빌드 작업에서 수행할 수 있는 몇 가지 작업이 다를 수 있습니다. Visual Studio에서 솔루션을 빌드할 때 hostspecific="true" 특성이 설정되어 있으면 텍스트 템플릿이 Visual Studio API(EnvDTE)에 액세스할 수 있습니다. 그러나 명령줄에서 솔루션을 빌드하거나 Visual Studio를 통해 서버 빌드를 시작할 때는 액세스할 수 없습니다. 이러한 경우에는 MSBuild에서 빌드가 수행되고 다른 T4 호스트가 사용됩니다. 즉, MSBuild를 사용하여 텍스트 템플릿을 빌드하는 경우와 같은 방법으로 프로젝트 파일 이름 같은 항목에 액세스할 수 없습니다. 그러나 빌드 매개 변수를 사용하여 환경 정보를 텍스트 템플릿과 명령 프로세서에 전달할 수 있습니다.

컴퓨터 구성

개발 컴퓨터에서 빌드 작업을 사용하려면 Modeling SDK for Visual Studio를 설치합니다.

참고

텍스트 템플릿 변환 구성 요소는 Visual Studio 확장 개발 워크로드의 일부로 자동으로 설치됩니다. Visual Studio 설치 프로그램의 개별 구성 요소 탭, SDK, 라이브러리, 프레임워크 범주 아래에서 설치할 수도 있습니다. 개별 구성 요소 탭에서 Modeling SDK 구성 요소를 설치합니다.

Visual Studio가 설치되어 있지 않은 컴퓨터에서 빌드 서버가 실행되는 경우 개발 머신에서 빌드 컴퓨터로 다음 파일을 복사합니다.

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

팁

빌드 서버에서 TextTemplating 빌드 대상을 실행할 때 Microsoft.CodeAnalysis 메서드에 대한 MissingMethodException이 발생하는 경우에는 빌드 실행 파일(예: msbuild.exe)과 동일한 디렉터리에 있는 Roslyn 디렉터리에 Roslyn 어셈블리가 있는지 확인합니다.

프로젝트 파일 편집

프로젝트 파일을 편집하여 MSBuild의 일부 기능(예: 텍스트 변환 대상 가져오기)을 구성합니다.

솔루션 탐색기에서 프로젝트의 마우스 오른쪽 단추 클릭 메뉴에서 언로드를 선택합니다. 이렇게 하면 XML 편집기에서 .csproj 또는 .vbproj 파일을 편집할 수 있습니다. 편집을 마치면 다시 로드를 선택합니다.

텍스트 변환 대상 가져오기

.vbproj 또는 .csproj 파일에서 마지막 Import Project 줄을 찾습니다.

이 줄이 있으면 그 뒤에 텍스트 템플릿 가져오기를 삽입합니다.

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

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

빌드에서 템플릿 변환

변형 작업을 제어하기 위해 프로젝트 파일에 삽입할 수 있는 몇 가지 속성이 있습니다.

  • 모든 빌드를 시작할 때 변환 작업을 실행합니다.

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

  • 예를 들어, 읽기 전용 파일은 체크 아웃되지 않기 때문에 파일을 덮어씁니다.

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

  • 항상 모든 템플릿 변형:

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

    기본적으로 T4 MSBuild 작업은 다음보다 오래된 경우 출력 파일을 다시 생성합니다.

    • 해당 템플릿 파일
    • 포함된 모든 파일
    • 이전에 템플릿이 읽거나 템플릿이 사용하는 지시문 프로세서가 읽은 모든 파일

    이는 템플릿과 출력 파일의 날짜만 비교하는 Visual Studio의 모든 템플릿 변환 명령에서 사용하는 더 강력한 종속성 테스트입니다.

프로젝트에서 텍스트 변형만 수행하려면 TransformAll 작업을 호출합니다.

msbuild myProject.csproj /t:TransformAll

특정한 텍스트 템플릿을 변형하려면 다음을 수행합니다.

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

변형 파일에서 와일드카드를 사용할 수 있습니다.

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

원본 제어

소스 제어 시스템과의 특정 기본 제공 통합은 없습니다. 그러나 생성된 파일을 체크 아웃하고 체크 인하기 위한 용도 등으로 고유한 확장을 추가할 수 있습니다. 기본적으로 텍스트 변환 작업은 읽기 전용으로 표시된 파일을 덮어쓰는 것을 방지합니다. 해당 파일이 발생하면 오류가 Visual Studio 오류 목록에 로그되고 작업이 실패합니다.

읽기 전용 파일을 덮어쓰도록 지정하려면 다음 속성을 삽입합니다.

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

후처리 단계를 사용자 지정하지 않는 한 파일을 덮어쓸 때 경고가 오류 목록에 로그됩니다.

빌드 프로세스 사용자 지정

빌드 프로세스에서 다른 작업을 수행하기 전에 텍스트 변환이 수행됩니다. $(BeforeTransform) 및 $(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>

AfterTransform에서 파일 목록을 참조할 수 있습니다.

  • GeneratedFiles - 프로세스에서 쓴 파일의 목록입니다. 기존 읽기 전용 파일을 덮어쓴 파일의 경우 %(GeneratedFiles.ReadOnlyFileOverwritten)는 true입니다. 이러한 파일은 소스 제어에서 체크 아웃할 수 있습니다.

  • NonGeneratedFiles - 덮어쓰지 않은 읽기 전용 파일의 목록입니다.

예를 들어, 생성된 파일을 체크 아웃하는 작업을 정의합니다.

OutputFilePath 및 OutputFileName

MSBuild에서만 이러한 속성을 사용합니다. Visual Studio의 코드 생성에는 영향을 주지 않습니다. 이러한 속성은 생성된 출력 파일을 다른 폴더 또는 파일로 리디렉션합니다. 대상 폴더가 이미 있어야 합니다.

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

리디렉션하기 유용한 폴더는 $(IntermediateOutputPath)입니다.

출력 파일 이름을 지정하는 경우 템플릿의 출력 지시문에 지정된 확장명보다 해당 이름이 우선적으로 적용됩니다.

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

모두 변환을 사용하거나 단일 파일 생성기를 실행하여 Visual Studio 내에서 템플릿을 변환하는 경우 OutputFileName이나 OutputFilePath를 지정하지 않는 것이 좋습니다. 변환을 실행하는 방법에 따라 서로 다른 파일 경로가 지정됩니다. 이 작업은 혼동될 수 있습니다.

참조 및 포함 경로 추가

템플릿에 참조된 어셈블리를 검색할 때 호스트에 기본 경로 집합이 있습니다. 이 집합에 추가하려면 다음을 수행합니다.

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

포함 파일을 검색할 폴더를 설정하려면 세미콜론 구분 목록을 제공합니다. 일반적으로 기존 폴더 목록에 추가합니다.

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

템플릿으로 빌드 컨텍스트 데이터 전달

프로젝트 파일에서 매개 변수 값을 설정할 수 있습니다. 예를 들어, 빌드 속성과 환경 변수를 전달할 수 있습니다.

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

텍스트 템플릿에서 hostspecific를 템플릿 지시문에 설정하십시오. parameter 지시문을 사용하여 값을 가져옵니다.

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

지시문 프로세서에서 ITextTemplatingEngineHost.ResolveParameterValue를 호출할 수 있습니다.

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

참고

ResolveParameterValue는 MSBuild를 사용하는 경우에만 T4ParameterValues에서 데이터를 가져옵니다. Visual Studio를 사용하여 템플릿을 변환하는 경우 매개 변수에는 기본값이 있습니다.

assembly 및 Include 지시문에서 프로젝트 속성 사용

$(SolutionDir) 같은 Visual Studio 매크로는 MSBuild에서 작동하지 않습니다. 대신 적절한 프로젝트 속성을 사용할 수 있습니다.

.csproj 또는 .vbproj 파일을 편집하여 프로젝트 속성을 정의합니다. 이 예제에서는 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>

이제 assembly 및 Include 지시문에서 프로젝트 속성을 사용할 수 있습니다.

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

이러한 지시문은 MSBuild와 Visual Studio 호스트에서 모두 T4parameterValues의 값을 가져옵니다.

질문 및 답변

왜 빌드 서버에서 템플릿을 변형해야 합니까? 내 코드를 체크 인하기 전에 이미 Visual Studio에서 템플릿을 변형했습니다.

템플릿이 읽은 포함 파일이나 다른 파일을 업데이트하는 경우 Visual Studio는 파일을 자동으로 변환하지 않습니다. 빌드 중에 템플릿을 변환하면 모든 항목이 최신 상태가 됩니다.

텍스트 템플릿 변환에 사용할 수 있는 다른 옵션은 무엇이 있습니까?

관련 콘텐츠

  • %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets에 T4 MSbuild 템플릿의 유용한 지침이 있습니다.
  • %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\msbuild\Microsoft\VisualStudio\v16.0\TextTemplating\Microsoft.TextTemplating.targets에 T4 MSbuild 템플릿의 유용한 지침이 있습니다.