Compartilhar via

Implantando um processador de diretiva personalizada

  • Artigo

Para usar um processador de diretiva personalizado no Visual Studio em qualquer computador, será necessário registrá-lo por um dos métodos descritos neste tópico.

Os métodos alternativos são:

  • Extensões do Visual Studio. Isso fornece uma maneira de instalar e desinstalar o processador de diretriz em seu próprio computador e em outros computadores. Normalmente, você pode empacotar outros recursos na mesma VSIX.

  • VSPackage. Se você estiver for definir um VSPackage que contém outros recursos além do processador de diretriz, há um método conveniente para registrar o processador de diretriz.

  • Definir uma chave do Registro. Nesse método, você adiciona uma entrada de Registro para o processador de diretriz.

Você precisará usar um desses métodos somente se quiser transformar o modelo de texto no Visual Studio ou no MSBuild. Se você usar um host personalizado em seu próprio aplicativo, seu host personalizado será responsável por localizar os processadores de diretrizes para cada diretiva.

Implantando um processador de diretriz em uma VSIX

Você pode adicionar um processador de diretiva personalizado a uma Extensão do Visual Studio (VSIX).

Você precisará certificar-se de que os dois seguintes itens estejam contidos no arquivo .vsix:

  • O assembly (.dll) que contém a classe do processador de diretriz personalizado.

  • Um arquivo .pkgdef que registra o processador de diretriz. O nome raiz do arquivo deve ser igual ao do assembly. Por exemplo, seus arquivos podem ser nomeados como CDP.dll e CDP.pkgdef.

Para inspecionar ou alterar o conteúdo de um arquivo .vsix, altere a extensão do seu nome de arquivo para .zip e abra-o. Depois de editar o conteúdo, altere o nome do arquivo de volta para .vsix.

Há várias maneiras de criar um arquivo .vsix. O procedimento a seguir descreve um método.

Para desenvolver um processador de diretriz personalizado em um projeto VSIX

  1. Criar um novo Projeto do VSIX.

  2. Em source.extension.vsixmanifest, defina o tipo de conteúdo e as edições com suporte.

    1. No editor de manifesto VSIX, na guia Ativos, escolha Novo e defina as propriedades do novo item:

      Tipo de Conteúdo = VsPackage

      Projeto de Origem = <o projeto atual>

    2. Clique em Edições Selecionadas e verifique os tipos de instalação para os quais você deseja que o processador de diretiva seja útil.

  3. Adicione um arquivo .pkgdef e defina suas propriedades para ser incluídas no VSIX.

    1. Crie um arquivo de texto e nomeie-o como <assemblyName>.pkgdef.

      <assemblyName> geralmente é igual ao nome do projeto.

    2. Selecione-o no Gerenciador de Soluções e defina suas propriedades da seguinte maneira:

      Ação de Compilação = Conteúdo

      Copiar para Diretório de Saída = Copiar Sempre

      Incluir no VSIX = Verdadeiro

    3. Defina o nome da VSIX e verifique se a ID é exclusiva.

  4. Adicione o seguinte texto ao arquivo .pkgdef.

    [$RootKey$\TextTemplating]
[$RootKey$\TextTemplating\DirectiveProcessors]
[$RootKey$\TextTemplating\DirectiveProcessors\ CustomDirectiveProcessorName]
@="Custom Directive Processor description"
"Class"="NamespaceName.ClassName"
"CodeBase"="$PackageFolder$\AssemblyName.dll"

    Substitua os seguintes nomes pelos seus próprios nomes: CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.

  5. Adicione as seguintes referências ao projeto:

    • Microsoft.VisualStudio.TextTemplating.*.0

    • Microsoft.VisualStudio.TextTemplating.Interfaces.*.0

    • Microsoft.VisualStudio.TextTemplating.VSHost.*.0

  6. Adicione sua classe de processador de diretriz personalizado ao projeto.

    Essa é uma classe pública que deve implementar DirectiveProcessor ou RequiresProvidesDirectiveProcessor.

Para instalar o Processador de Diretriz Personalizado

  1. No Windows Explorer, abra o diretório de build (geralmente bin\Debug ou bin\Release).

  2. Se você desejar instalar o processador de diretriz em outro computador, copie o arquivo .vsix para o outro computador.

  3. Clique duas vezes no arquivo .vsix. O instalador de extensões do Visual Studio é exibido.

  4. Reinicie o Visual Studio. Agora você poderá executar os modelos de texto que contêm diretivas que se referem ao processador de diretriz personalizado. Cada diretiva tem este formato:

    <#@ CustomDirective Processor="CustomDirectiveProcessorName" parameter1="value1" ... #>

