Registro de suplementos

Artigo
06/10/2015

Os suplementos do Visual Studio foram preteridos no Visual Studio 2013. Você deve atualizar seus suplementos para as extensões VSPackage. Para obter mais informações sobre a atualização, consulte Perguntas frequentes: convertendo suplementos em extensões VSPackage.

Após um suplemento ser criado, será necessário registrá-lo no Visual Studio para que ele possa ser ativado no Gerenciador de Suplementos. Isso é realizado usando um arquivo XML que tem uma extensão de nome de arquivo .addin.

O arquivo .addin descreve as informações de que Visual Studio precisa para exibir o suplemento no Gerenciador de Suplementos. Quando o Visual Studio inicia, ele examina no local do arquivo .addin qualquer arquivo .addin disponível. Se encontrar algum, ele lerá o arquivo XML e fornecerá ao Gerenciador de Suplementos as informações necessárias para iniciar o suplemento quando clicado.

O arquivo .addin é criado automaticamente quando você cria um suplemento usando o Assistente de Suplemento. Também é possível criar um arquivo .addin manualmente usando as informações deste tópico.

Locais dos arquivos

Duas cópias do arquivo .addin são criadas automaticamente pelo Assistente de Suplemento da seguinte forma:

Local do arquivo .addin	Local do arquivo .dll	Descrição
Pasta raiz do projeto \Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\	Caminho local (MyAddin1.dll)	Usado na implantação do projeto de suplemento. Incluído no projeto para facilitar a edição e tem o caminho local para a implantação de xcopy-style.
Pasta do suplemento \Documents\Visual Studio 2013\Addins\ -ou- Shared Documents Location\Addins\	Pasta de depuração do projeto (Por exemplo, \Documents\Visual Studio 2013 Projects\MyAddin1\MyAddin1\bin\)	Usado para executar o suplemento no ambiente de depuração. Ela deve sempre apontar para o caminho de saída da configuração da compilação atual.

Pasta raiz do projeto

\Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\

Caminho local (MyAddin1.dll)

Usado na implantação do projeto de suplemento. Incluído no projeto para facilitar a edição e tem o caminho local para a implantação de xcopy-style.

Pasta do suplemento

\Documents\Visual Studio 2013\Addins\

-ou-

Shared Documents Location\Addins\

Pasta de depuração do projeto

(Por exemplo, \Documents\Visual Studio 2013

Projects\MyAddin1\MyAddin1\bin\)

Usado para executar o suplemento no ambiente de depuração. Ela deve sempre apontar para o caminho de saída da configuração da compilação atual.

Para instalar o suplemento em outro computador, o arquivo .addin deve ser colocado em um local em que o Visual Studio verifica se há suplementos. Esses locais são listados na caixa de diálogo Opções, no nó Ambiente, na página Segurança do Suplemento. Para obter mais informações, consulte Segurança de Suplemento.

O arquivo .dll que contém o suplemento pode ser instalado em qualquer local no computador cliente. No entanto, recomendamos que você o coloque com o arquivo .addin.

Dica

O elemento <Assembly> do arquivo .addin deve apontar para o arquivo .dll que contém os binários do suplemento.

O Arquivo .Addin

O arquivo XML .addin é dividido nas seguintes seções marcadas:

Seção	Descrição
Aplicativo Host	(Obrigatório.) Especifica os nomes e os números de versão dos aplicativos que podem carregar o suplemento.
Addin	(Obrigatório) Contém os elementos que descrevem o suplemento.
Página Opções de Ferramentas	(Opcional) Especifica uma página na caixa de diálogo Opções em que o suplemento pode ser configurado. Os nós filhos especificam a categoria e a subcategoria da página Opções e também seu nome de assembly e o nome completo da classe.

Os seguintes elementos são filhos da seção <Addin>:

