Entradas do Registro para suplementos VSTO

  • Artigo

Você deve criar um conjunto específico de entradas do Registro ao implantar suplementos VSTO que são criados usando o Visual Studio. Essas entradas do Registro fornecem informações que permitem que o aplicativo do Microsoft Office descubra e carregue o suplemento VSTO.

Aplica-se a: As informações neste tópico se aplicam a projetos de suplemento VSTO. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Observação

Interessado em desenvolver soluções que estendam a experiência do Office em várias plataformas? Confira o novo modelo de Suplementos do Office. Os Suplementos do Office têm um espaço pequeno em comparação com os suplementos e soluções VSTO, e você pode criá-los usando praticamente qualquer tecnologia de programação da Web, como HTML5, JavaScript, CSS3 e XML.

Quando você cria seu projeto, o Visual Studio cria essas entradas do Registro no computador de desenvolvimento. Isso ajuda você a executar e depurar facilmente o suplemento VSTO. Usando o ClickOnce para implantar seu suplemento VSTO, as entradas do Registro são criadas automaticamente no computador do usuário final.

Para obter mais informações sobre como implantar uma solução VSTO usando o Windows Installer, consulte Implantando uma solução VSTO usando o Windows Installer.

Para obter mais informações sobre como as entradas do Registro são usadas durante o processo de carregamento de suplementos VSTO, consulte Arquitetura de suplementos VSTO.

Observação

Neste tópico, a ID do suplemento de texto representa uma ID exclusiva para o suplemento VSTO. Por padrão, o ID é o nome do assembly do suplemento VSTO.

Registrar suplementos VSTO para o usuário atual versus todos os usuários

Quando um suplemento VSTO é instalado, ele pode ser registrado de duas maneiras:

  • Somente para o usuário atual (O suplemento VSTO está disponível somente para o usuário que estava conectado ao computador quando o suplemento foi instalado). Nesse caso, as entradas do Registro são criadas sob o HKEY_CURRENT_USER.

  • Para todos os usuários (ou seja, qualquer usuário que entra no computador pode usar o suplemento VSTO). Nesse caso, as entradas do Registro são criadas em HKEY_LOCAL_MACHINE.

    Todos os suplementos VSTO que você cria usando o Visual Studio podem ser registrados para o usuário atual. No entanto, os suplementos VSTO podem ser registrados para todos os usuários somente em determinados cenários. Esses cenários dependem da versão do Microsoft Office no computador e de como o suplemento VSTO foi implantado.

Tipo de implantação

Se você usar o ClickOnce para implantar um suplemento VSTO, o suplemento VSTO poderá ser registrado somente para o usuário atual. Isso ocorre porque o ClickOnce oferece suporte apenas à criação de chaves sob HKEY_CURRENT_USER. Se desejar registrar um suplemento VSTO para todos os usuários em um computador, você deverá usar o Windows Installer para implantar o suplemento VSTO. Para obter mais informações sobre esses tipos de implantação, consulte Implantar uma solução do Office usando o ClickOnce e Implantar uma solução do Office usando o Windows Installer.

Entradas do Registro

As entradas de registro necessárias do suplemento VSTO estão localizadas nas seguintes chaves do Registro, onde Root é HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE dependendo se a instalação for para o usuário atual ou todos os usuários.

Aplicativo do Office Caminho de configuração
Visio ID de Root\Software\Microsoft\Visio\Addins\add-in
Todos os outros ID do aplicativo Root\Software\Microsoft\Office\Office\Addins\add-in

Observação

Se o instalador estiver direcionado a todos os usuários no Windows de 64 bits, é recomendável que ele inclua duas entradas do Registro, uma sob o HKEY_LOCAL_MACHINE\Software\Microsoft e outra sob o HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft hive. Isso ocorre porque é possível que os usuários usem versões de 32 bits ou 64 bits do Office no computador.

Se o instalador estiver direcionado ao usuário atual, ele não precisará instalar no WOW6432Node porque o caminho HKEY_CURRENT_USER\Software é compartilhado.

Para obter mais informações, consulte Dados de aplicativos de 32 bits e 64 bits no Registro.

A tabela a seguir lista as entradas sob essa chave do Registro.

