Entradas de registro para suplementos do VSTORegistry entries for VSTO Add-ins

Você deve criar um conjunto específico de entradas de registro ao implantar suplementos do VSTO que são criados usando o Visual Studio.You must create a specific set of registry entries when you deploy VSTO Add-ins that are created by using Visual Studio. Essas entradas de registro fornecem informações que permitem que o aplicativo Microsoft Office descubra e carregue o suplemento do VSTO.These registry entries provide information that enables the Microsoft Office application to discover and load the VSTO Add-in.

Aplica-se a: As informações neste tópico se aplicam ao VSTO Add - in Projects.Applies to: The information in this topic applies to VSTO Add-in projects. Para obter mais informações, consulte recursos disponíveis por aplicativo do Office e tipo de projeto.For more information, see Features available by Office application and project type.

Observação

Interessado em desenvolver soluções que estendam a experiência do Office em várias plataformas?Interested in developing solutions that extend the Office experience across multiple platforms? Confira o novo modelo de suplementos do Office.Check out the new Office Add-ins model. Os suplementos do Office têm uma pequena superfície em comparação com os suplementos e soluções do VSTO, e você pode criá-los usando praticamente qualquer tecnologia de programação da Web, como HTML5, JavaScript, CSS3 e XML.Office Add-ins have a small footprint compared to VSTO Add-ins and solutions, and you can build them by using almost any web programming technology, such as HTML5, JavaScript, CSS3, and XML.

Quando você cria seu projeto, o Visual Studio cria essas entradas de registro no computador de desenvolvimento para que você possa executar e depurar facilmente o suplemento do VSTO.When you build your project, Visual Studio creates these registry entries on the development computer so that you can easily run and debug the VSTO Add-in. Se você usar o ClickOnce para implantar seu suplemento do VSTO, as entradas do registro serão criadas automaticamente no computador do usuário final.If you use ClickOnce to deploy your VSTO Add-in, the registry entries are automatically created on the end-user computer. Se você usar Windows Installer para implantar o suplemento do VSTO, deverá configurar o projeto do InstallShield Limited Edition para criar as entradas do registro no computador do usuário final.If you use Windows Installer to deploy your VSTO Add-in, you must configure the InstallShield Limited Edition project to create the registry entries on the end-user computer.

Para obter mais informações sobre como as entradas do registro são usadas durante o processo de carregamento para suplementos do VSTO, consulte arquitetura de suplementos do VSTO.For more information about how the registry entries are used during the load process for VSTO Add-ins, see Architecture of VSTO Add-ins.

Observação

Neste tópico, a ID do suplemento de texto representa uma ID exclusiva para seu suplemento do VSTO.In this topic, the text add-in ID represents a unique ID for your VSTO Add-in. Por padrão, a ID é o nome do seu assembly de suplemento do VSTO.By default, the ID is the name of your VSTO Add-in assembly.

Registrar suplementos do VSTO para o usuário atual versus todos os usuáriosRegister VSTO Add-ins for the current user vs. all users

Quando um suplemento do VSTO é instalado, ele pode ser registrado de duas maneiras:When a VSTO Add-in is installed, it can be registered in two ways:

  • Somente para o usuário atual (ou seja, ele está disponível somente para o usuário que está conectado ao computador quando o suplemento do VSTO está instalado).For the current user only (that is, it is available only to the user that is logged on to the computer when the VSTO Add-in is installed). Nesse caso, as entradas do registro são criadas no HKEY_CURRENT_USER.In this case, the registry entries are created under the HKEY_CURRENT_USER.

  • Para todos os usuários (ou seja, qualquer usuário que faça logon no computador pode usar o suplemento do VSTO).For all users (that is, any user that logs on to the computer can use the VSTO Add-in). Nesse caso, as entradas do registro são criadas em HKEY_LOCAL_MACHINE.In this case, the registry entries are created under HKEY_LOCAL_MACHINE.

    Todos os suplementos do VSTO que você cria usando o Visual Studio podem ser registrados para o usuário atual.All VSTO Add-ins that you create by using Visual Studio can be registered for the current user. No entanto, os suplementos do VSTO podem ser registrados para todos os usuários somente em determinados cenários.However, VSTO Add-ins can be registered for all users only in certain scenarios. Esses cenários dependem da versão do Microsoft Office no computador e de como o suplemento do VSTO foi implantado.These scenarios depend on the version of Microsoft Office on the computer and how the VSTO Add-in was deployed.

