Walkthrough: Creating a Custom Directive Processor
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at 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 your own custom directive processors. This enables you to customize your text templates. To create a custom directive processor, you create a class that inherits from either DirectiveProcessor or RequiresProvidesDirectiveProcessor.
Tasks that are illustrated in this walkthrough include the following:
Creating a custom directive processor
Registering the directive processor
Testing the directive processor
To complete this walkthrough, you will need:
Visual Studio 2010
Visual Studio 2010 SDK
In this walkthrough, you create a custom directive processor. You add a custom directive that reads an XML file, stores it in an XmlDocument variable, and exposes it through a property. In the section "Testing 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:
<#@ CoolDirective Processor="CustomDirectiveProcessor" FileName="<Your Path>DocFile.xml" #>
The custom directive processor adds the variable and the property 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. 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:
To create a custom directive processor
In Visual Studio, create a C# or a Visual Basic class library project named CustomDP.
Note If you want to install the directive processor on more than one computer, it is better to use a Visual Studio Extension (VSIX) project and include a .pkgdef file in the extension. For more information, see Deploying a Custom Directive Processor.
Add references to these assemblies:
Microsoft.VisualStudio.TextTemplating.*.0
Microsoft.VisualStudio.TextTemplating.Interfaces.*.0
Replace the code in Class1 with the following code. This code defines a CustomDirectiveProcessor class that inherits from the DirectiveProcessor class and implements the necessary methods.
For Visual Basic only, open the Project menu, and click CustomDP Properties. On the Application tab, in Root namespace, delete the default value,
CustomDP.On the File menu, click Save All.
On the Build menu, click Build Solution.
Build the Project
Build the project. On the Build menu, click Build Solution.
Before you can call a directive from a text template in Visual Studio, you must add a registry key for the directive processor.
If you want to install the directive processor on more than one computer, it is better to define a Visual Studio Extension (VSIX) that includes a .pkgdef file along with your assembly. For more information, see Deploying a Custom Directive Processor. |
Keys for directive processors exist in the registry in the following location:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors
For 64-bit systems, the registry location is:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors
In this section, you add a key for your custom directive processor to the registry in the same location.
Incorrectly editing the registry can severely damage your system. Before you make changes to the registry, back up any valuable data that is on the computer. |
To add a registry key for the directive processor
Run the
regeditcommand by using the Start menu or the command line.Browse to the location HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors, and click the node.
On 64-bit systems, use HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors
Add a new key named CustomDirectiveProcessor.
Note This is the name that you will use in the Processor field of your custom directives. This name does not need to match the name of the directive, the name of the directive processor class, or the directive processor namespace.
Add a new string value named Class that has a value CustomDP.CustomDirectiveProcessor for the name of the new string.
Add a new string value named CodeBase that has a value equal to 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 <Path to Your Solution>CustomDP\bin\Debug\CustomDP.dll If you have put the assembly in the GAC, the values should look like the following:
Name Type Data (Default) REG_SZ (value not set) Class REG_SZ CustomDP.CustomDirectiveProcessor Assembly REG_SZ CustomDP.dll Restart Visual Studio.
To test the directive processor, you need to write a text template that calls it.
In this example, 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.
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
Create a text file named
DocFile.xmlby using any text editor (for example, Notepad).
Note You can create this file in any location (for example, C:\Test\DocFile.xml).
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>Save and close the file.
To create a text template to test the directive processor
In Visual Studio, create a C# or Visual Basic class library project named TemplateTest.
Add a new text template file named TestDP.tt.
Make sure that the Custom Tool property of TestDP.tt is set to
TextTemplatingFileGenerator.Change the content of TestDP.tt to the following text.
Note Make sure to replace the string <
YOUR PATH>with the path to the DocFile.xml file.The language of the text template does not have to match the language of the directive processor.
Note In this example, the value of the
Processorparameter isCustomDirectiveProcessor. The value of theProcessorparameter must match the name of the processor's registry key.On the File menu, click Save All.
To test the directive processor
In Solution Explorer, right-click TestDP.tt 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.
In Solution Explorer, expand the TestDP.txt node, and then double-click TestDP.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
Replace the code in TestDP.tt with the following. The HTML is highlighted. Make sure to replace the string
YOUR PATHwith the path to the DocFile.xml file.
Note Additional open <# and close #> tags separate the statement code from the HTML tags.
On the File menu, click Save TestDP.txt.
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 except it should have the HTML format applied. Each item name should appear in bold.