T4 템플릿 지시문

일반적으로 Visual Studio T4 텍스트 템플릿은 템플릿의 처리 방식을 지정하는 template 지시문으로 시작합니다. 하나의 텍스트 템플릿 및 템플릿이 포함된 파일에는 템플릿 지시문이 하나만 있어야 합니다.

텍스트 템플릿 작성에 대한 일반적인 개요를 보려면 T4 텍스트 템플릿 쓰기을 참조하십시오.

template 지시문 사용

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

template 지시문에는 변환의 다양한 측면을 지정할 수 있도록 하는 몇 가지 특성이 있습니다. 모든 특성은 선택적입니다.

compilerOptions 특성

• 예를 들면 다음과 같은 형식입니다.
  compilerOptions="optimize+"

• 유효한 값:
  유효한 컴파일러 옵션입니다. 자세한 내용은 C# 컴파일러 옵션 범주별 목록 및 Visual Basic 컴파일러 옵션 범주별 목록을 참조하십시오.

  전처리된 런타임 템플릿의 경우 무시됩니다.

이 옵션은 템플릿이 Visual C# 또는 Visual Basic으로 변환된 경우 적용되며 결과 코드는 컴파일됩니다.

culture 특성

• 예를 들면 다음과 같은 형식입니다.
  culture="de-CH"

• 유효한 값:
  "", 기본값인 고정 문화권입니다.

  xx-XX 형식의 문자열로 표현된 문화권. 예를 들어 en-US, ja-JP, de-CH, de-DE 등입니다. 자세한 내용은 CultureInfo를 참조하십시오.

식 블록이 텍스트로 변환될 때 사용할 문화권을 지정하는 culture 특성입니다.

debug 특성

• 예제:

  debug="true"
  

• 유효한 값:
  true, false. 기본값은 False입니다.

debug 특성이 true인 경우 중간 코드 파일에 디버거가 중단 또는 예외가 발생한 템플릿의 위치를 정확하게 식별할 수 있도록 하는 정보가 포함됩니다.

디자인 타임 템플릿의 경우에는 중간 코드 파일이 %TEMP% 디렉터리에 작성됩니다.

디버거에서 디자인 타임 템플릿을 실행하려면 텍스트 템플릿을 저장한 다음 솔루션 탐색기에서 텍스트 템플릿의 바로 가기 메뉴를 열고 T4 템플릿 디버깅을 선택합니다.

hostspecific 특성

• 예제:

  hostspecific="true"
  

• 유효한 값:
  true, false, trueFromBase. 기본값은 False입니다.

이 특성의 값을 true로 설정하면 Host라는 속성이 텍스트 템플릿에서 생성된 클래스에 추가됩니다. 이 속성은 변환 엔진의 호스트에 대한 참조이며 ITextTemplatingEngineHost로 선언됩니다. 사용자 지정 호스트를 정의한 경우에는 해당 호스트를 사용자 지정 호스트 형식으로 캐스팅할 수 있습니다.

이 속성의 형식이 호스트의 형식에 따라 달라지기 때문에 이 속성은 특정 호스트에서만 작동하는 텍스트 템플릿을 작성하는 경우에만 유용합니다. 이는 런타임 템플릿이 아닌 디자인 타임 템플릿에 적용됩니다.

hostspecific이 true이고 Visual Studio를 사용하고 있는 경우 this.Host를 IServiceProvider로 캐스팅하여 Visual Studio 기능에 액세스할 수 있습니다. Host.ResolvePath(filename)를 사용하여 프로젝트에서 파일의 절대 경로를 가져올 수도 있습니다. 예를 들면 다음과 같습니다.

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

inherits와 hostspecific 특성을 함께 사용하는 경우, 파생 클래스에 host="trueFromBase"를 지정하고 기본 클래스에는 host="true"를 지정하십시오. 이렇게 하면 생성된 코드에서 Host 속성의 이중 정의를 피할 수 있습니다.

language 특성

• 예제:
  language="VB"

• 유효한 값:
  C#(기본값)

  VB

