次の方法で共有

チュートリアル: カスタム ディレクティブ プロセッサを作成する

  • [アーティクル]

"ディレクティブ プロセッサ" は、"生成された変換クラス" にコードを追加することで機能します。 "テキスト テンプレート" から "ディレクティブ" を呼び出すと、テキスト テンプレートに記述された残りのコードで、ディレクティブが提供する機能を利用できるようになります。

独自のカスタム ディレクティブ プロセッサを記述できます。 これにより、テキスト テンプレートをカスタマイズすることができます。 カスタム ディレクティブ プロセッサを作成するには、DirectiveProcessor または RequiresProvidesDirectiveProcessor を継承するクラスを作成します。

このチュートリアルでは、次のタスクについて説明します。

  • カスタム ディレクティブ プロセッサを作成する

  • ディレクティブ プロセッサを登録する

  • ディレクティブ プロセッサをテストする

カスタム ディレクティブ プロセッサを作成する

このチュートリアルでは、カスタム ディレクティブ プロセッサを作成します。 XML ファイルを読み取って XmlDocument 変数に格納し、プロパティを通じてそれを公開するカスタム ディレクティブを追加します。 「ディレクティブ プロセッサのテスト」では、テキスト テンプレートでこのプロパティを使用して XML ファイルにアクセスします。

カスタム ディレクティブの呼び出しは、次のような形式で記述します。

<#@ CoolDirective Processor="CustomDirectiveProcessor" FileName="<Your Path>DocFile.xml" #>

カスタム ディレクティブ プロセッサは、生成された変換クラスに変数とプロパティを追加します。 これから記述するディレクティブでは、System.CodeDom クラスを使用して、生成された変換クラスにエンジンによって追加されるコードを作成します。 System.CodeDom クラスは、template ディレクティブの language パラメーターで指定された言語に応じて、Visual C# または Visual Basic でコードを作成します。 ディレクティブ プロセッサの言語とディレクティブ プロセッサにアクセスするテキスト テンプレートの言語は、同じでなくてもかまいません。

ディレクティブによって作成されるコードは次のようになります。

private System.Xml.XmlDocument document0Value;

public virtual System.Xml.XmlDocument Document0
{
  get
  {
    if ((this.document0Value == null))
    {
      this.document0Value = XmlReaderHelper.ReadXml(<FileNameParameterValue>);
    }
    return this.document0Value;
  }
}

カスタム ディレクティブ プロセッサを作成するには

  1. Visual Studio で、CustomDP という名前の C# クラス ライブラリ プロジェクトまたは Visual Basic クラス ライブラリ プロジェクトを作成します。

    Note

    複数のコンピューターにディレクティブ プロセッサをインストールする場合は、Visual Studio Extension (VSIX) プロジェクトを使用し、拡張機能に .pkgdef ファイルを追加することをお勧めします。 詳細については、「カスタム ディレクティブ プロセッサの配置」を参照してください。

  2. 次のアセンブリへの参照を追加します。

    • Microsoft.VisualStudio.TextTemplating.*.0

    • Microsoft.VisualStudio.TextTemplating.Interfaces.*.0

  3. Class1 内のコードを次のコードに置き換えます。 このコードによって、DirectiveProcessor クラスを継承し、必要なメソッドを実装する CustomDirectiveProcessor クラスが定義されます。

    using System;
using System.CodeDom;
using System.CodeDom.Compiler;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Text;
using System.Xml;
using System.Xml.Serialization;
using Microsoft.VisualStudio.TextTemplating;

namespace CustomDP
{
    public class CustomDirectiveProcessor : DirectiveProcessor
    {
        // This buffer stores the code that is added to the
        // generated transformation class after all the processing is done.
        // ---------------------------------------------------------------------
        private StringBuilder codeBuffer;

        // Using a Code Dom Provider creates code for the
        // generated transformation class in either Visual Basic or C#.
        // If you want your directive processor to support only one language, you
        // can hard code the code you add to the generated transformation class.
        // In that case, you do not need this field.
        // --------------------------------------------------------------------------
        private CodeDomProvider codeDomProvider;

        // This stores the full contents of the text template that is being processed.
        // --------------------------------------------------------------------------
        private String templateContents;

        // These are the errors that occur during processing. The engine passes
        // the errors to the host, and the host can decide how to display them,
        // for example the host can display the errors in the UI
        // or write them to a file.
        // ---------------------------------------------------------------------
        private CompilerErrorCollection errorsValue;
        public new CompilerErrorCollection Errors
        {
            get { return errorsValue; }
        }