Elemento	Descrição
Sobre Detalhes da Caixa	(Opcional) Especifica o texto que será exibido para o seu suplemento na caixa de diálogo Sobre do Visual Studio.
Sobre Dados do Ícone	(Opcional) Contém dados binários que especificam o ícone que será exibido para o seu suplemento na caixa de diálogo Sobre do Visual Studio.
Sobre Local do Ícone	(Opcional) Especifica o caminho absoluto ou relativo do ícone que será exibido para o seu suplemento na caixa de diálogo Sobre do Visual Studio.
Assembly	(Obrigatório.) Especifica o local dos binários do suplemento. Esse campo pode ser definido como um caminho local, um caminho de rede ou uma URL.
Seguro para Linha de Comando	(Opcional) Especifica os modos de Visual Studio com os quais o suplemento é compatível, por exemplo, somente linha de comando e/ou somente ambiente de desenvolvimento integrado (IDE).
Pré-carga de Comando	(Opcional) Especifica o estado pré-carregado do suplemento, ou seja, se o suplemento deve criar sua interface de usuário usando um método como o Commands.AddNamedCommand.
Nome Completo da Classe	(Obrigatório.) Especifica o nome da classe usado para se conectar ao suplemento.
Comportamento da Carga	(Opcional) Define se um suplemento é carregado na inicialização ou manualmente.

Aqui estão os detalhes de cada configuração. Para obter mais informações sobre a localização hierárquica de vários dos elementos descritos, consulte "Exemplo do Arquivo XML .Addin" mais adiante neste tópico.

Aplicativo Host

O elemento <Name> na seção Host Application contém o nome do aplicativo. Esse é o nome exibido na barra de título do aplicativo ou é retornado por DTE.Name. Por exemplo, para Visual Studio, a marca deveria conter "Microsoft Visual Studio".

Pode haver mais de um valor Aplicativo Host por arquivo .addin. Cada valor deve estar entre colchetes usando as marcas <Name> no elemento <HostApplication>. Além de conter um elemento <Name>, cada elemento <HostApplication> também deve incluir o número da versão do aplicativo entre colchetes por marcas <Version>. Por exemplo,

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>12.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio</Name>
      <Version>11.0</Version>
   </HostApplication>

Como alternativa, você pode especificar um asterisco (*) para representar o valor de <Version> para qualquer versão do Visual Studio.

Nome Amigável

O elemento <FriendlyName>, que está localizado no elemento <Addin>, especifica a cadeia de caracteres que será exibida na coluna Suplementos Disponíveis em Gerenciador de Suplementos. Por exemplo,

   <FriendlyName>My New Super Addin</FriendlyName>

Descrição

O elemento <Description>, que está localizado no elemento <Addin>, especifica a cadeia de caracteres que será exibida na caixa Descrição em Gerenciador de Suplementos. Por exemplo,

   <Description>This add-in will change your life!</Description>

Sobre Detalhes da Caixa

Se você escolher a opção para gerar configurações para a caixa de diálogo Sobre ao criar seu suplemento, esse elemento será adicionado ao arquivo .addin. Esse elemento especifica o texto que será exibido na caixa de diálogo Sobre do Visual Studio. Por exemplo,

   <AboutBoxDetails>For add-in support, call 1-800-xxx-
     xxxx.</AboutBoxDetails>

Sobre Dados do Ícone

Se você escolher a opção para gerar configurações para a caixa de diálogo Sobre ao criar seu suplemento, esse elemento será adicionado ao arquivo .addin. Esse elemento contém dados binários que especificam o ícone que será exibido na caixa de diálogo Sobre do Visual Studio. Por exemplo,

<AboutIconData>0000010006 . . . FFFF0000</AboutIconData>

Assembly

O elemento <Assembly>, que está localizado no elemento <Addin>, especifica o local dos arquivos binários do suplemento. Esse elemento pode ser configurado como um caminho relativo, um caminho absoluto ("arquivo"), um nome de assembly registrado ("assembly") ou uma URL ("url").

O exemplo a seguir mostra um local de caminho absoluto. Nesse caso, o parâmetro src está configurado como file para indicar o local na DLL do suplemento.
```
<Assembly src="file">C:\Documents and Settings\jdoe\Application Data\Microsoft\Visual Studio\12.0\AddIns\MyAddin4.dll</Assembly>
```
O exemplo a seguir mostra um local registrado. Nesse caso, o parâmetro src está configurado como assembly para indicar uma DLL do suplemento registrada.
```
<Assembly src="assembly">BookshelfDefineAddin</Assembly>
```
O exemplo a seguir mostra uma localização de URL. Nesse caso, o parâmetro src está configurado como url para indicar a localização baseada na Web da DLL do suplemento.
```
<Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
```

Nome Completo da Classe

O elemento <FullClassName> especifica o nome completo da classe usado para se conectar ao suplemento. Isso inclui o namespace que contém a classe. Por exemplo,

    <FullClassName>MyAddin4.Connect</FullClassName>