Tipo de implantaçãoDeployment type

Se você usar o ClickOnce para implantar um suplemento do VSTO, o suplemento do VSTO só poderá ser registrado para o usuário atual.If you use ClickOnce to deploy a VSTO Add-in, the VSTO Add-in can be registered only for the current user. Isso ocorre porque o ClickOnce só dá suporte à criação de chaves em HKEY_CURRENT_USER.This is because ClickOnce only supports creating keys under HKEY_CURRENT_USER. Se você quiser registrar um suplemento do VSTO para todos os usuários em um computador, deverá usar Windows Installer para implantar o suplemento do VSTO.If you want to register a VSTO Add-in to all users on a computer, you must use Windows Installer to deploy the VSTO Add-in. 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 Windows Installer.For more information about these deployment types, see Deploy an Office solution by using ClickOnce and Deploy an Office solution by using Windows Installer.

Entradas do RegistroRegistry entries

As entradas do registro do suplemento do VSTO necessárias estão localizadas nas seguintes chaves do registro, em que a raiz é HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE dependendo se a instalação for para o usuário atual ou para todos os usuários.The required VSTO Add-in registry entries are located under the following registry keys where Root is HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE depending if the installation is for the current user or all users.

Aplicativo do OfficeOffice Application Caminho de configuraçãoConfiguration Path
VisioVisio \ \ ID do suplemento \Software\Microsoft do Visio \AddinsRoot\Software\Microsoft\Visio\Addins\add-in ID
Todos os outrosAll Other Raiz\Software\Microsoft\Office \ nome do aplicativo do Office\Addins \ ID do suplementoRoot\Software\Microsoft\Office\Office application name\Addins\add-in ID

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 na HKEY_LOCAL_MACHINE\Software\Microsoft e outra no hive HKEY_LOCAL_MACHINE\Software\ WOW6432Node\Microsoft.If the installer is targeting all users on 64-bit Windows, it is recommended that it includes two registry entries, one under the HKEY_LOCAL_MACHINE\Software\Microsoft and one under the 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.This is because it's possible for users to use either 32-bit or 64-bit versions of Office on the computer.

Se o instalador estiver direcionando para o usuário atual, ele não precisará instalar no WOW6432Node porque o caminho de HKEY_CURRENT_USER\Software é compartilhado.If the Installer is targeting the current user, it does not need to install to the WOW6432Node because the HKEY_CURRENT_USER\Software path is shared.

Para obter mais informações, consulte dados de aplicativos de 32 bits e de 64 bits no registroFor more information please see 32-bit and 64-bit Application Data in the Registry

A tabela a seguir lista as entradas nessa chave do registro.The following table lists the entries under this registry key.

EntradaEntry TypeType ValorValue
DescriçãoDescription REG_SZREG_SZ Obrigatório.Required. Uma breve descrição do suplemento do VSTO.A brief description of the VSTO Add-in.

Essa descrição é exibida quando o usuário seleciona o suplemento do VSTO no painel de suplementos da caixa de diálogo opções no aplicativo Microsoft Office.This description is displayed when the user selects the VSTO Add-in in the Add-Ins pane of the Options dialog box in the Microsoft Office application.
FriendlyNameFriendlyName REG_SZREG_SZ Obrigatório.Required. Um nome descritivo do suplemento do VSTO que é exibido na caixa de diálogo suplementos de com no aplicativo Microsoft Office.A descriptive name of the VSTO Add-in that is displayed in the COM Add-Ins dialog box in the Microsoft Office application. O valor padrão é a ID do suplemento do VSTO.The default value is the VSTO Add-in ID.
LoadBehaviorLoadBehavior REG_DWORDREG_DWORD Obrigatório.Required. Um valor que especifica quando o aplicativo tenta carregar o suplemento do VSTO e o estado atual do suplemento do VSTO (carregado ou descarregado).A value that specifies when the application attempts to load the VSTO Add-in and the current state of the VSTO Add-in (loaded or unloaded).

