Aangepaste richtlijnprocessors voor T4-tekstsjablonen maken

Het transformatieproces van de tekstsjabloon neemt een tekstbestand als invoer en produceert een tekstbestand als uitvoer. De transformatie-engine voor tekstsjablonen bepaalt het proces en de engine communiceert met een transformatiehost voor tekstsjablonen en een of meer tekstsjabloonrichtlijnprocessors om het proces te voltooien. Zie Het transformatieproces van de tekstsjabloon voor meer informatie.

Als u een aangepaste instructieprocessor wilt maken, maakt u een klasse die erft van DirectiveProcessor of RequiresProvidesDirectiveProcessor.

Het verschil tussen deze twee is dat DirectiveProcessor de minimale interface implementeert die nodig is om parameters van de gebruiker op te halen en om de code te genereren die het uitvoerbestand van de sjabloon produceert. RequiresProvidesDirectiveProcessor implementeert het ontwerpprincipe 'vereisten/voorzieningen'. RequiresProvidesDirectiveProcessor verwerkt twee speciale parameters en requiresprovides. Een aangepaste instructieprocessor kan bijvoorbeeld een bestandsnaam van de gebruiker accepteren, het bestand openen en lezen en vervolgens de tekst van het bestand opslaan in een variabele met de naam fileText. Een subklasse van de RequiresProvidesDirectiveProcessor klasse kan een bestandsnaam van de gebruiker aannemen als de waarde van de requires parameter en de naam van de variabele waarin de tekst moet worden opgeslagen als de waarde van de provides parameter. Deze processor zou het bestand openen en lezen en vervolgens de tekst van het bestand opslaan in de opgegeven variabele.

Voordat u een aangepaste instructieprocessor aanroept vanuit een tekstsjabloon in Visual Studio, moet u deze registreren.

Zie Een aangepaste richtlijnprocessor implementeren voor meer informatie over het toevoegen van de registersleutel.

Aangepaste richtlijnen

Een aangepaste richtlijn ziet er als volgt uit:

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

U kunt een aangepaste instructieprocessor gebruiken wanneer u toegang wilt krijgen tot externe gegevens of resources vanuit een tekstsjabloon.

Verschillende tekstsjablonen kunnen de functionaliteit delen die een enkele richtlijnprocessor biedt, zodat richtlijnprocessors een manier bieden om code te factoreren voor hergebruik. De ingebouwde include instructie is vergelijkbaar, omdat u deze kunt gebruiken om code uit te factoren en deze te delen tussen verschillende tekstsjablonen. Het verschil is dat alle functionaliteit die de include richtlijn biedt, is vast en accepteert geen parameters. Als u algemene functionaliteit wilt bieden aan een tekstsjabloon en de sjabloon wilt toestaan parameters door te geven, moet u een aangepaste instructieprocessor maken.

Enkele voorbeelden van aangepaste richtlijnverwerkers kunnen zijn:

• Een richtlijnprocessor voor het retourneren van gegevens uit een database die een gebruikersnaam en wachtwoord accepteert als parameters.

• Een instructieprocessor voor het openen en lezen van een bestand dat de naam van het bestand als parameter accepteert.

Belangrijkste onderdelen van een aangepaste richtlijnverwerker

Als u een richtlijnprocessor wilt ontwikkelen, moet u een klasse maken die erft van DirectiveProcessor of RequiresProvidesDirectiveProcessor.

De belangrijkste DirectiveProcessor methoden die u moet implementeren, zijn als volgt.

• bool IsDirectiveSupported(string directiveName) - Retourneer true als uw richtlijnprocessor de benoemde richtlijn kan verwerken.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - De sjabloonengine roept deze methode aan voor elke keer dat een directive in de sjabloon voorkomt. Uw processor moet de resultaten opslaan.

Na alle aanroepen naar ProcessDirective() roept de templating-engine deze methoden aan:

• string[] GetReferencesForProcessingRun() - Retourneer de namen van assembly's die de sjablooncode nodig heeft.

• string[] GetImportsForProcessingRun() - Retourneer de naamruimten die kunnen worden gebruikt in de sjablooncode.

• string GetClassCodeForProcessingRun() - Retourneer de code van methoden, eigenschappen en andere declaraties die de sjablooncode kan gebruiken. De eenvoudigste manier om dit te doen, is door een tekenreeks te bouwen die de C# of Visual Basic-code bevat. Als u wilt dat uw instructieprocessor kan worden aangeroepen vanuit een sjabloon die gebruikmaakt van een CLR-taal, kunt u de instructies samenstellen als een CodeDom-structuur en vervolgens het resultaat retourneren van het serialiseren van de structuur in de taal die door de sjabloon wordt gebruikt.

• Zie Walkthrough: Een aangepaste richtlijnprocessor maken voor meer informatie.

Verwante inhoud

• Een aangepaste richtlijnprocessor implementeren legt uit hoe u een aangepaste richtlijnprocessor registreert.
• Overzicht: Een aangepaste richtlijnprocessor maken beschrijft hoe u een aangepaste instructieprocessor maakt, hoe u de instructieprocessor registreert en test en hoe u het uitvoerbestand opmaken als HTML.