Criar processadores de diretiva de modelo de texto T4 personalizados

O processo de transformação do modelo de texto usa um arquivo de modelo de texto como entrada e produz um arquivo de texto como saída. O mecanismo de transformação de modelo de texto controla o processo e o mecanismo interage com um host de transformação de modelo de texto e um ou mais processadores de diretiva de modelo de texto para concluir o processo. Para obter mais informações, consulte O processo de transformação do modelo de texto.

Para criar um processador de diretiva personalizado, crie uma classe que herda de uma das classes DirectiveProcessor ou RequiresProvidesDirectiveProcessor.

A diferença entre esses dois é que DirectiveProcessor implementa a interface mínima necessária para obter parâmetros do usuário e gerar o código que produz o arquivo de saída do modelo. RequiresProvidesDirectiveProcessor implementa o padrão de design requer/fornece. RequiresProvidesDirectiveProcessor lida com dois parâmetros requires especiais e provides. Por exemplo, um processador de diretriz personalizado pode aceitar um nome de arquivo do usuário, abrir e ler o arquivo e, em seguida, armazenar o texto do arquivo em uma variável chamada fileText. Uma subclasse da classe RequiresProvidesDirectiveProcessor pode tomar um nome de ficheiro do usuário como o valor do parâmetro requires e o nome da variável na qual armazenar o texto como o valor do parâmetro provides. Este processador abriria e leria o arquivo e, em seguida, armazenaria o texto do arquivo na variável especificada.

Antes de chamar um processador de diretiva personalizado de um modelo de texto no Visual Studio, você deve registrá-lo.

Para obter mais informações sobre como adicionar a chave do Registro, consulte Implantando um processador de diretiva personalizada.

Diretivas aduaneiras

Uma diretiva personalizada tem esta aparência:

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

Você pode usar um processador de diretriz personalizado quando quiser acessar dados ou recursos externos a partir de um modelo de texto.

Diferentes modelos de texto podem compartilhar a funcionalidade que um único processador de diretiva fornece, portanto, os processadores de diretiva fornecem uma maneira de fatorar o código para reutilização. A diretiva integrada include é semelhante, porque pode ser usada para fatorar o código e partilhá-lo entre diferentes modelos de texto. A diferença é que qualquer funcionalidade que a include diretiva fornece é fixa e não aceita parâmetros. Se quiser fornecer funcionalidade comum a um modelo de texto e permitir que o modelo passe parâmetros, você deve criar um processador de diretiva personalizado.

Alguns exemplos de processadores de diretriz personalizados podem ser:

• Um processador de diretriz para retornar dados de um banco de dados que aceita um nome de usuário e senha como parâmetros.

• Um processador de diretriz para abrir e ler um arquivo que aceita o nome do arquivo como parâmetro.

Partes principais de um processador de diretriz personalizado

Para desenvolver um processador de diretrizes, deve criar uma classe que herda de DirectiveProcessor ou RequiresProvidesDirectiveProcessor.

Os métodos mais importantes DirectiveProcessor que você deve implementar são os seguintes.

• bool IsDirectiveSupported(string directiveName) - Retorne true se o seu processador de diretiva puder processar a diretiva nomeada.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - O mecanismo de modelo chama esse método para cada ocorrência de uma diretiva no modelo. O processador deve salvar os resultados.

Depois de todas as chamadas para ProcessDirective(), o mecanismo de modelagem chamará estes métodos:

• string[] GetReferencesForProcessingRun() - Retornar os nomes dos assemblies que o código do modelo exige.

• string[] GetImportsForProcessingRun() - Retornar os namespaces que podem ser usados no código do modelo.

• string GetClassCodeForProcessingRun() - Retornar o código de métodos, propriedades e outras declarações que o código do modelo pode usar. A maneira mais fácil de fazer isso é criar uma cadeia de caracteres contendo o código C# ou Visual Basic. Para tornar seu processador de diretriz capaz de ser chamado a partir de um modelo que usa qualquer linguagem CLR, você pode construir as instruções como uma árvore CodeDom e, em seguida, retornar o resultado da serialização da árvore na linguagem usada pelo modelo.

• Para obter mais informações, consulte Passo a passo: Criando um processador de diretiva personalizada.

Conteúdo relacionado

• Implantar um processador de diretiva personalizada explica como registrar um processador de diretiva personalizado.
• Passo a passo: Criar um processador de diretiva personalizada descreve como criar um processador de diretiva personalizado, como registrar e testar o processador de diretiva e como formatar o arquivo de saída como HTML.