Skapa anpassade T4-textmallsdirektivprocessorer

Omvandlingsprocessen för textmallen tar en textmallfil som indata och skapar en textfil som utdata. Omvandlingsmotorn för textmallen styr processen, och motorn interagerar med en värd för textmallstransformation och en eller flera direktivprocessorer för textmallar för att slutföra processen. Mer information finns i Omvandlingsprocessen för textmallar.

Om du vill skapa en processor för anpassat direktiv skapar du en klass som ärver från antingen DirectiveProcessor eller RequiresProvidesDirectiveProcessor.

Skillnaden mellan dessa två är att DirectiveProcessor implementera det minsta gränssnitt som krävs för att hämta parametrar från användaren och generera koden som skapar mallens utdatafil. RequiresProvidesDirectiveProcessor implementerar designmönstret kräver/erbjuder. RequiresProvidesDirectiveProcessor hanterar två särskilda parametrar och requiresprovides. En processor för anpassat direktiv kan till exempel acceptera ett filnamn från användaren, öppna och läsa filen och sedan lagra texten i filen i en variabel med namnet fileText. En underklass av RequiresProvidesDirectiveProcessor klassen kan ta ett filnamn från användaren som värdet för parametern requires och namnet på variabeln där texten ska lagras som värdet för parametern provides . Den här processorn öppnar och läser filen och lagrar sedan filens text i den angivna variabeln.

Innan du anropar en processor för anpassat direktiv från en textmall i Visual Studio måste du registrera den.

Mer information om hur du lägger till registernyckeln finns i Implementera en anpassad direktivprocessor.

Anpassade direktiv

Ett anpassat direktiv ser ut så här:

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

Du kan använda en processor för anpassade direktiv när du vill komma åt externa data eller resurser från en textmall.

Olika textmallar kan dela de funktioner som en enda direktivprocessor tillhandahåller, så direktivprocessorer ger ett sätt att faktorkoda för återanvändning. Det inbyggda include direktivet liknar det, eftersom du kan använda det för att räkna ut kod och dela det mellan olika textmallar. Skillnaden är att alla funktioner som include direktivet tillhandahåller är fasta och inte accepterar parametrar. Om du vill tillhandahålla vanliga funktioner för en textmall och tillåta att mallen skickar parametrar måste du skapa en anpassad direktivprocessor.

Några exempel på anpassade direktivprocessorer kan vara:

• En direktivprocessor som returnerar data från en databas som accepterar ett användarnamn och lösenord som parametrar.

• En direktivprocessor som öppnar och läser en fil som accepterar namnet på filen som en parameter.

Huvuddelar i en anpassad direktivprocessor

Om du vill utveckla en direktivprocessor måste du skapa en klass som ärver från antingen DirectiveProcessor eller RequiresProvidesDirectiveProcessor.

De viktigaste DirectiveProcessor metoderna som du måste implementera är följande.

• bool IsDirectiveSupported(string directiveName) - Returnera true om din direktivprocessor kan hantera det namngivna direktivet.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) – Mallmotorn anropar den här metoden för varje förekomst av ett direktiv i mallen. Processorn bör spara resultatet.

När alla anrop till ProcessDirective() har bearbetats kommer mallmotorn att anropa följande metoder:

• string[] GetReferencesForProcessingRun() – Returnera namnen på sammansättningar som mallkoden kräver.

• string[] GetImportsForProcessingRun() – Returnera de namnområden som kan användas i mallkoden.

• string GetClassCodeForProcessingRun() – Returnera koden för metoder, egenskaper och andra deklarationer som mallkoden kan använda. Det enklaste sättet att göra detta är att skapa en sträng som innehåller C# eller Visual Basic-koden. För att göra direktivprocessorn kapabel att anropas från en mall som använder valfritt CLR-språk kan du konstruera uttrycken som ett CodeDom-träd och sedan returnera resultatet av serialiseringen av trädet på det språk som används av mallen.

• Mer information finns i Genomgång: Skapa en anpassad direktivprocessor.

Relaterat innehåll

• Distribuera en anpassad direktivprocessor förklarar hur du registrerar en anpassad direktivprocessor.
• Genomgång: Skapa en processor för anpassat direktiv beskriver hur du skapar en processor för anpassat direktiv, hur du registrerar och testar direktivprocessorn och hur du formaterar utdatafilen som HTML.