Para desinstalar ou desabilitar temporariamente o processador de diretriz personalizado

  1. No menu Ferramentas do Visual Studio, clique em Gerenciador de Extensões.

  2. Selecione a VSIX que contém o processador de diretiva e clique em Desinstalar ou em Desabilitar.

Solução de problemas de um processador de diretriz em uma VSIX

Se o processador de diretriz não funcionar, as sugestões a seguir podem ajudar:

  • O nome do processador que você especifica na diretiva personalizada deve corresponder ao CustomDirectiveProcessorName que você especificou no arquivo .pkgdef.

  • O método IsDirectiveSupported deve retornar true quando o nome de seu CustomDirective é aprovado.

  • Se você não puder ver a extensão no Gerenciador de Extensões, mas o sistema não permitir que você instale-a, exclua a extensão de %localappdata%\Microsoft\VisualStudio\*.0\Extensions\.

  • Abra o arquivo .vsix e inspecione seu conteúdo. Para abri-lo, altere a extensão do nome do arquivo para .zip. Verifique se contém os arquivos .dll, .pkgdef e extension.vsixmanifest. O arquivo extension.vsixmanifest deve conter a lista apropriada no nó SupportedProducts e deve conter também um nó VsPackage, sob o nó Conteúdo:

    <Content>

    <VsPackage>CustomDirectiveProcessor.dll</VsPackage>

    </Content>

Implantando um processador de diretriz em um VSPackage

Se o processador de diretriz fizer parte de um VSPackage que será instalado no GAC, é possível fazer com que o sistema gere o arquivo .pkgdef para você.

Coloque o seguinte atributo na classe do pacote:

[ProvideDirectiveProcessor(typeof(DirectiveProcessorClass), "DirectiveProcessorName", "Directive processor description.")]

Observação

Esse atributo é colocado na classe de pacote, e não na classe de processador de diretriz.

O arquivo .pkgdef será gerado quando você compilar o projeto. Quando você instala o VSPackage, o arquivo .pkgdef registra o processador de diretriz.

Verifique se o arquivo .pkgdef aparece na pasta de compilação, que é geralmente bin\Debug ou bin\Release. Se não for exibido, abra o arquivo .csproj em um editor de texto e remova o seguinte nó: <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Para obter mais informações, confira VSPackages.

Configuração de uma chave do Registro

Esse método de instalação de um processador de diretriz personalizado é o menos preferido. Não fornece uma maneira conveniente de habilitar e desabilitar o processador de diretriz, e não fornece um método de distribuição do processador de diretriz para outros usuários.

Cuidado

A edição incorreta do Registro pode danificar seriamente o sistema. Antes de alterar o Registro, faça o backup de todos os dados importantes no computador.

Para registrar um processador de diretriz definindo uma chave do Registro

  1. Execute regedit.

  2. Em regedit, navegue até

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors

    Se você desejar instalar o processador de diretiva na versão de avaliação do Visual Studio, insira “Exp” após “11.0”.

  3. Adicione uma chave do Registro que tenha o mesmo nome da classe do processador de diretriz.

    • Na árvore do registro, clique com o botão direito do mouse no nó DirectiveProcessors, aponte para Novo e clique em Chave.

  4. No novo nó, adicione valores de cadeia de caracteres para Class e CodeBase ou Assembly, de acordo com as tabelas a seguir.

    1. Clique com o botão direito do mouse no nó que você criou, aponte para Novo e clique em Valor da Cadeia de Caracteres.

    2. Edite o nome do valor.

    3. Clique duas vezes no nome e edite os dados.

    Se o processador de diretriz personalizado não estiver no GAC, as subchaves do Registro deverão se parecer como na tabela a seguir:

Nome Tipo Dados
(Padrão) REG_SZ (valor não definido)
Classe REG_SZ <Nome do Namespace>.<Nome da Classe>
CodeBase REG_SZ <Seu caminho>\<Nome do Assembly>

Se o assembly estiver no GAC, as subchaves do Registro deverão se parecer como na tabela a seguir:

Nome Tipo Dados
(Padrão) REG_SZ (valor não definido)
Classe REG_SZ <Nome da Classe Totalmente Qualificado>
Assembly REG_SZ <Nome do Assembly no GAC>

Conteúdo relacionado