Criar processadores personalizados de diretiva de modelo de texto T4

O processo de transformação do modelo de texto usa um arquivo de modelo de texto como a entrada e gera um arquivo de texto como a 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 diretriz personalizado, é preciso criar uma classe herdada de DirectiveProcessor ou de 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 requires/provides. RequiresProvidesDirectiveProcessor manipula dois parâmetros especiais, requires e provides. Por exemplo, um processador de diretiva personalizada pode aceitar um nome de arquivo do usuário, abrir e ler o arquivo e armazenar o texto do arquivo em uma variável chamada fileText. Uma subclasse da classe RequiresProvidesDirectiveProcessor pode ter um nome de arquivo 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. Esse processador abriria e leria o arquivo e 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 personalizadas

Uma diretiva personalizada tem esta aparência:

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

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

Modelos de texto diferentes 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 interna include é semelhante, pois você pode usá-la para fatorar o código e compartilhá-lo entre diferentes modelos de texto. A diferença é que qualquer funcionalidade que a diretiva include fornece é fixa e não aceita parâmetros. Se você quiser fornecer uma funcionalidade comum a um modelo de texto e permitir que o modelo passe parâmetros, crie um processador de diretiva personalizado.

Alguns exemplos de processadores de diretiva personalizados podem ser:

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

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

Partes principais de um processador de diretiva personalizada

Para criar um processador de diretriz personalizado, é preciso criar uma classe herdada de DirectiveProcessor ou RequiresProvidesDirectiveProcessor.

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

• bool IsDirectiveSupported(string directiveName) - Retorna true se o processador de diretiva puder lidar com 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. Seu processador deve salvar os resultados.

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

• string[] GetReferencesForProcessingRun() – Retorna os nomes de assemblies que o código de modelo requer.

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

• string GetClassCodeForProcessingRun() – Retorna o código de métodos, propriedades e outras declarações que o código de 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 diretiva capaz de ser chamado 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 no idioma usado pelo modelo.

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

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.