Exemplarische Vorgehensweise: Erstellen eines benutzerdefinierten Direktivenprozessors

Artikel
07/20/2011

Direktivenprozessoren fügen der generierten Transformationsklasse Code hinzu. Wenn Sie eine Direktive in einer Textvorlage aufrufen, kann der Rest des Codes, den Sie in der Textvorlage schreiben, auf der von der Direktive bereitgestellten Funktion basieren.

Sie können eigene benutzerdefinierte Direktivenprozessoren schreiben. Dies ermöglicht Ihnen das Anpassen der Textvorlagen. Zum Erstellen eines benutzerdefinierten Direktivenprozessors erstellen Sie eine Klasse, die von DirectiveProcessor oder RequiresProvidesDirectiveProcessor erbt.

In dieser exemplarischen Vorgehensweise werden u. a. die folgenden Aufgaben beschrieben:

Erstellen eines benutzerdefinierten Direktivenprozessors
Registrieren des Direktivenprozessors
Testen des Direktivenprozessors

Vorbereitungsmaßnahmen

Um die exemplarische Vorgehensweise nachzuvollziehen, benötigen Sie Folgendes:

Visual Studio 2010
Visual Studio 2010 SDK

Erstellen eines benutzerdefinierten Direktivenprozessors

In dieser exemplarischen Vorgehensweise erstellen Sie einen benutzerdefinierten Direktivenprozessor. Sie fügen eine benutzerdefinierte Direktive hinzu, von der eine XML-Datei gelesen, in einer XmlDocument-Variable gespeichert und durch eine Eigenschaft verfügbar gemacht wird. Im Abschnitt "Testen des Direktivenprozessors" verwenden Sie diese Eigenschaft in einer Textvorlage, um auf die XML-Datei zuzugreifen.

Der Aufruf der benutzerdefinierten Direktive sieht folgendermaßen aus:

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

Der benutzerdefinierte Direktivenprozessor fügt die Variable und die Eigenschaft der generierten Transformationsklasse hinzu. In der Direktive, die Sie hier erstellen, wird der vom Modul zur generierten Transformationsklasse hinzugefügte Code mithilfe von System.CodeDom-Klassen erstellt. Die System.CodeDom-Klassen erstellen abhängig von der im language-Parameter der template-Direktive angegebenen Sprache Code in Visual C# oder Visual Basic. Die Sprache des Direktivenprozessors und die Sprache der Textvorlage, die auf den Direktivenprozessor zugreift, müssen nicht identisch sein.

Der von der Direktive erstellte Code sieht folgendermaßen aus:

private System.Xml.XmlDocument document0Value;

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

Private document0Value As System.Xml.XmlDocument

Public Overridable ReadOnly Property Document0() As System.Xml.XmlDocument
    Get
        If (Me.document0Value Is Nothing) Then
            Me.document0Value = XmlReaderHelper.ReadXml(<FileNameParameterValue>)
        End If
        Return Me.document0Value
    End Get
End Property

So erstellen Sie einen benutzerdefinierten Direktivenprozessor

Erstellen Sie in Visual Studio ein Visual C#- oder Visual Basic-Klassenbibliothekprojekt mit dem Namen "CustomDP".

Tipp

Wenn Sie den Direktivenprozessor auf mehreren Computern installieren möchten, empfiehlt es sich, ein Visual Studio-Erweiterungsprojekt (VSIX) zu verwenden und eine PKGDEF-Datei in die Erweiterung einzuschließen. Weitere Informationen finden Sie unter Bereitstellen eines benutzerdefinierten Direktivenprozessors.
Fügen Sie Verweise auf die folgenden Assemblys hinzu:
- Microsoft.VisualStudio.TextTemplating.10.0
- Microsoft.VisualStudio.TextTemplating.Interfaces.10.0

Ersetzen Sie den Code in Class1 durch den folgenden Code. Dieser Code definiert eine CustomDirectiveProcessor-Klasse, die von der DirectiveProcessor-Klasse erbt und die erforderlichen Methoden implementiert.

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

Öffnen Sie im Fall eines Visual Basic-Projekts das Menü Projekt, und klicken Sie auf CustomDP-Eigenschaften. Löschen Sie auf der Registerkarte Anwendung in Stammnamespace den Standardwert CustomDP.
Klicken Sie im Menü Datei auf Alle speichern.
Klicken Sie im Menü Erstellen auf Projektmappe erstellen.

Erstellen des Projekts

