Walkthrough: Creating a Custom Directive Processor
Collapse the table of content
Expand the table of content
The document is archived and information here might be outdated

Walkthrough: Creating a Custom Directive Processor 

Directive processors work by adding code to the generated transformation class. If you call a directive from a text template, the rest of the code that you write in your text template can rely on the functionality that the directive provides. You can write custom directive processors to provide custom functionality to text templates. For more information, see Architecture of the Text Template Transformation Process.

Tasks illustrated in this walkthrough include:

  • How to create a custom directive processor.

  • How to add a registry key for the directive processor.

  • How to test the directive processor.

To complete this walkthrough, you will need:

In this walkthrough, you create a custom directive processor. You add a directive that reads an XML file, stores it in an XmlDocument variable, and exposes it through a property. In the section "Test the Directive Processor," you use this property in a text template to access the XML file.

The call to your custom directive looks like the following example:

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

The variable and the property are added to the generated transformation class. The directive that you write uses the System.CodeDom classes to create the code that the engine adds to the generated transformation class. The System.CodeDom classes create code in either Visual C# or Visual Basic, depending on the language specified in the language parameter of the template directive. Therefore, the language of the directive processor and the language of the text template that is accessing the directive processor do not have to match.

The code that the directive creates looks like the following:

private System.Xml.XmlDocument document0Value;

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