Entrada Tipo Valor
Descrição REG_SZ Obrigatório. Uma breve descrição do suplemento VSTO.

Essa descrição é exibida quando o usuário seleciona o suplemento VSTO no painel Suplementos da caixa de diálogo Opções no aplicativo Microsoft Office.
FriendlyName REG_SZ Obrigatório. Um nome descritivo do suplemento VSTO que é exibido na caixa de diálogo Suplementos COM no aplicativo Microsoft Office. O valor padrão é a ID do suplemento VSTO.
LoadBehavior REG_DWORD Obrigatório. Um valor que especifica quando o aplicativo tenta carregar o suplemento VSTO e o estado atual do suplemento VSTO (carregado ou descarregado).

Por padrão, essa entrada é definida como 3, que especifica que o suplemento VSTO é carregado na inicialização. Para obter mais informações, consulte Valores de LoadBehavior.

Nota: Se um usuário desabilitar o suplemento VSTO, essa ação modificará o valor de LoadBehavior na seção do Registro HKEY_CURRENT_USER. Para cada usuário, o valor de LoadBehavior no hive de HKEY_CURRENT_USER substitui o LoadBehavior padrão definido na seção HKEY_LOCAL_MACHINE.
Manifesto REG_SZ Obrigatório. O caminho completo do manifesto de implantação para o suplemento VSTO. O caminho pode ser um local no computador local, um compartilhamento de rede (UNC) ou um servidor Web (HTTP).

Se você usar o Windows Installer para implantar a solução, deverá adicionar o prefixo file:/// ao caminho do manifesto. Você também deve acrescentar a cadeia de caracteres |vstolocal (ou seja, o caractere | de pipe seguido de vstolocal) ao final desse caminho. Isso garante que sua solução seja carregada da pasta de instalação, em vez do cache ClickOnce. Para obter mais informações, consulte Implantar uma solução do Office usando o Windows Installer.

Nota: Quando você cria um suplemento VSTO no computador de desenvolvimento, o Visual Studio acrescenta automaticamente a cadeia de caracteres |vstolocal a essa entrada do Registro.

Entradas do Registro para regiões de formulário do Outlook

Se você criar uma área de formulário personalizada em um suplemento VSTO para Outlook, entradas de registro adicionais serão usadas para registrar a região de formulário com o Outlook. Essas entradas são criadas em uma chave do Registro diferente para cada classe de mensagem que a região do formulário suporta. Essas chaves do Registro estão no seguinte local, onde Root é HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE.

Root\Software\Microsoft\Office\Outlook\FormRegions\message classe

Como as outras entradas do Registro compartilhadas por todos os suplementos do VSTO, o Visual Studio cria as entradas do Registro da região do formulário no computador de desenvolvimento quando você cria seu projeto. Usando o ClickOnce para implantar seu suplemento VSTO, as entradas do Registro são criadas automaticamente no computador do usuário final. Ao usar o Windows Installer para implantar o suplemento VSTO, você deve configurar o projeto InstallShield Limited Edition para criar as entradas do Registro no computador do usuário final.

Para obter mais informações sobre as entradas do Registro da região do formulário, consulte Especificar o local de uma região de formulário em um formulário personalizado. Para obter mais informações sobre regiões de formulário do Outlook, consulte Criar regiões de formulário do Outlook.

Valores de LoadBehavior

A entrada LoadBehavior sob a chave de ID Root\Software\Microsoft\Office\application name\Addins\add-in contém uma combinação bit a bit de valores que especificam o comportamento de tempo de execução do suplemento VSTO. O bit de ordem mais baixo (valores 0 e 1) indica se o suplemento VSTO está atualmente descarregado ou carregado. Outros bits indicam quando o aplicativo tenta carregar o suplemento VSTO.

Normalmente, a entrada LoadBehavior destina-se a ser definida como 0, 3 ou 16 (em decimal) quando o suplemento VSTO é instalado em computadores de usuário final. Por padrão, o Visual Studio define a entrada LoadBehavior do suplemento VSTO como 3 quando você compilá-lo ou publicá-lo.