Por padrão, essa entrada é definida como 3, o que especifica que o suplemento do VSTO é carregado na inicialização.By default, this entry is set to 3, which specifies that the VSTO Add-in is loaded at startup. Para obter mais informações, veja valores de LoadBehavior.For more information, see LoadBehavior values. Observação: Se um usuário desabilitar o suplemento do VSTO, essa ação modificará o valor LoadBehavior no hive do registro HKEY_CURRENT_USER .Note: If a user disables the VSTO Add-in, that action modifies LoadBehavior value in the HKEY_CURRENT_USER registry hive. Para cada usuário, o valor do valor LoadBehavior no hive HKEY_CURRENT_USER substitui o LoadBehavior padrão definido no hive HKEY_LOCAL_MACHINE .For each user, the value of the LoadBehavior value in the HKEY_CURRENT_USER hive overrides the default LoadBehavior defined in the HKEY_LOCAL_MACHINE hive.
ManifestManifest REG_SZREG_SZ Obrigatório.Required. O caminho completo do manifesto de implantação para o suplemento do VSTO.The full path of the deployment manifest for the VSTO Add-in. O caminho pode ser um local no computador local, um compartilhamento de rede (UNC) ou um servidor Web (HTTP).The path can be a location on the local computer, a network share (UNC), or a Web server (HTTP).

Se você usar Windows Installer para implantar a solução, deverá adicionar o prefixo file:/// ao caminho do manifesto .If you use Windows Installer to deploy the solution, you must add the prefix file:/// to the manifest path. Você também deve acrescentar a cadeia de caracteres |vstolocal (ou seja, o caractere de pipe | seguido por vstolocal) ao final deste caminho.You must also append the string |vstolocal (that is, the pipe character | followed by vstolocal) to the end of this path. Isso garante que sua solução seja carregada a partir da pasta de instalação, em vez do cache do ClickOnce.This ensures that your solution is loaded from the installation folder, rather than the ClickOnce cache. Para obter mais informações, consulte implantar uma solução do Office usando Windows Installer.For more information, see Deploy an Office solution by using Windows Installer. Observação: Quando você cria um suplemento do VSTO no computador de desenvolvimento, o Visual Studio acrescenta automaticamente a cadeia de caracteres |vstolocal a essa entrada de registro.Note: When you build a VSTO Add-in on the development computer, Visual Studio automatically appends the |vstolocal string to this registry entry.

Entradas de registro para regiões de formulário do OutlookRegistry entries for Outlook form regions

Se você criar uma região de formulário personalizada em um suplemento do VSTO para o Outlook, as entradas adicionais do registro serão usadas para registrar a região do formulário com o Outlook.If you create a custom form region in a VSTO Add-in for Outlook, additional registry entries are used to register the form region with Outlook. Essas entradas são criadas sob uma chave de registro diferente para cada classe de mensagem à qual a região de formulário dá suporte.These entries are created under a different registry key for each message class that the form region supports. Essas chaves do registro estão no seguinte local, onde a raiz é HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE.These registry keys are in the following location, where Root is HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

Classe de \ mensagem \Software\Microsoft\Office\Outlook\FormRegions raizRoot\Software\Microsoft\Office\Outlook\FormRegions\message class

Assim como as outras entradas de registro compartilhadas por todos os suplementos do VSTO, o Visual Studio cria as entradas do registro de região de formulário no computador de desenvolvimento quando você cria seu projeto.Like the other registry entries shared by all VSTO Add-ins, Visual Studio creates the form region registry entries on the development computer when you build your project. Se você usar o ClickOnce para implantar seu suplemento do VSTO, as entradas do registro serão criadas automaticamente no computador do usuário final.If you use ClickOnce to deploy your VSTO Add-in, the registry entries are automatically created on the end-user computer. Se você usar Windows Installer para implantar o suplemento do VSTO, deverá configurar o projeto do InstallShield Limited Edition para criar as entradas do registro no computador do usuário final.If you use Windows Installer to deploy your VSTO Add-in, you must configure the InstallShield Limited Edition project to create the registry entries on the end-user computer.

Para obter mais informações sobre as entradas de registro de região de formulário, consulte especificar o local de uma região de formulário em um formulário personalizado.For more information about the form region registry entries, see Specify the location of a form region in a custom form. Para obter mais informações sobre as regiões de formulário do Outlook, consulte criar regiões de formulário do Outlook.For more information about Outlook form regions, see Create Outlook form regions.