To create a custom directive processor

  1. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.

  2. Under Project types, click either the Visual Basic or Visual C# node, according to your preference.

  3. Under Visual Studio installed templates, click Class Library.

  4. In Name, type CustomDP.

  5. Select the Create directory for solution check box, and click OK.

    A class library project is created and opens.

  6. On the Project menu, click Add Reference.

    The Add Reference dialog box opens with the .NET tab displayed.

  7. In the Component Name column, click Microsoft.VisualStudio.TextTemplating, and click OK.

  8. In Solution Explorer, double-click Class1 to open it in the editor.

  9. Replace the code in Class1 with the following code:

    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 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);
                    }
    
                }//end CoolDirective
    
    
                //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...
                }//end SuperCoolDirective
    
    
                //Track how many times the processor has been called.
                //-----------------------------------------------------------------
                directiveCount++;
    
            }//end ProcessDirective
    
    
            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"
                };
            }
        }//end class CustomDirectiveProcessor
    
    
        //-------------------------------------------------------------------------
        // 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 (XmlTextReader reader = new XmlTextReader(fileName))
                {
                    try
                    {
                        d.Load(reader);
                    }
                    catch (System.Xml.XmlException e)
                    {
                        throw new DirectiveProcessorException("Unable to read the XML file.", e);
                    }
                }
                return d;
            }
        }//end class XmlReaderHelper
    }//end namespace CustomDP
    

    Imports System
    Imports System.CodeDom
    Imports System.CodeDom.Compiler
    Imports System.Collections.Generic
    Imports System.Globalization
    Imports System.IO
    Imports System.Text
    Imports System.Xml
    Imports System.Xml.Serialization
    Imports Microsoft.VisualStudio.TextTemplating
    
    Namespace CustomDP
    
        Public Class CustomDirectiveProcessor
        Inherits DirectiveProcessor
    
            'this buffer stores the code that is added to the 
            'generated transformation class after all the processing is done 
            '---------------------------------------------------------------
            Private codeBuffer As StringBuilder
    
    
            '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 As CodeDomProvider
    
    
            'this stores the full contents of the text template that is being processed
            '--------------------------------------------------------------------------
            Private templateContents As String
    
    
            '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 the host can display the errors in the UI
            'or write them to a file.
            '---------------------------------------------------------------------
            Private errorsValue As CompilerErrorCollection
            Public Shadows ReadOnly Property Errors() As CompilerErrorCollection
                Get
                    Return errorsValue
                End Get
            End Property
    
    
            '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 directiveCount As Integer = 0
    
    
            Public Overrides Sub Initialize(ByVal host As ITextTemplatingEngineHost)
    
                'we do not need to do any initialization work
            End Sub
    
    
            Public Overrides Sub StartProcessingRun(ByVal languageProvider As CodeDomProvider, ByVal templateContents As String, ByVal errors As CompilerErrorCollection)
    
                'the engine has passed us the language of the text template
                'we will use that language to generate code later
                '----------------------------------------------------------
                Me.codeDomProvider = languageProvider
                Me.templateContents = templateContents
                Me.errorsValue = errors
    
                Me.codeBuffer = New StringBuilder()
            End Sub
    
    
            '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 Overrides Function IsDirectiveSupported(ByVal directiveName As String) As Boolean
    
                If String.Compare(directiveName, "CoolDirective", StringComparison.OrdinalIgnoreCase) = 0 Then
                    Return True
                End If
    
                If String.Compare(directiveName, "SuperCoolDirective", StringComparison.OrdinalIgnoreCase) = 0 Then
                    Return True
                End If
    
                Return False
            End Function
    
    
            Public Overrides Sub ProcessDirective(ByVal directiveName As String, ByVal arguments As IDictionary(Of String, String))
    
                If String.Compare(directiveName, "CoolDirective", StringComparison.OrdinalIgnoreCase) = 0 Then
    
                    Dim fileName As String
    
                    If Not (arguments.TryGetValue("FileName", fileName)) Then
                        Throw New DirectiveProcessorException("Required argument 'FileName' not specified.")
                    End If
    
                    If String.IsNullOrEmpty(fileName) Then
                        Throw New DirectiveProcessorException("Argument 'FileName' is null or empty.")
                    End If
    
                    '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.
                    '--------------------------------------------------------------------------
    
                    Dim documentField As CodeMemberField = New CodeMemberField()
    
                    documentField.Name = "document" & directiveCount & "Value"
                    documentField.Type = New CodeTypeReference(GetType(XmlDocument))
                    documentField.Attributes = MemberAttributes.Private
    
                    Dim documentProperty As CodeMemberProperty = New CodeMemberProperty()
    
                    documentProperty.Name = "Document" & directiveCount
                    documentProperty.Type = New CodeTypeReference(GetType(XmlDocument))
                    documentProperty.Attributes = MemberAttributes.Public
                    documentProperty.HasSet = False
                    documentProperty.HasGet = True
    
                    Dim fieldName As CodeExpression = New CodeFieldReferenceExpression(New CodeThisReferenceExpression(), documentField.Name)
                    Dim booleanTest As CodeExpression = New CodeBinaryOperatorExpression(fieldName, CodeBinaryOperatorType.IdentityEquality, New CodePrimitiveExpression(Nothing))
                    Dim rightSide As CodeExpression = New CodeMethodInvokeExpression(New CodeTypeReferenceExpression("XmlReaderHelper"), "ReadXml", New CodePrimitiveExpression(fileName))
                    Dim thenSteps As CodeStatement() = New CodeStatement() {New CodeAssignStatement(fieldName, rightSide)}
    
                    Dim ifThen As CodeConditionStatement = New CodeConditionStatement(booleanTest, thenSteps)
                    documentProperty.GetStatements.Add(ifThen)
    
                    Dim s As CodeStatement = New CodeMethodReturnStatement(fieldName)
                    documentProperty.GetStatements.Add(s)
    
                    Dim options As CodeGeneratorOptions = New CodeGeneratorOptions()
                    options.BlankLinesBetweenMembers = True
                    options.IndentString = "    "
                    options.VerbatimOrder = True
                    options.BracingStyle = "VB"
    
                    Using writer As StringWriter = New StringWriter(codeBuffer, CultureInfo.InvariantCulture)
    
                        codeDomProvider.GenerateCodeFromMember(documentField, writer, options)
                        codeDomProvider.GenerateCodeFromMember(documentProperty, writer, options)
                    End Using
    
                End If  'CoolDirective
    
    
                '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 Then
    
                    'code for SuperCoolDirective goes here
                End If 'SuperCoolDirective
    
                'Track how many times the processor has been called.
                '-----------------------------------------------------------------
                directiveCount += 1
            End Sub 'ProcessDirective
    
    
            Public Overrides Sub FinishProcessingRun()
    
                Me.codeDomProvider = Nothing
    
                'important: do not do this:
                'the get methods below are called after this method 
                'and the get methods can access this field
                '-----------------------------------------------------------------
                'Me.codeBuffer = Nothing
            End Sub
    
    
            Public Overrides Function GetPreInitializationCodeForProcessingRun() As String
    
                '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
            End Function
    
    
            Public Overrides Function GetPostInitializationCodeForProcessingRun() As String
    
                '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
            End Function
    
    
            Public Overrides Function GetClassCodeForProcessingRun() As String
    
                'Return the code to add to the generated transformation class.
                '-----------------------------------------------------------------
                Return codeBuffer.ToString()
            End Function
    
    
            Public Overrides Function GetReferencesForProcessingRun() As String()
    
                '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", Me.GetType().Assembly.Location}
            End Function
    
    
            Public Overrides Function GetImportsForProcessingRun() As String()
    
                '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"}
            End Function
        End Class 'CustomDirectiveProcessor
    
    
        '--------------------------------------------------------------------------
        ' the code that we are adding to the generated transformation class 
        ' will call this method
        '--------------------------------------------------------------------------
        Public Class XmlReaderHelper
    
            Public Shared Function ReadXml(ByVal fileName As String) As XmlDocument
    
                Dim d As XmlDocument = New XmlDocument()
    
                Using reader As XmlTextReader = New XmlTextReader(fileName)
    
                    Try
                        d.Load(reader)
    
                    Catch e As System.Xml.XmlException
    
                        Throw New DirectiveProcessorException("Unable to read the XML file.", e)
                    End Try
                End Using
    
                Return d
            End Function
        End Class 'XmlReaderHelper
    
    End Namespace
    
  10. For Visual Basic only, open the Project menu, and click CustomDP Properties. On the Application tab, in Root namespace, delete the default value, CustomDP.

  11. On the File menu, click Save All.

  12. On the Build menu, click Build Solution.