        // Each time this directive processor is called, it creates a new property.
        // We count how many times we are called, and append "n" to each new
        // property name. The property names are therefore unique.
        // -----------------------------------------------------------------------------
        private int directiveCount = 0;

        public override void Initialize(ITextTemplatingEngineHost host)
        {
            // We do not need to do any initialization work.
        }

        public override void StartProcessingRun(CodeDomProvider languageProvider, String templateContents, CompilerErrorCollection errors)
        {
            // The engine has passed us the language of the text template
            // we will use that language to generate code later.
            // ----------------------------------------------------------
            this.codeDomProvider = languageProvider;
            this.templateContents = templateContents;
            this.errorsValue = errors;

            this.codeBuffer = new StringBuilder();
        }

        // Before calling the ProcessDirective method for a directive, the
        // engine calls this function to see whether the directive is supported.
        // Notice that one directive processor might support many directives.
        // ---------------------------------------------------------------------
        public override bool IsDirectiveSupported(string directiveName)
        {
            if (string.Compare(directiveName, "CoolDirective", StringComparison.OrdinalIgnoreCase) == 0)
            {
                return true;
            }
            if (string.Compare(directiveName, "SuperCoolDirective", StringComparison.OrdinalIgnoreCase) == 0)
            {
                return true;
            }
            return false;
        }

        public override void ProcessDirective(string directiveName, IDictionary<string, string> arguments)
        {
            if (string.Compare(directiveName, "CoolDirective", StringComparison.OrdinalIgnoreCase) == 0)
            {
                string fileName;

                if (!arguments.TryGetValue("FileName", out fileName))
                {
                    throw new DirectiveProcessorException("Required argument 'FileName' not specified.");
                }

                if (string.IsNullOrEmpty(fileName))
                {
                    throw new DirectiveProcessorException("Argument 'FileName' is null or empty.");
                }

                // Now we add code to the generated transformation class.
                // This directive supports either Visual Basic or C#, so we must use the
                // System.CodeDom to create the code.
                // If a directive supports only one language, you can hard code the code.
                // --------------------------------------------------------------------------

                CodeMemberField documentField = new CodeMemberField();

                documentField.Name = "document" + directiveCount + "Value";
                documentField.Type = new CodeTypeReference(typeof(XmlDocument));
                documentField.Attributes = MemberAttributes.Private;

                CodeMemberProperty documentProperty = new CodeMemberProperty();

                documentProperty.Name = "Document" + directiveCount;
                documentProperty.Type = new CodeTypeReference(typeof(XmlDocument));
                documentProperty.Attributes = MemberAttributes.Public;
                documentProperty.HasSet = false;
                documentProperty.HasGet = true;

                CodeExpression fieldName = new CodeFieldReferenceExpression(new CodeThisReferenceExpression(), documentField.Name);
                CodeExpression booleanTest = new CodeBinaryOperatorExpression(fieldName, CodeBinaryOperatorType.IdentityEquality, new CodePrimitiveExpression(null));
                CodeExpression rightSide = new CodeMethodInvokeExpression(new CodeTypeReferenceExpression("XmlReaderHelper"), "ReadXml", new CodePrimitiveExpression(fileName));
                CodeStatement[] thenSteps = new CodeStatement[] { new CodeAssignStatement(fieldName, rightSide) };

                CodeConditionStatement ifThen = new CodeConditionStatement(booleanTest, thenSteps);
                documentProperty.GetStatements.Add(ifThen);

                CodeStatement s = new CodeMethodReturnStatement(fieldName);
                documentProperty.GetStatements.Add(s);

                CodeGeneratorOptions options = new CodeGeneratorOptions();
                options.BlankLinesBetweenMembers = true;
                options.IndentString = "    ";
                options.VerbatimOrder = true;
                options.BracingStyle = "C";

                using (StringWriter writer = new StringWriter(codeBuffer, CultureInfo.InvariantCulture))
                {
                    codeDomProvider.GenerateCodeFromMember(documentField, writer, options);
                    codeDomProvider.GenerateCodeFromMember(documentProperty, writer, options);
                }
            }

            // One directive processor can contain many directives.
            // If you want to support more directives, the code goes here...
            // -----------------------------------------------------------------
            if (string.Compare(directiveName, "supercooldirective", StringComparison.OrdinalIgnoreCase) == 0)
            {
                // Code for SuperCoolDirective goes here...
            }

            // Track how many times the processor has been called.
            // -----------------------------------------------------------------
            directiveCount++;

        }

        public override void FinishProcessingRun()
        {
            this.codeDomProvider = null;

            // Important: do not do this:
            // The get methods below are called after this method
            // and the get methods can access this field.
            // -----------------------------------------------------------------
            // this.codeBuffer = null;
        }