Comportamento da Carga

O elemento <LoadBehavior> define se um suplemento é carregado automaticamente na inicialização do IDE ou é iniciado manualmente. O elemento <LoadBehavior> está sob o elemento <Addin>. Por exemplo,

    <LoadBehavior>1</LoadBehavior>

Embora o uso de <LoadBehavior> seja opcional, recomendamos utilizá-lo para definir explicitamente quando um suplemento é carregado.

Valor	Descrição
0	O suplemento não é carregado na inicialização do IDE e deve ser iniciado manualmente.
1	O suplemento é carregado automaticamente na inicialização do IDE.
4	O suplemento é carregado quando devenv é iniciado em um prompt de comando usando uma opção de compilação (devenv /build).

Pré-carga de Comando

O elemento <CommandPreload> especifica se o suplemento deve ser pré-carregado. O pré-carregamento carrega o suplemento na primeira vez em que o Visual Studio é iniciado após a instalação do arquivo .addin. Por exemplo,

    <CommandPreload>1</CommandPreload>

Esse elemento permite especificar que um suplemento deve ser carregado após Visual Studio ser iniciado. Isso permite ao seu suplemento uma chance de criar elementos necessários da interface do usuário, tais como botões da barra de comandos, ou executar outras tarefas de inicialização somente na primeira vez, tais como criar configurações padrão de suplementos. O suplemento é então descarregado até que um usuário execute um dos comandos criados pelo suplemento. Depois disso, o suplemento é carregado conforme necessário.

Valor	Descrição
0	O suplemento não é carregado até que o usuário o inicie usando o Gerenciador de Suplementos ou o suplemento seja definido para ser carregado na inicialização.
1	O suplemento é carregado automaticamente quando Visual Studio for iniciado pela primeira vez após a instalação do arquivo .addin.

É possível verificar o método OnConnection que você implementa para ver se o tipo de conexão, que é especificado usando o segundo argumento para OnConnection, é ext_cm_UISetup. Caso seja, você poderá executar quaisquer posicionamentos de comandos desejados usando o método AddNamedCommand ou AddControl.

Seguro para Linha de Comando

O elemento <CommandLineSafe> opcional indica se o suplemento foi projetado para evitar a exibição de uma interface do usuário iniciado em um prompt de comando, por exemplo, quando você executar compilações da linha de comando ou operações semelhantes. (Isso é feito ao escolher Meu Suplemento nunca colocará uma interface do usuário modal no Assistente de Suplemento.) Além disso, ele especifica os modos do Visual Studio com os quais o suplemento é compatível, por exemplo, somente linha de comando ou somente IDE. Por exemplo,

    <CommandLineSafe>0</CommandLineSafe>

Valor	Descrição
0	Especifica que o suplemento não é seguro para linha de comando e pode exibir uma interface do usuário.
1	Especifica que o suplemento é seguro para linha de comando e não pode exibir uma interface do usuário.

Página Opções de Ferramentas

O elemento <ToolsOptionsPage> opcional especifica uma página Opções para que os usuários possam configurar o suplemento. Os nós filhos especificam a categoria e a subcategoria na qual a página é exibida, além do nome de assembly e do nome completo da classe da página Opções. O seguinte exemplo mostra a hierarquia deste elemento:

  <ToolsOptionsPage>
    <Category Name="Text Editor">
      <SubCategory Name="General">
        <Assembly>"MyFilePath\MyAddInOptionPage.dll"</Assembly>
        <FullClassName>"MyNamespace.MyAddInOptionPage"</FullClassName>
      </SubCategory>
    </Category>
  </ToolsOptionsPage>

Exemplo do Arquivo XML .Addin

O exemplo a seguir mostra um arquivo XML .addin completo. Ele mostra a hierarquia e os locais dos elementos que são descritos neste tópico.

<?xml version="1.0" encoding="UTF-16" standalone="no"?>
<Extensibility 
  xmlns="https://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>12.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>11.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2013.</AboutBoxDetails>
        <AboutIconData>0000 . . . FFFF0000</AboutIconData>
        <Assembly>MyNewAddin.dll</Assembly>
        <FullClassName>MyNewAddin.Connect</FullClassName>
        <LoadBehavior>1</LoadBehavior>
        <CommandPreload>1</CommandPreload>
        <CommandLineSafe>0</CommandLineSafe>
    </Addin>
</Extensibility>

Consulte também

Compartilhar via