Erstellen von benutzerdefinierten T4-Textvorlagen-Direktivenprozessoren

Der Textvorlagentransformationsprozess verwendet eine Textvorlagendatei als Eingabe und erzeugt eine Textdatei als Ausgabe. Die Textvorlagentransformations-Engine steuert den Prozess, und die Engine interagiert mit einem Textvorlagentransformations-Host und einem oder mehreren Textvorlagenrichtlinien-Prozessoren, um den Prozess abzuschließen. Weitere Informationen finden Sie im Textvorlagentransformationsprozess.

Um einen benutzerdefinierten Direktivenprozessor zu erstellen, erstellen Sie eine Klasse, die entweder von DirectiveProcessor oder von RequiresProvidesDirectiveProcessor erbt.

Der Unterschied zwischen diesen beiden besteht darin, dass DirectiveProcessor die Mindestschnittstelle implementiert, die erforderlich ist, um Parameter vom Benutzer abzurufen und um den Code zu generieren, der die Vorlagenausgabedatei erzeugt. RequiresProvidesDirectiveProcessor implementiert das "requires/provides"-Entwurfsmuster. RequiresProvidesDirectiveProcessor behandelt zwei spezielle Parameter requires und provides. Beispielsweise kann ein benutzerdefinierter Direktivenprozessor einen Dateinamen des Benutzers akzeptieren, die Datei öffnen und lesen und dann den Text der Datei in einer Variablen speichern, die den Namen hat fileText. Eine Unterklasse der RequiresProvidesDirectiveProcessor Klasse verwendet möglicherweise einen Dateinamen vom Benutzer als Wert des requires Parameters und den Namen der Variablen, in der der Text als Wert des provides Parameters gespeichert werden soll. Dieser Prozessor würde die Datei öffnen und lesen und dann den Text der Datei in der angegebenen Variablen speichern.

Bevor Sie einen benutzerdefinierten Direktivenprozessor aus einer Textvorlage in Visual Studio aufrufen, müssen Sie ihn registrieren.

Weitere Informationen zum Hinzufügen des Registrierungsschlüssels finden Sie unter Bereitstellen eines benutzerdefinierten Direktivenprozessors.

Benutzerdefinierte Direktiven

Eine benutzerdefinierte Direktive sieht wie folgt aus:

<#@ MyDirective Processor="MyDirectiveProcessor" parameter1="value1" ... #>

Sie können einen benutzerdefinierten Direktivenprozessor verwenden, wenn Sie über eine Textvorlage auf externe Daten oder Ressourcen zugreifen möchten.

Verschiedene Textvorlagen können die Von einem einzelnen Direktivenprozessor bereitgestellten Funktionen gemeinsam nutzen, sodass Direktivenprozessoren eine Möglichkeit zur Wiederverwendung von Code bereitstellen können. Die integrierte include-Direktive ist ähnlich, da Sie sie verwenden können, um Code aufzuteilen und zwischen verschiedenen Textvorlagen zu teilen. Der Unterschied besteht darin, dass jegliche Funktionalität, die die include Direktive bereitstellt, festgelegt ist und keine Parameter akzeptiert. Wenn Sie allgemeine Funktionen für eine Textvorlage bereitstellen und der Vorlage das Übergeben von Parametern erlauben möchten, müssen Sie einen benutzerdefinierten Direktivenprozessor erstellen.

Einige Beispiele für benutzerdefinierte Direktivenprozessoren könnten sein:

• Ein Direktivenverarbeiter, der Daten aus einer Datenbank zurückgibt, die einen Benutzernamen und ein Kennwort als Parameter akzeptiert.

• Ein Direktivenprozessor zum Öffnen und Lesen einer Datei, die den Namen der Datei als Parameter akzeptiert.

Hauptteile eines benutzerdefinierten Direktivenprozessors

Um einen Direktivenprozessor zu entwickeln, müssen Sie eine Klasse erstellen, die von einem DirectiveProcessor oder RequiresProvidesDirectiveProcessorbeiden erbt.

Die wichtigsten DirectiveProcessor Methoden, die Sie implementieren müssen, sind wie folgt.

• bool IsDirectiveSupported(string directiveName) – Gibt true zurück, wenn Ihr Direktivenverarbeiter die benannte Direktive verarbeiten kann.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - Das Vorlagenmodul ruft diese Methode für jedes Vorkommen einer Direktive in der Vorlage auf. Der Prozessor sollte die Ergebnisse speichern.

Nach allen Aufrufen von ProcessDirective() ruft das Vorlagenmodul die folgenden Methoden auf:

• string[] GetReferencesForProcessingRun() - Geben Sie die Namen von Assemblys zurück, die der Vorlagencode benötigt.

• string[] GetImportsForProcessingRun() - Gibt die Namespaces zurück, die im Vorlagencode verwendet werden können.

• string GetClassCodeForProcessingRun() - Gibt den Code von Methoden, Eigenschaften und anderen Deklarationen zurück, die der Vorlagencode verwenden kann. Am einfachsten erstellen Sie dazu eine Zeichenfolge, die den C#- oder Visual Basic-Code enthält. Damit Ihr Direktivenprozessor aus einer Vorlage aufgerufen werden kann, die eine beliebige CLR-Sprache verwendet, können Sie die Anweisungen als CodeDom-Struktur erstellen und dann das Ergebnis der Serialisierung der Struktur in der von der Vorlage verwendeten Sprache zurückgeben.

• Weitere Informationen finden Sie unter Schritt-für-Schritt-Anleitung: Erstellen eines benutzerdefinierten Direktivenprozessors.

Verwandte Inhalte

• Bereitstellen eines benutzerdefinierten Direktivenprozessors erläutert, wie ein benutzerdefinierter Direktivenprozessor registriert wird.
• Exemplarische Vorgehensweise: Erstellen eines benutzerdefinierten Direktivenprozessors beschreibt, wie ein benutzerdefinierter Direktivenprozessor erstellt wird, wie der Direktivenprozessor registriert und getestet wird und wie die Ausgabedatei als HTML formatiert wird.