        public override string GetPreInitializationCodeForProcessingRun()
        {
            // Use this method to add code to the start of the
            // Initialize() method of the generated transformation class.
            // We do not need any pre-initialization, so we will just return "".
            // -----------------------------------------------------------------
            // GetPreInitializationCodeForProcessingRun runs before the
            // Initialize() method of the base class.
            // -----------------------------------------------------------------
            return String.Empty;
        }

        public override string GetPostInitializationCodeForProcessingRun()
        {
            // Use this method to add code to the end of the
            // Initialize() method of the generated transformation class.
            // We do not need any post-initialization, so we will just return "".
            // ------------------------------------------------------------------
            // GetPostInitializationCodeForProcessingRun runs after the
            // Initialize() method of the base class.
            // -----------------------------------------------------------------
            return String.Empty;
        }

        public override string GetClassCodeForProcessingRun()
        {
            //Return the code to add to the generated transformation class.
            // -----------------------------------------------------------------
            return codeBuffer.ToString();
        }

        public override string[] GetReferencesForProcessingRun()
        {
            // This returns the references that we want to use when
            // compiling the generated transformation class.
            // -----------------------------------------------------------------
            // We need a reference to this assembly to be able to call
            // XmlReaderHelper.ReadXml from the generated transformation class.
            // -----------------------------------------------------------------
            return new string[]
            {
                "System.Xml",
                this.GetType().Assembly.Location
            };
        }

        public override string[] GetImportsForProcessingRun()
        {
            //This returns the imports or using statements that we want to
            //add to the generated transformation class.
            // -----------------------------------------------------------------
            //We need CustomDP to be able to call XmlReaderHelper.ReadXml
            //from the generated transformation class.
            // -----------------------------------------------------------------
            return new string[]
            {
                "System.Xml",
                "CustomDP"
            };
        }
    }

    // -------------------------------------------------------------------------
    // The code that we are adding to the generated transformation class
    // will call this method.
    // -------------------------------------------------------------------------
    public static class XmlReaderHelper
    {
        public static XmlDocument ReadXml(string fileName)
        {
            XmlDocument d = new XmlDocument();

            using (XmlReader reader = XmlReader.Create(fileName))
            {
                try
                {
                    d.Load(reader);
                }
                catch (System.Xml.XmlException e)
                {
                    throw new DirectiveProcessorException("Unable to read the XML file.", e);
                }
            }
            return d;
        }
    }
}

  4. Visual Basic の場合にのみ、[プロジェクト] メニューの [CustomDP のプロパティ] をクリックします。 [アプリケーション] タブの [ルート名前空間] で、既定値の CustomDP を削除します。

  5. [ファイル] メニューの [すべてを保存] をクリックします。

  6. [ビルド] メニューの [ソリューションのビルド] をクリックします。

プロジェクトをビルドする

プロジェクトをビルドします。 [ビルド] メニューの [ソリューションのビルド] をクリックします。

ディレクティブ プロセッサを登録する

Visual Studio でテキスト テンプレートからディレクティブを呼び出す前に、ディレクティブ プロセッサのレジストリ キーを追加する必要があります。

Note

複数のコンピューターにディレクティブ プロセッサをインストールする場合は、アセンブリと .pkgdef ファイルを含む Visual Studio Extension (VSIX) を定義することをお勧めします。 詳細については、「カスタム ディレクティブ プロセッサの配置」を参照してください。

ディレクティブ プロセッサのキーは次の場所のレジストリにあります。

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors

64 ビット システムの場合、レジストリは次の場所にあります。

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors

ここでは、この場所にカスタム ディレクティブ プロセッサのキーを追加します。

注意

レジストリを誤って編集すると、システムに重大な障害が発生する場合があります。 レジストリを変更する前に、コンピューター上の重要なデータをすべてバックアップしてください。