Before you can call a directive from a text template in Visual Studio, you must add a key for the directive processor in the registry.

NoteNote

If you use the command line tool to transform a text template that calls a custom directive, you do not need to add a key for the directive processor to the registry. For more information, see Command-Line Tools for Text Templates.

Keys for directive processors that Domain-Specific Language Tools uses already exist in the registry in the following location:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TextTemplating\DirectiveProcessors

In this section, you add a key for your custom directive processor to the registry in the same location.

Caution noteCaution

Incorrectly editing the registry can severely damage your system. Before you making changes to the registry, back up any valued data on the computer.

To add a registry key for the directive processor

  1. On the Start menu, click Run.

  2. In the Run dialog box, type regedit, and click OK.

    The Registry Editor appears.

  3. Browse to the location HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TextTemplating\DirectiveProcessors, and click the node.

  4. On the Edit menu, point to New, and then click Key.

  5. Type CustomDirectiveProcessor for the name of the new key.

    NoteNote

    You can choose any name that you want for this key. This name does not need to match the name of the directive, the name of the directive processor class, or the directive processor namespace.

  6. Right-click the CustomDirectiveProcessor key, point to New, and then click String Value.

  7. Type Class for the name of the new string.

  8. Right-click Class, and click Modify.

  9. In the Edit String dialog box, in Value data, type CustomDP.CustomDirectiveProcessor, and click OK.

    NoteNote

    This string is the namespace and the class name of your custom directive processor.

  10. Right-click the CustomDirectiveProcessor key, point to New, and then click String Value.

  11. Type CodeBase for the name of the new string.

  12. Right-click CodeBase, and click Modify.

  13. In the Edit String dialog box, in Value data, type the path of the CustomDP.dll that you created earlier in this walkthrough. For example, the path might look like C:\UserFiles\CustomDP\bin\Debug\CustomDP.dll.

    Your registry key should have the following values:

    Name Type Data

    (Default)

    REG_SZ

    (value not set)

    Class

    REG_SZ

    CustomDP.CustomDirectiveProcessor

    CodeBase

    REG_SZ

    <Your Path>CustomDP\bin\Debug\CustomDP.dll

  14. Close the Registry Editor.