Erstellen Sie das Projekt. Klicken Sie im Menü Erstellen auf Projektmappe erstellen.

Registrieren des Direktivenprozessors

Bevor Sie in Visual Studio eine Direktive in einer Textvorlage aufrufen können, müssen Sie einen Registrierungsschlüssel für den Direktivenprozessor hinzufügen.

Tipp

Wenn Sie den Direktivenprozessor auf mehreren Computern installieren möchten, empfiehlt es sich, eine Visual Studio-Erweiterung (VSIX) zu definieren, die eine PKGDEF-Datei und die Assembly enthält. Weitere Informationen finden Sie unter Bereitstellen eines benutzerdefinierten Direktivenprozessors.

Schlüssel für Direktivenprozessoren befinden sich unter folgendem Pfad in der Registrierung:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors

Für 64-Bit-Systeme wird der folgende Registrierungsort verwendet:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors

In diesem Abschnitt fügen Sie der Registrierung unter demselben Pfad einen Schlüssel für den benutzerdefinierten Direktivenprozessor hinzu.

Warnung

Durch eine fehlerhafte Bearbeitung der Registrierung kann das System ernsthaft beschädigt werden. Sichern Sie alle wichtigen Daten auf dem Computer, bevor Sie Änderungen an der Registrierung vornehmen.

So fügen Sie einen Registrierungsschlüssel für den Direktivenprozessor hinzu

Führen Sie den regedit-Befehl über das Menü "Start" oder die Befehlszeile aus.
Navigieren Sie zum Pfad HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors, und klicken Sie auf den Knoten.

Verwenden Sie bei 64-Bit-Systemen HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors
Fügen Sie einen neuen Schlüssel mit dem Namen "CustomDirectiveProcessor" hinzu.

Tipp

Diesen Namen verwenden Sie im Feld "Prozessor" der benutzerdefinierten Direktiven. Dieser Name muss nicht mit dem Namen der Direktive, dem Namen der Direktivenprozessorklasse oder des Direktivenprozessornamespaces übereinstimmen.
Fügen Sie einen neuen Zeichenfolgenwert mit dem Namen "Class" und dem Wert CustomDP.CustomDirectiveProcessor für den Namen der neuen Zeichenfolge hinzu.
Fügen Sie einen neuen Zeichenfolgenwert mit dem Namen "CodeBase" hinzu, dessen Wert dem Pfad der zuvor in dieser exemplarischen Vorgehensweise erstellten CustomDP.dll entspricht.

Der Pfad kann z. B. C:\UserFiles\CustomDP\bin\Debug\CustomDP.dll lauten.

Folgende Werte müssen für den Registrierungsschlüssel festgelegt werden:

Name

Typ

Daten

(Standard)

REG_SZ

(Wert nicht festgelegt)

Klasse

REG_SZ

CustomDP.CustomDirectiveProcessor

CodeBase

REG_SZ

<Pfad zur Projektmappe>CustomDP\bin\Debug\CustomDP.dll

Wenn Sie die Assembly im GAC gespeichert haben, sollten die Werte wie folgt aussehen:

Name

Typ

Daten

(Standard)

REG_SZ

(Wert nicht festgelegt)

Klasse

REG_SZ

CustomDP.CustomDirectiveProcessor

Assembly

REG_SZ

CustomDP.dll
Starten Sie Visual Studio neu.

Name	Typ	Daten
(Standard)	REG_SZ	(Wert nicht festgelegt)
Klasse	REG_SZ	CustomDP.CustomDirectiveProcessor
CodeBase	REG_SZ	<Pfad zur Projektmappe>CustomDP\bin\Debug\CustomDP.dll

Name	Typ	Daten
(Standard)	REG_SZ	(Wert nicht festgelegt)
Klasse	REG_SZ	CustomDP.CustomDirectiveProcessor
Assembly	REG_SZ	CustomDP.dll

Testen des Direktivenprozessors

Zum Testen des Direktivenprozessors müssen Sie eine Textvorlage erstellen, in der der Prozessor aufgerufen wird.