ディレクティブ プロセッサのレジストリ キーを追加するには

  1. [スタート] メニューまたはコマンド ラインを使用して、regedit コマンドを実行します。

  2. HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors に移動し、ノードをクリックします。

    64 ビット システムでは、HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors を使用します。

  3. CustomDirectiveProcessor という名前の新しいキーを追加します。

    Note

    これは、カスタム ディレクティブの Processor フィールドで使用する名前です。 この名前は、ディレクティブの名前、ディレクティブ プロセッサ クラスの名前、またはディレクティブ プロセッサの名前空間と同じでなくてもかまいません。

  4. Class という名前の新しい文字列値を追加し、その新しい文字列に CustomDP.CustomDirectiveProcessor という値を設定します。

  5. CodeBase という名前の新しい文字列値を追加し、このチュートリアルで作成した CustomDP.dll のパスに一致する値を設定します。

    たとえば、パスは C:\UserFiles\CustomDP\bin\Debug\CustomDP.dll のようになります。

    レジストリ キーの値は次のようになります。

    名前 Type データ
    (既定) REG_SZ (値が設定されていません)
    クラス REG_SZ CustomDP.CustomDirectiveProcessor
    CodeBase REG_SZ <ソリューションのパス>CustomDP\bin\Debug\CustomDP.dll

    アセンブリを GAC に追加した場合は、値を次のように設定します。

    名前 Type データ
    (既定) REG_SZ (値が設定されていません)
    クラス REG_SZ CustomDP.CustomDirectiveProcessor
    組み立て REG_SZ CustomDP.dll

  6. Visual Studio を再起動します。

ディレクティブ プロセッサをテストする

ディレクティブ プロセッサをテストするには、それを呼び出すテキスト テンプレートを記述する必要があります。

この例のテキスト テンプレートでは、ディレクティブを呼び出し、クラス ファイルのドキュメントを含む XML ファイルの名前を渡します。 テキスト テンプレートでは、ディレクティブによって作成された XmlDocument プロパティを使用して XML をナビゲートし、ドキュメントのコメントを出力します。

ディレクティブ プロセッサのテストに使用する XML ファイルを作成するには

  1. 任意のテキスト エディター (メモ帳など) を使用して、DocFile.xml という名前のファイルを作成します。

    Note

    このファイルはどこに作成してもかまいません (C:\Test\DocFile.xml など)。

  2. XML ファイルに次を追加します。

    <?xml version="1.0"?>
<doc>
    <assembly>
        <name>xmlsample</name>
    </assembly>
    <members>
        <member name="T:SomeClass">
            <summary>Class level summary documentation goes here.</summary>
            <remarks>Longer comments can be associated with a type or member through the remarks tag</remarks>
        </member>
        <member name="F:SomeClass.m_Name">
            <summary>Store for the name property</summary>
        </member>
        <member name="M:SomeClass.#ctor">
            <summary>The class constructor.</summary>
        </member>
        <member name="M:SomeClass.SomeMethod(System.String)">
            <summary>Description for SomeMethod.</summary>
            <param name="s">Parameter description for s goes here</param>
            <seealso cref="T:System.String">You can use the cref attribute on any tag to reference a type or member and the compiler will check that the reference exists.</seealso>
        </member>
        <member name="M:SomeClass.SomeOtherMethod">
            <summary>Some other method.</summary>
            <returns>Return results are described through the returns tag.</returns>
            <seealso cref="M:SomeClass.SomeMethod(System.String)">Notice the use of the cref attribute to reference a specific method</seealso>
        </member>
        <member name="M:SomeClass.Main(System.String[])">
            <summary>The entry point for the application.</summary>
            <param name="args">A list of command line arguments</param>
        </member>
        <member name="P:SomeClass.Name">
            <summary>Name property</summary>
            <value>A value tag is used to describe the property value</value>
        </member>
    </members>
</doc>

  3. ファイルを保存して閉じます。

テキスト テンプレートを作成してディレクティブ プロセッサをテストするには

  1. Visual Studio で、TemplateTest という名前の C# クラス ライブラリ プロジェクトまたは Visual Basic クラス ライブラリ プロジェクトを作成します。

  2. TestDP.tt という名前の新しいテキスト テンプレート ファイルを追加します。

  3. TestDP.tt の [カスタム ツール] プロパティが TextTemplatingFileGenerator に設定されていることを確認します。

  4. TestDP.tt の内容を次のテキストに変更します。

    Note

    <YOUR PATH> という文字列は、DocFile.xml ファイルのパスに置き換えます。

    テキスト テンプレートの言語は、ディレクティブ プロセッサの言語と同じでなくてもかまいません。

    <#@ assembly name="System.Xml" #>
<#@ template debug="true" #>
<#@ output extension=".txt" #>

<#  // This will call the custom directive processor. #>
<#@ CoolDirective Processor="CustomDirectiveProcessor" FileName="<YOUR PATH>\DocFile.xml" #>

<#  // Uncomment this line if you want to see the generated transformation class. #>
<#  // System.Diagnostics.Debugger.Break(); #>