To test the directive processor, you write a text template that calls it. The text template calls the directive and passes in the name of an XML file that contains documentation for a class file. For more information, see XML Documentation Comments (C# Programming Guide).

The text template then uses the XmlDocument property that the directive creates to navigate the XML and print the documentation comments.

To create an XML file for use in testing the directive processor

  1. Create a text file named DocFile.xml by using any text editor (for example, Notepad).

    Note   You can create this file in any location (for example, C:\Test\DocFile.xml).

  2. Add the following to the text file:

    <?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. Save and close the file.

To create a text template to test the directive processor

  1. Open a new instance of Visual Studio.

  2. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.

  3. Under Project types, click the Visual Basic or Visual C# node, according to your preference.

    NoteNote

    The language of the text template does not need to match the language of the directive processor.

  4. Under Visual Studio installed templates, click Class Library.

  5. In Name, type TemplateTest.

  6. Select the Create directory for solution check box, and click OK.

    A class library project is created and opens.

  7. On the Project menu, click Add New Item.

  8. Under Visual Studio installed templates, click Text File.

  9. In Name, type TestDP.txt, and then click Add.

  10. In Solution Explorer, click TestDP.txt.

    Caution noteCaution

    When you add the text file to the project, it will be highlighted in Solution Explorer but might not be selected. If the file is not selected, the following step will not work.

  11. On the View menu, click Properties Window.

  12. In the Custom Tool property, type TextTemplatingFileGenerator.

  13. In Solution Explorer, double-click TestDP.txt to open it in the editor.

  14. Add the following code to TestDP.txt:

    NoteNote

    The language of the text template does not need to match the language of the directive processor.

    <#@ 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");
    
        //...
    #>
    

    <#@ assembly name="System.Xml" #>
    <#@ template debug="true" language="vb" #>
    <#@ 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. #>
    <#
        Dim node as XmlNode = Document0.DocumentElement.SelectSingleNode("members")
    
        Dim member As XmlNode
        For Each member In node.ChildNodes
    
            Dim name As XmlNode = member.Attributes.GetNamedItem("name")
            WriteLine("{0,7}:  {1}", "Name", name.Value)
    
            Dim comment As XmlNode
            For Each comment In member.ChildNodes
                WriteLine("{0,7}:  {1}", comment.Name, comment.InnerText)
            Next
    
            WriteLine("")
        Next
    #>
    
    <#  'You can call the directive processor again and pass it a different file. #>
    <# '@ CoolDirective Processor="CustomDirectiveProcessor" FileName="<YOUR PATH>\DocFileTwo.xml" #>
    
    <#  'To use the results of the second directive call, use Document1. #>
    <#
        'node = Document1.DocumentElement.SelectSingleNode("members")
    
        '...
    #>
    
    NoteNote

    In this example, the value of the Processor parameter is CustomDirectiveProcessor. The value of the Processor parameter must match the name of the processor's registry key.

  15. In the code, replace <YOUR PATH> with the path of the DocFile.xml file that you created earlier in this walkthrough.

  16. On the File menu, click Save All.

To test the directive processor

  1. In the second instance of Visual Studio, in Solution Explorer, right-click TestDP.txt, and then click Run Custom Tool.

    For Visual Basic users, TestDP.txt might not appear in Solution Explorer by default. To display all files assigned to the project, open the Project menu, and click Show All Files

  2. In Solution Explorer, expand the TestDP.txt node, and then double-click TestDP1.txt to open it in the editor.

    The generated text output appears. The output should look like the following:

       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
    

After you test your custom directive processor, you might want to add some HTML to your generated text.

To add HTML to the generated text

  1. Replace the code in TestDP.txt with the following. The HTML is highlighted.

    NoteNote

    Additional open <# and close #> tags separate the statement code from the HTML tags.

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

    <#@ assembly name="System.Xml" #>
    <#@ template debug="true" language="vb" #>
    <#@ 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#>
    <#
        Dim node as XmlNode = Document0.DocumentElement.SelectSingleNode("members")
    
        Dim member As XmlNode
        For Each member In node.ChildNodes
    #>
    <h3>
    <#    
            Dim name As XmlNode = member.Attributes.GetNamedItem("name")
            WriteLine("{0,7}:  {1}", "Name", name.Value)
    #>
    </h3>
    <#
            Dim comment As XmlNode
            For Each comment In member.ChildNodes
                WriteLine("{0,7}:  {1}", comment.Name, comment.InnerText)
    #>
    <br/>
    <#
            Next
        Next
    #>
    </body>
    </html>
    
  2. In the code, replace <YOUR PATH> with the path of the DocFile.xml file that you created earlier in this walkthrough.

  3. On the File menu, click Save TestDP.txt.

  4. To view the output in a browser, in Solution Explorer, right-click TestDP.htm, and click View In Browser.

    Your output should be the same as the original text but with HTML format applied. Each item name should appear in bold.

For more information, see Security of Text Templates.

Show:
© 2016 Microsoft