Valores de LoadBehaviorLoadBehavior values

A entrada LoadBehavior sob a chave de \ ID do suplemento \Addins do nome do aplicativo\Software\Microsoft\Office raiz \ contém uma combinação bit-a-ponto de valores que especificam o comportamento de tempo de execução do suplemento do VSTO.The LoadBehavior entry under the Root\Software\Microsoft\Office\application name\Addins\add-in ID key contains a bitwise combination of values that specify the run time behavior of the VSTO Add-in. O menor bit de ordem (valores 0 e 1) indica se o suplemento do VSTO está atualmente descarregado ou carregado.The lowest order bit (values 0 and 1) indicates whether the VSTO Add-in is currently unloaded or loaded. Outros bits indicam quando o aplicativo tenta carregar o suplemento do VSTO.Other bits indicate when the application attempts to load the VSTO Add-in.

Normalmente, a entrada LoadBehavior deve ser definida como 0, 3 ou 16 (em decimal) quando o suplemento do VSTO é instalado nos computadores dos usuários finais.Typically, the LoadBehavior entry is intended to be set to 0, 3, or 16 (in decimal) when the VSTO Add-in is installed on end-user computers. Por padrão, o Visual Studio define a entrada LoadBehavior de seu suplemento do VSTO como 3 quando você o compila ou publica.By default, Visual Studio sets the LoadBehavior entry of your VSTO Add-in to 3 when you build or publish it.

A tabela a seguir lista todos os valores possíveis da entrada LoadBehavior .The following table lists all the possible values of the LoadBehavior entry. Algumas descrições nesta tabela referem-se ao carregamento de um suplemento do VSTO manual ou programaticamente.Some descriptions in this table refer to loading a VSTO Add-in manually or programmatically. Para carregar um suplemento do VSTO manualmente, marque a caixa de seleção ao lado do suplemento do VSTO na caixa de diálogo suplementos do com no aplicativo.To load a VSTO Add-in manually, select the check box next to the VSTO Add-in in the COM Add-Ins dialog box in the application. Para carregar um suplemento do VSTO programaticamente, defina a Connect Propriedade do COMAddIn objeto que representa o suplemento do VSTO como true.To load a VSTO Add-in programmatically, set the Connect property of the COMAddIn object that represents the VSTO Add-in to true.

Valor (em decimal)Value (in decimal) Status do suplemento do VSTOVSTO Add-in status Comportamento de carregamento do suplemento do VSTOVSTO Add-in load behavior DescriçãoDescription
00 DescarregadoUnloaded Não carregar automaticamenteDo not load automatically O aplicativo nunca tenta carregar o suplemento do VSTO automaticamente.The application never tries to load the VSTO Add-in automatically. O usuário pode tentar carregar manualmente o suplemento do VSTO ou o suplemento do VSTO pode ser carregado programaticamente.The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

Se o suplemento do VSTO for carregado com êxito, o valor LoadBehavior permanecerá 0, mas o status do suplemento do VSTO na caixa de diálogo suplementos do com será atualizado para indicar que o suplemento do VSTO está carregado.If the VSTO Add-in is successfully loaded, the LoadBehavior value remains 0, but the status of the VSTO Add-in in the COM Add-ins dialog box is updated to indicate that the VSTO Add-in is loaded.
11 CarregadoLoaded Não carregar automaticamenteDo not load automatically O aplicativo nunca tenta carregar o suplemento do VSTO automaticamente.The application never tries to load the VSTO Add-in automatically. O usuário pode tentar carregar manualmente o suplemento do VSTO ou o suplemento do VSTO pode ser carregado programaticamente.The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

Embora a caixa de diálogo suplementos de com indique que o suplemento do VSTO é carregado depois que o aplicativo é iniciado, o suplemento do VSTO não é carregado até que seja carregado manualmente ou programaticamente.Although the COM Add-ins dialog box indicates that the VSTO Add-in is loaded after the application starts, the VSTO Add-in isn't loaded until it is loaded manually or programmatically.

Se o aplicativo carregar o suplemento do VSTO com êxito, o valor LoadBehavior será alterado para 0 e permanecerá em 0 depois que o aplicativo for fechado.If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 0, and remains at 0 after the application closes.
22 DescarregadoUnloaded Carregar na inicializaçãoLoad at startup O aplicativo não tenta carregar o suplemento do VSTO automaticamente.The application does not try to load the VSTO Add-in automatically. O usuário pode tentar carregar manualmente o suplemento do VSTO ou o suplemento do VSTO pode ser carregado programaticamente.The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