language 특성은 문 및 식 블록에서 소스 코드에 사용할 언어(Visual Basic 또는 Visual C#)를 지정합니다. 출력이 생성되는 중간 코드 파일에서 이 언어가 사용됩니다. 이 언어는 템플릿에서 생성되는 언어와 관련이 없으며 모든 종류의 텍스트일 수 있습니다.

예를 들면 다음과 같습니다.

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

inherits 특성

템플릿의 프로그램 코드가 텍스트 템플릿에서 생성될 수도 있는 다른 클래스에서 상속하도록 지정할 수 있습니다.

전처리된 런타임 텍스트 템플릿의 상속

런타임 텍스트 템플릿 간에 상속을 사용하여 여러 파생 변형이 있는 기본 템플릿을 만들 수 있습니다. 런타임 템플릿은 사용자 지정 도구 속성이 TextTemplatingFilePreprocessor로 설정된 템플릿입니다. 런타임 템플릿에서는 응용 프로그램에서 호출하여 템플릿에 정의된 텍스트를 만들 수 있는 코드를 생성합니다. 자세한 내용은 T4 텍스트 템플릿을 사용하여 런타임 텍스트 생성을 참조하십시오.

inherits 특성을 지정하지 않으면 기본 클래스 및 파생 클래스가 텍스트 템플릿에서 생성됩니다. inherits 특성을 지정하면 파생 클래스만 생성됩니다. 기본 클래스를 직접 작성할 수 있지만 기본 클래스에서 파생 클래스에 사용되는 메서드를 제공해야 합니다.

또한 전처리된 다른 템플릿을 기본 클래스로 지정하는 것이 더 일반적입니다. 기본 템플릿에서는 파생 템플릿의 텍스트를 인터리브할 수 있는 공통 텍스트 블록을 제공합니다. 클래스 기능 블록 <#+ ... #>을 사용하여 텍스트 조각이 들어 있는 메서드를 정의할 수 있습니다. 예를 들어 출력 텍스트의 프레임워크를 기본 템플릿에 둠으로써 파생 템플릿에 재정의할 수 있는 가상 메서드를 제공할 수 있습니다.

• 전처리된 런타임 텍스트 템플릿 BaseTemplate.tt:

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• 전처리된 런타임 텍스트 템플릿 DerivedTemplate1.tt:

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• DerivedTemplate1을 호출할 응용 프로그램 코드:

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• 결과 출력:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

서로 다른 프로젝트에서 기본 클래스와 파생 클래스를 빌드할 수 있습니다. 기본 프로젝트 또는 어셈블리를 파생 프로젝트의 참조에 추가해야 합니다.

직접 작성한 일반 클래스를 기본 클래스로 사용할 수도 있습니다. 기본 클래스는 파생 클래스에 사용되는 메서드를 제공합니다.

경고

inherits와 hostspecific 특성을 함께 사용하는 경우, 파생 클래스에 hostspecific="trueFromBase"를 지정하고 기본 클래스에는 host="true"를 지정하십시오.이렇게 하면 생성된 코드에서 Host 속성의 이중 정의를 피할 수 있습니다.

디자인 타임 텍스트 템플릿의 상속

디자인 타임 텍스트 템플릿은 사용자 지정 도구가 TextTemplatingFileGenerator로 설정된 파일입니다. 이 템플릿에서는 Visual Studio 프로젝트의 일부를 구성하는 코드 또는 텍스트의 출력 파일을 생성합니다. 출력 파일을 생성하기 위해 먼저 템플릿이 중간 프로그램 코드 파일로 변환되며, 대개 이 파일은 보이지 않습니다. inherits 특성은 이 중간 코드를 위한 기본 클래스를 지정합니다.

디자인 타임 텍스트 템플릿의 경우에는 TextTransformation 클래스에서 파생되는 기본 클래스를 지정할 수 있습니다. <#@assembly#> 지시문을 사용하여 기본 클래스가 들어 있는 프로젝트나 어셈블리를 로드합니다.

자세한 내용은 Gareth Jones 블로그의 "Inheritance in Text Templates"를 참조하십시오.

LinePragmas 특성

• 예제:
  linePragmas="false"

• 유효한 값:
  true(기본값)

  false

이 특성을 false로 설정하면 생성된 코드에서 줄 번호를 식별하는 태그가 제거됩니다. 즉, 컴파일러에서 생성된 코드의 줄 번호를 사용하여 모든 오류를 보고하는 것을 의미합니다. 이렇게 하면 텍스트 템플릿 또는 생성된 코드를 디버깅하도록 선택할 수 있어 더 많은 디버깅 옵션을 사용할 있습니다.

이 특성은 소스 코드 컨트롤에 따라 프로그램에서 산만한 병합을 유발하는 정확한 파일 이름을 찾는 경우 유용할 수 있습니다.

표시 유형 특성

• 예제:
  visibility="internal"

• 유효한 값:
  public(기본값)

  internal

런타임 텍스트 템플릿에서 생성된 클래스의 표시 유형 특성을 설정합니다. 기본적으로 클래스는 사용자 코드의 공용 API에 속하지만 visibility="internal"을 설정하여 사용자의 코드만 텍스트 생성 클래스를 사용할 수 있도록 지정할 수 있습니다.