Creare processori di direttiva di modelli di testo T4 personalizzati

Il processo di trasformazione modello di testo accetta un file modello di testo come input e produce un file di testo come output. Il motore di trasformazione modello di testo controlla il processo e il motore interagisce con un host di trasformazione modello di testo e uno o più processori di direttiva modello di testo per completare il processo. Per altre informazioni, vedere Processo di trasformazione Modello di testo.

Per creare un processore di direttiva personalizzato, si crea una classe che eredita da DirectiveProcessor o RequiresProvidesDirectiveProcessor.

La differenza tra questi due è che DirectiveProcessor implementa l'interfaccia minima necessaria per ottenere i parametri dall'utente e per generare il codice che produce il file di output del modello. RequiresProvidesDirectiveProcessor implementa il modello di progettazione richiesto/fornisce. RequiresProvidesDirectiveProcessor gestisce due parametri speciali e requires provides. Ad esempio, un processore di direttive personalizzato potrebbe accettare un nome di file dall'utente, aprire e leggere il file e quindi archiviare il testo del file in una variabile denominata fileText. Una sottoclasse della RequiresProvidesDirectiveProcessor classe può accettare un nome di file dall'utente come valore del requires parametro e il nome della variabile in cui archiviare il testo come valore del provides parametro. Questo processore apre e legge il file e quindi archivia il testo del file nella variabile specificata.

Prima di chiamare un processore di direttiva personalizzato da un modello di testo in Visual Studio, è necessario registrarlo.

Per altre informazioni su come aggiungere la chiave del Registro di sistema, vedere Distribuzione di un processore di direttive personalizzato.

Direttive personalizzate

Una direttiva personalizzata è simile alla seguente:

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

È possibile usare un processore di direttiva personalizzato quando si desidera accedere a dati o risorse esterne da un modello di testo.

Modelli di testo diversi possono condividere la funzionalità fornita da un singolo processore di direttiva, quindi i processori di direttiva forniscono un modo per considerare il codice per il riutilizzo. La direttiva predefinita include è simile, perché è possibile usarla per escludere il codice e condividerlo tra modelli di testo diversi. La differenza è che qualsiasi funzionalità fornita dalla include direttiva è fissa e non accetta parametri. Se si desidera fornire funzionalità comuni a un modello di testo e consentire al modello di passare parametri, è necessario creare un processore di direttiva personalizzato.

Alcuni esempi di processori di direttiva personalizzati possono essere:

• Responsabile del trattamento delle direttive per restituire dati da un database che accetta un nome utente e una password come parametri.

• Processore di direttiva per aprire e leggere un file che accetta il nome del file come parametro.

Parti principali di un processore di direttive personalizzato

Per sviluppare un processore di direttiva, è necessario creare una classe che eredita da DirectiveProcessor o RequiresProvidesDirectiveProcessor.

I metodi più importanti DirectiveProcessor da implementare sono i seguenti.

• bool IsDirectiveSupported(string directiveName) - Restituisce true se il processore di direttiva può gestire la direttiva denominata.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - Il motore di modelli chiama questo metodo per ogni occorrenza di una direttiva nel modello. Il processore deve salvare i risultati.

Dopo tutte le chiamate a ProcessDirective() il motore di creazione modelli chiamerà questi metodi:

• string[] GetReferencesForProcessingRun() : restituisce i nomi degli assembly richiesti dal codice del modello.

• string[] GetImportsForProcessingRun() : restituisce gli spazi dei nomi che possono essere usati nel codice del modello.

• string GetClassCodeForProcessingRun() : restituisce il codice di metodi, proprietà e altre dichiarazioni che il codice del modello può usare. Il modo più semplice per eseguire questa operazione consiste nel compilare una stringa contenente il codice C# o Visual Basic. Per rendere il processore di direttiva in grado di essere chiamato da un modello che usa qualsiasi linguaggio CLR, è possibile costruire le istruzioni come albero CodeDom e quindi restituire il risultato della serializzazione dell'albero nel linguaggio usato dal modello.

• Per altre informazioni, vedere Procedura dettagliata: Creazione di un processore di direttiva personalizzato.

Contenuto correlato

• Distribuire un processore di direttiva personalizzato spiega come registrare un processore di direttiva personalizzato.
• Procedura dettagliata: creare un processore di direttiva personalizzato descrive come creare un processore di direttiva personalizzato, come registrare e testare il processore di direttiva e come formattare il file di output come HTML.