Crie processadores de diretivas personalizados para modelos de texto T4

O processo de transformação de modelo de texto usa um arquivo de modelo de texto como entrada e produz 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 de Template de Texto.

Para criar um processador de diretiva personalizado, você cria uma classe que herda de um 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 requires/provides. RequiresProvidesDirectiveProcessor manipula dois parâmetros requires especiais e provides. Por exemplo, um processador de diretiva personalizado 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 RequiresProvidesDirectiveProcessor classe pode ter um nome de arquivo do usuário como o valor do requires parâmetro e o nome da variável na qual armazenar o texto como o valor do provides parâmetro. 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 personalizado.

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 externos ou recursos 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 separar e compartilhar o código entre diferentes modelos de texto. A diferença é que qualquer funcionalidade fornecida pela include diretiva é 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 personalizado

Para desenvolver um processador de diretiva, você 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 processador de diretivas puder lidar com a diretiva especificada.

• 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() - Retorne os nomes dos assemblies requeridos pelo código do modelo.

• 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 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 o 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 personalizado explica como registrar um processador de diretiva personalizado.
• Passo a passo: Criar um processador de diretiva personalizado descreve como criar um processador de diretiva personalizado, como registrar e testar o processador de diretivas e como formatar o arquivo de saída como HTML.