Se o aplicativo carregar o suplemento do VSTO com êxito, o valor LoadBehavior mudará para 3 e permanecerá em 3 depois que o aplicativo for fechado.If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 3, and remains at 3 after the application closes.
33 CarregadoLoaded Carregar na inicializaçãoLoad at startup O aplicativo tenta carregar o suplemento do VSTO quando o aplicativo é iniciado.The application tries to load the VSTO Add-in when the application starts. Esse é o valor padrão quando você cria ou publica um suplemento do VSTO no Visual Studio.This is the default value when you build or publish a VSTO Add-in in Visual Studio.

Se o aplicativo carregar o suplemento do VSTO com êxito, o valor LoadBehavior permanecerá 3.If the application successfully loads the VSTO Add-in, the LoadBehavior value remains 3. Se ocorrer um erro ao carregar o suplemento do VSTO, o valor LoadBehavior será alterado para 2 e permanecerá em 2 depois que o aplicativo for fechado.If an error occurs when loading the VSTO Add-in, the LoadBehavior value changes to 2, and remains at 2 after the application closes.
88 DescarregadoUnloaded Carregar sob demandaLoad on demand O aplicativo não tenta carregar o suplemento do VSTO automaticamente.The application does not try to load the VSTO Add-in automatically. O usuário pode tentar carregar manualmente o suplemento do VSTO ou o suplemento do VSTO pode ser carregado programaticamente.The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

Se o aplicativo carregar o suplemento do VSTO com êxito, o valor LoadBehavior mudará para 9.If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 9.
99 CarregadoLoaded Carregar sob demandaLoad on demand O suplemento do VSTO será carregado somente quando o aplicativo exigir, como quando um usuário clicar em um elemento da interface do usuário que usa a funcionalidade no suplemento do VSTO (por exemplo, um botão personalizado na faixa de bits).The VSTO Add-in will be loaded only when the application requires it, such as when a user clicks a UI element that uses functionality in the VSTO Add-in (for example, a custom button in the Ribbon).

Se o aplicativo carregar o suplemento do VSTO com êxito, o valor LoadBehavior permanecerá em 9, mas o status do suplemento do VSTO na caixa de diálogo suplementos do com será atualizado para indicar que o suplemento do VSTO está carregado no momento.If the application successfully loads the VSTO Add-in, the LoadBehavior value remains 9, but the status of the VSTO Add-in in the COM Add-ins dialog box is updated to indicate that the VSTO Add-in is currently loaded. Se ocorrer um erro ao carregar o suplemento do VSTO, o valor LoadBehavior será alterado para 8.If an error occurs when loading the VSTO Add-in, the LoadBehavior value changes to 8.
1616 CarregadoLoaded Carregar pela primeira vez e carregar sob demandaLoad first time, then load on demand Defina esse valor se desejar que seu suplemento do VSTO seja carregado sob demanda.Set this value if you want your VSTO Add-in to be loaded on demand. O aplicativo carrega o suplemento do VSTO quando o usuário executa o aplicativo pela primeira vez.The application loads the VSTO Add-in when the user runs the application for the first time. Na próxima vez que o usuário executar o aplicativo, o aplicativo carregará todos os elementos da interface do usuário que são definidos pelo suplemento do VSTO, mas o suplemento do VSTO não será carregado até que o usuário clique em um elemento de interface de usuário associado ao suplemento do VSTO.The next time the user runs the application, the application loads any UI elements that are defined by the VSTO Add-in, but the VSTO Add-in is not loaded until the user clicks a UI element that is associated with the VSTO Add-in.

Quando o aplicativo carrega o suplemento do VSTO com êxito pela primeira vez, o valor LoadBehavior permanece 16 enquanto o suplemento do VSTO é carregado.When the application successfully loads the VSTO Add-in for the first time, the LoadBehavior value remains 16 while the VSTO Add-in is loaded. Depois que o aplicativo é fechado, o valor LoadBehavior muda para 9.After the application closes, the LoadBehavior value changes to 9.

Confira tambémSee also