A tabela a seguir lista todos os valores possíveis da entrada LoadBehavior . Algumas descrições nesta tabela referem-se ao carregamento de um suplemento VSTO manualmente ou programaticamente. Para carregar um suplemento VSTO manualmente, marque a caixa de seleção ao lado do suplemento VSTO na caixa de diálogo Suplementos COM no aplicativo. Para carregar um suplemento VSTO programaticamente, defina a ConnectCOMAddIn propriedade do objeto que representa o suplemento VSTO como true.

Valor (em decimal) Status do suplemento VSTO Comportamento de carregamento do suplemento VSTO Descrição
0 Descarregado Não carregar automaticamente O aplicativo nunca tenta carregar o suplemento VSTO automaticamente. O usuário pode tentar carregar manualmente o suplemento VSTO ou o suplemento VSTO pode ser carregado programaticamente.

Se o suplemento VSTO for carregado com êxito, o valor LoadBehavior permanecerá 0, mas o status do suplemento VSTO na caixa de diálogo Suplementos COM será atualizado para indicar que o suplemento VSTO foi carregado.
1 Carregado Não carregar automaticamente O aplicativo nunca tenta carregar o suplemento VSTO automaticamente. O usuário pode tentar carregar manualmente o suplemento VSTO ou o suplemento VSTO pode ser carregado programaticamente.

Embora a caixa de diálogo Suplementos COM indique que o Suplemento VSTO é carregado após o início do aplicativo, o Suplemento VSTO não é carregado até que seja carregado manual ou programaticamente.

Se o aplicativo carregar com êxito o suplemento VSTO, o valor LoadBehavior será alterado para 0 e permanecerá em 0 após o fechamento do aplicativo.
2 Descarregado Carregar na inicialização O aplicativo não tenta carregar o suplemento VSTO automaticamente. O usuário pode tentar carregar manualmente o suplemento VSTO ou o suplemento VSTO pode ser carregado programaticamente.

Se o aplicativo carregar com êxito o suplemento VSTO, o valor LoadBehavior será alterado para 3 e permanecerá em 3 após o fechamento do aplicativo.
3 Carregado Carregar na inicialização O aplicativo tenta carregar o suplemento VSTO quando o aplicativo é iniciado. Esse é o valor padrão quando você cria ou publica um suplemento VSTO no Visual Studio.

Se o aplicativo carregar com êxito o suplemento VSTO, o valor LoadBehavior permanecerá 3. Se ocorrer um erro ao carregar o suplemento VSTO, o valor LoadBehavior será alterado para 2 e permanecerá em 2 após o fechamento do aplicativo.
8 Descarregado Carga sob demanda O aplicativo não tenta carregar o suplemento VSTO automaticamente. O usuário pode tentar carregar manualmente o suplemento VSTO ou o suplemento VSTO pode ser carregado programaticamente.

Se o aplicativo carregar com êxito o suplemento VSTO, o valor LoadBehavior será alterado para 9.
9 Carregado Carga sob demanda O suplemento VSTO será carregado somente quando o aplicativo exigir. Como quando um usuário seleciona um elemento da interface do usuário que usa a funcionalidade no suplemento VSTO (por exemplo, um botão personalizado na Faixa de Opções).

Se o aplicativo carregar com êxito o suplemento VSTO, o valor LoadBehavior permanecerá 9, mas o status do suplemento VSTO na caixa de diálogo Suplementos COM será atualizado para indicar que o suplemento VSTO está carregado no momento. Se ocorrer um erro ao carregar o suplemento VSTO, o valor LoadBehavior será alterado para 8.
16 Carregado Carregue primeiro e, em seguida, carregue sob demanda Defina esse valor se desejar que o suplemento VSTO seja carregado sob demanda. O aplicativo carrega o suplemento VSTO quando o usuário executa o aplicativo pela primeira vez. Na próxima vez que o usuário executar o aplicativo, o aplicativo carregará todos os elementos da interface do usuário definidos pelo suplemento VSTO. No entanto, o suplemento VSTO não é carregado até que o usuário selecione um elemento de interface do usuário associado ao suplemento VSTO.

Quando o aplicativo carrega com êxito o suplemento VSTO pela primeira vez, o valor LoadBehavior permanece 16 enquanto o suplemento VSTO é carregado. Depois que o aplicativo é fechado, o valor LoadBehavior muda para 9.

Conteúdo relacionado