In diesem Beispiel ruft die Textvorlage die Direktive auf und übergibt im Namen eine XML-Datei, die Dokumentation für eine Klassendatei enthält. Weitere Informationen finden Sie unter XML-Dokumentationskommentare (C#-Programmierhandbuch).

Anschließend wird in der Textvorlage die von der Direktive erstellte XmlDocument-Eigenschaft verwendet, um in der XML-Datei zu navigieren und die Dokumentationskommentare auszugeben.

So erstellen Sie eine XML-Datei zum Testen des Direktivenprozessors

Erstellen Sie mit einem Text-Editor (z. B. Editor) eine Textdatei mit dem Namen DocFile.xml.

Tipp

Diese Datei kann an einem beliebigen Speicherort erstellt werden (z. B. C:\Test\DocFile.xml).

Fügen Sie folgenden Text in der Textdatei ein:

<?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>

Speichern und schließen Sie die Datei.

So erstellen Sie eine Textvorlage zum Testen des Direktivenprozessors

Erstellen Sie in Visual Studio ein Visual C#- oder Visual Basic-Klassenbibliothekprojekt mit dem Namen "TemplateTest".
Fügen Sie eine neue Textvorlagendatei mit dem Namen "TestDP.tt" hinzu.
Vergewissern Sie sich, dass die Eigenschaft Benutzerdefiniertes Tool von "TestDP.tt" auf TextTemplatingFileGenerator festgelegt ist.

Ändern Sie den Inhalt von "TestDP.tt" in den folgenden Text.

Tipp

Ersetzen Sie die Zeichenfolge <YOUR PATH> durch den Pfad der Datei "DocFile.xml".

Die Sprache der Textvorlage muss nicht mit der Sprache des Direktivenprozessors identisch sein.

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

    '...
#>

Tipp

In diesem Beispiel ist der Wert des Processor-Parameters CustomDirectiveProcessor. Der Wert des Processor-Parameters muss dem Namen des Registrierungsschlüssels des Prozessors entsprechen.

Klicken Sie im Menü Datei auf Alle speichern.

So testen Sie den Direktivenprozessor

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf "TestDP.tt", und klicken Sie dann auf Benutzerdefiniertes Tool ausführen.

Für Visual Basic-Benutzer wird "TestDP.txt" möglicherweise nicht standardmäßig im Projektmappen-Explorer angezeigt. Klicken Sie zum Anzeigen aller zugewiesenen Dateien des Projekts im Menü Projekt auf Alle Dateien anzeigen.

Erweitern Sie im Projektmappen-Explorer den Knoten "TestDP.txt", und doppelklicken Sie dann auf "TestDP.txt", um die Datei im Editor zu öffnen.

Die generierte Textausgabe wird angezeigt. Die Ausgabe sollte wie folgt aussehen:

   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

Hinzufügen von HTML zum generierten Text

Nachdem Sie den benutzerdefinierten Direktivenprozessor getestet haben, können Sie dem generierten Text HTML hinzufügen.

So fügen Sie dem generierten Text HTML hinzu

Ersetzen Sie den Code in "TestDP.tt" durch den folgenden Code. Der HTML-Code ist hervorgehoben. Ersetzen Sie die Zeichenfolge YOUR PATH durch den Pfad der Datei "DocFile.xml".

Tipp

Zusätzliche <#-Starttags und #>-Endtags trennen den Anweisungscode von den 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>

Klicken Sie im Menü Datei auf TestDP.txt speichern.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf "TestDP.htm", und klicken Sie auf In Browser anzeigen, um die Ausgabe in einem Browser anzuzeigen.

Die Ausgabe sollte dem ursprünglichen Text entsprechen, jedoch HTML-formatiert sein. Jeder Elementname sollte fett formatiert sein.

Änderungsprotokoll

Datum	Versionsgeschichte	Grund
Juni 2010	Registrierungsort für 64-Bit-Systeme hinzugefügt.	Kundenfeedback.

Juni 2010

Registrierungsort für 64-Bit-Systeme hinzugefügt.

Kundenfeedback.

Freigeben über

Exemplarische Vorgehensweise: Erstellen eines benutzerdefinierten Direktivenprozessors

Vorbereitungsmaßnahmen

Erstellen eines benutzerdefinierten Direktivenprozessors

So erstellen Sie einen benutzerdefinierten Direktivenprozessor

Erstellen des Projekts

Registrieren des Direktivenprozessors

So fügen Sie einen Registrierungsschlüssel für den Direktivenprozessor hinzu

Testen des Direktivenprozessors

So erstellen Sie eine XML-Datei zum Testen des Direktivenprozessors

So erstellen Sie eine Textvorlage zum Testen des Direktivenprozessors

So testen Sie den Direktivenprozessor

Hinzufügen von HTML zum generierten Text

So fügen Sie dem generierten Text HTML hinzu

Änderungsprotokoll

Zusätzliche Ressourcen