<#  // This will use the results of the directive processor. #>
<#  // The directive processor has read the XML and stored it in Document0. #>
<#
    XmlNode node = Document0.DocumentElement.SelectSingleNode("members");

    foreach (XmlNode member in node.ChildNodes)
    {
        XmlNode name = member.Attributes.GetNamedItem("name");
        WriteLine("{0,7}:  {1}", "Name", name.Value);

        foreach (XmlNode comment in member.ChildNodes)
        {
            WriteLine("{0,7}:  {1}", comment.Name, comment.InnerText);
        }
        WriteLine("");
    }
#>

<# // You can call the directive processor again and pass it a different file. #>
<# // @ CoolDirective Processor="CustomDirectiveProcessor" FileName="<YOUR PATH>\<Your Second File>" #>

<#  // To use the results of the second directive call, use Document1. #>
<#
    // XmlNode node2 = Document1.DocumentElement.SelectSingleNode("members");

    // ...
#>

    Note

    この例では、Processor パラメーターの値は CustomDirectiveProcessor です。 Processor パラメーターの値は、プロセッサのレジストリ キーの名前に一致する必要があります。

  5. [ファイル] メニューの [すべてを保存] を選択します。

ディレクティブ プロセッサをテストするには

  1. ソリューション エクスプローラーで、TestDP.tt を右クリックし、[カスタム ツールの実行] をクリックします。

    Visual Basic ユーザーの場合、既定では TestDP.txt がソリューション エクスプローラーに表示されない可能性があります。 プロジェクトに割り当てられているすべてのファイルを表示するには、[プロジェクト] メニューの [すべてのファイルを表示] をクリックします。

  2. ソリューション エクスプローラーで、TestDP.txt ノードを展開し、TestDP.txt をダブルクリックしてエディターで開きます。

    生成されたテキスト出力が表示されます。 出力は次のようになります。

       Name:  T:SomeClass
summary:  Class level summary documentation goes here.
remarks:  Longer comments can be associated with a type or member through the remarks tag

   Name:  F:SomeClass.m_Name
summary:  Store for the name property

   Name:  M:SomeClass.#ctor
summary:  The class constructor.

   Name:  M:SomeClass.SomeMethod(System.String)
summary:  Description for SomeMethod.
  param:  Parameter description for s goes here
seealso:  You can use the cref attribute on any tag to reference a type or member and the compiler will check that the reference exists.

   Name:  M:SomeClass.SomeOtherMethod
summary:  Some other method.
returns:  Return results are described through the returns tag.
seealso:  Notice the use of the cref attribute to reference a specific method

   Name:  M:SomeClass.Main(System.String[])
summary:  The entry point for the application.
  param:  A list of command line arguments

   Name:  P:SomeClass.Name
summary:  Name property
  value:  A value tag is used to describe the property value

生成されたテキストに HTML を追加する

カスタム ディレクティブ プロセッサをテストした後は、生成されたテキストに HTML を追加できます。

生成されたテキストに HTML を追加するには

  1. TestDP.tt 内のコードを次のコードに置き換えます。 HTML は強調表示されています。 YOUR PATH という文字列は、DocFile.xml ファイルのパスに置き換えてください。

    Note

    ステートメント コードは、追加の開始タグ (<#) と終了タグ (#>) によって HTML タグと区別されます。

    <#@ assembly name="System.Xml" #>
<#@ template debug="true" #>
<#@ output extension=".htm" #>

<#  // This will call the custom directive processor #>
<#@ CoolDirective Processor="CustomDirectiveProcessor" FileName="<YOUR PATH>\DocFile.xml" #>

<#  // Uncomment this line if you want to see the generated transformation class #>
<#  // System.Diagnostics.Debugger.Break(); #>

<html><body>

<#  // This will use the results of the directive processor #>.
<#  // The directive processor has read the XML and stored it in Document0#>.
<#
    XmlNode node = Document0.DocumentElement.SelectSingleNode("members");

    foreach (XmlNode member in node.ChildNodes)
    {
#>
<h3>
<#
        XmlNode name = member.Attributes.GetNamedItem("name");
        WriteLine("{0,7}:  {1}", "Name", name.Value);
#>
</h3>
<#
        foreach (XmlNode comment in member.ChildNodes)
        {
            WriteLine("{0,7}:  {1}", comment.Name, comment.InnerText);
#>
<br/>
<#
        }
    }
#>
</body></html>

  2. [ファイル] メニューの [TestDP.txt の保存] をクリックします。

  3. 出力をブラウザーで表示するには、ソリューション エクスプローラーで TestDP.htm を右クリックし、[ブラウザーで表示] をクリックします。

    HTML 形式が適用される点を除き、出力は元のテキストと同じです。 各項目名は太字で表示されます。