Entradas del registro para complementos de VSTO

  • Artículo

Debe crear un conjunto específico de entradas del registro al implementar complementos de VSTO creados con Visual Studio. Dichas entradas del registro proporcionan información que permite que la aplicación de Microsoft Office detecte y cargue el complemento de VSTO.

Se aplica a: La información de este tema se aplica a los proyectos de complemento de VSTO. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

Nota:

¿Le interesa desarrollar soluciones que amplíen la experiencia de Office en varias plataformas? Consulte el nuevo modelo de complementos de Office. Los complementos de Office tienen una superficie pequeña en comparación con los complementos y soluciones de VSTO, y puede compilarlos mediante casi cualquier tecnología de programación web, como HTML5, JavaScript, CSS3 y XML.

Al compilar el proyecto, Visual Studio crea estas entradas del Registro en el equipo de desarrollo. Esto le ayuda a ejecutar y depurar fácilmente el complemento VSTO. Con ClickOnce para implementar el complemento de VSTO, las entradas del Registro se crean automáticamente en el equipo del usuario final.

Para obtener más información sobre cómo implementar una solución de VSTO mediante Windows Installer, consulte Implementación de una solución VSTO mediante Windows Installer.

Para obtener más información acerca de cómo se usan las entradas de registro durante el proceso de carga de los complementos VSTO, consulte Architecture of VSTO Add-ins.

Nota:

En este tema, el texto Identificador de complemento es un identificador único para el complemento de VSTO. De forma predeterminada, el identificador es el nombre del ensamblado del complemento de VSTO.

Registrar complementos de VSTO para el usuario actual frente a todos los usuarios

Cuando se instala un complemento de VSTO, se puede registrar de dos formas:

  • Solo para el usuario actual (el complemento VSTO solo está disponible para el usuario que inició sesión en el equipo cuando se instaló el complemento). En este caso, las entradas del Registro se crean en el HKEY_CURRENT_USER.

  • Para todos los usuarios (es decir, cualquier usuario que inicie sesión en el equipo puede usar el complemento VSTO). En este caso, las entradas del Registro se crean en HKEY_LOCAL_MACHINE.

    Todos los complementos de VSTO que cree mediante Visual Studio pueden registrarse para el usuario actual. Sin embargo, los complementos de VSTO pueden registrarse para todos los usuarios solo en determinados escenarios. Estos escenarios dependen de la versión de Microsoft Office del equipo y de cómo se implementó el complemento de VSTO.

Tipo de implementación

Si usa ClickOnce para implementar un complemento de VSTO, el complemento de VSTO se puede registrar únicamente para el usuario actual. Esto se debe a que ClickOnce solo admite la creación de claves en HKEY_CURRENT_USER. Si desea registrar un complemento de VSTO para todos los usuarios de un equipo, debe usar Windows Installer para implementarlo. Para obtener más información sobre estos tipos de implementación, vea Implementar una solución de Office mediante ClickOnce e Implementar una solución de Office mediante Windows Installer.

Entradas del registro

Las entradas del Registro de complementos de VSTO necesarias se encuentran en las siguientes claves del Registro donde Root se HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE dependiendo de si la instalación es para el usuario actual o para todos los usuarios.

Aplicación de Office Ruta de acceso de configuración
Visio Root\Software\Microsoft\Visio\Addins\add-in ID
Todo el resto Root\Software\Microsoft\Office\aplicación de Office lication name\Addins\add-in ID

Nota:

Si el instalador tiene como destino todos los usuarios en Windows de 64 bits, se recomienda que incluya dos entradas del Registro, una en la HKEY_LOCAL_MACHINE\Software\Microsoft y otra en el subárbol HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft. Esto se debe a que es posible que los usuarios usen versiones de 32 o 64 bits de Office en el equipo.

Si el instalador tiene como destino el usuario actual, no es necesario instalarlo en WOW6432Node porque se comparte la ruta de acceso de HKEY_CURRENT_USER\Software.

Para obtener más información, consulte Datos de aplicación de 32 y 64 bits en el Registro.

En la tabla siguiente se enumeran las entradas que figuran en esta clave del Registro.

Entrada Tipo Valor
Descripción REG_SZ Necesario. Breve descripción del complemento de VSTO.

Esta descripción se muestra cuando el usuario selecciona el complemento de VSTO en el panel Complementos del cuadro de diálogo Opciones de la aplicación de Microsoft Office.
FriendlyName REG_SZ Necesario. Nombre descriptivo del complemento de VSTO que se muestra en el cuadro de diálogo Complementos COM de la aplicación de Microsoft Office. El valor predeterminado es el identificador del complemento de VSTO.
LoadBehavior REG_DWORD Necesario. Valor que especifica cuándo la aplicación intenta cargar el complemento de VSTO y el estado actual del complemento de VSTO (cargado o sin cargar).

De forma predeterminada, esta entrada se establece en 3, lo que especifica que el complemento de VSTO se carga al inicio. Para obtener más información, consulte Valores de LoadBehavior.

Nota: Si un usuario deshabilita el complemento VSTO, esa acción modifica el valor LoadBehavior en el subárbol del registro de HKEY_CURRENT_USER . Para cada usuario, el valor del valor LoadBehavior en el HKEY_CURRENT_USER hive invalida el loadBehavior predeterminado definido en el subárbol de HKEY_LOCAL_MACHINE.
Manifiesto REG_SZ Necesario. Ruta de acceso completa del manifiesto de implementación para el complemento de VSTO. La ruta de acceso puede ser una ubicación en el equipo local, un recurso compartido de red (UNC) o un servidor web (HTTP).

Si usa Windows Installer para implementar la solución, debe agregar el prefijo file:/// a la ruta de acceso del manifiesto . También debe anexar la cadena |vstolocal (es decir, el carácter | de canalización seguido de vstolocal) al final de esta ruta de acceso. Esto garantiza que la solución se cargue desde la carpeta de instalación, no desde la memoria caché de ClickOnce. Para obtener más información, vea Implementar una solución de Office mediante Windows Installer.

Nota: Al compilar un complemento de VSTO en el equipo de desarrollo, Visual Studio anexa automáticamente la cadena |vstolocal a esta entrada del Registro.

Entradas del Registro para las áreas del formulario de Outlook

Si crea un área del formulario personalizada en un complemento de VSTO para Outlook, se usarán entradas del registro adicionales para registrar dicha área en Outlook. Estas entradas se crean en una clave del Registro diferente para cada clase de mensaje que sea compatible con el área del formulario. Estas claves del Registro se encuentran en la siguiente ubicación, donde Root es HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE.

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

Al igual que las demás entradas del registro compartidas por todos los complementos de VSTO, Visual Studio crea las entradas del registro de las áreas del formulario en el equipo de desarrollo al compilar el proyecto. Con ClickOnce para implementar el complemento de VSTO, las entradas del Registro se crean automáticamente en el equipo del usuario final. Al usar Windows Installer para implementar el complemento de VSTO, debe configurar el proyecto InstallShield Limited Edition para crear las entradas del Registro en el equipo del usuario final.

Para obtener más información sobre las entradas del registro del área de formulario, vea Especificar la ubicación de un área de formulario en un formulario personalizado. Para obtener más información sobre las áreas del formulario de Outlook, vea Crear áreas de formulario de Outlook.

Valores de LoadBehavior

La entrada LoadBehavior en root\Software\Microsoft\Office\application name\Addins\add-in ID contiene una combinación bit a bit de valores que especifican el comportamiento en tiempo de ejecución del complemento vsTO. El bit de ordenación más bajo (valores 0 y 1) indica si el complemento de VSTO está cargado o no. Otros bits indican el momento en que la aplicación intenta cargar el complemento de VSTO.

Normalmente, la entrada LoadBehavior está pensada para establecerse en 0, 3 o 16 (en decimal) cuando el complemento VSTO está instalado en equipos de usuario final. De forma predeterminada, Visual Studio establece la entrada LoadBehavior del complemento de VSTO en 3 al compilarlo o publicarlo.

En la siguiente tabla se enumeran todos los valores posibles de la entrada LoadBehavior . Algunas descripciones de esta tabla hacen referencia a cargar un complemento de VSTO manualmente o mediante programación. Para cargar un complemento de VSTO manualmente, active la casilla que encontrará junto al complemento de VSTO en el cuadro de diálogo Complementos COM de la aplicación. Para cargar un complemento de VSTO mediante programación, establezca la propiedad Connect del objeto COMAddIn que representa el complemento de VSTO en true.

Valor (en forma decimal) Estado del complemento de VSTO Comportamiento de carga de complementos de VSTO Descripción
0 Descargado No cargar automáticamente La aplicación nunca intenta cargar el complemento de VSTO automáticamente. El usuario puede intentar cargar manualmente el complemento de VSTO o el complemento de VSTO se puede cargar mediante programación.

Si el complemento de VSTO se carga correctamente, el valor LoadBehavior sigue siendo 0, pero el estado del complemento de VSTO en el cuadro de diálogo Complementos COM se actualiza para indicar que el complemento de VSTO está cargado.
1 Cargado No cargar automáticamente La aplicación nunca intenta cargar el complemento de VSTO automáticamente. El usuario puede intentar cargar manualmente el complemento de VSTO o el complemento de VSTO se puede cargar mediante programación.

Aunque el cuadro de diálogo Complementos COM indica que el complemento VSTO se carga después de iniciar la aplicación, el complemento vsTO no se carga hasta que se carga manual o mediante programación.

Si la aplicación carga correctamente el complemento de VSTO, el valor LoadBehavior cambia a 0 y sigue siendo 0 una vez que se cierra la aplicación.
2 Descargado Cargar al inicio La aplicación no intenta cargar automáticamente el complemento VSTO. El usuario puede intentar cargar manualmente el complemento de VSTO o el complemento de VSTO se puede cargar mediante programación.

Si la aplicación carga correctamente el complemento de VSTO, el valor LoadBehavior cambia a 3 y sigue siendo 3 una vez que se cierra la aplicación.
3 Cargado Cargar al inicio La aplicación intenta cargar el complemento de VSTO cuando se inicia la aplicación. Este es el valor predeterminado al compilar o publicar un complemento de VSTO en Visual Studio.

Si la aplicación carga correctamente el complemento de VSTO, el valor LoadBehavior sigue siendo 3. Si se produce un error al cargar el complemento de VSTO, el valor LoadBehavior cambia a 2 y sigue siendo 2 una vez que se cierra la aplicación.
8 Descargado Cargar a petición La aplicación no intenta cargar automáticamente el complemento VSTO. El usuario puede intentar cargar manualmente el complemento de VSTO o el complemento de VSTO se puede cargar mediante programación.

Si la aplicación carga correctamente el complemento de VSTO, el valor LoadBehavior cambia a 9.
9 Cargado Cargar a petición El complemento VSTO solo se cargará cuando la aplicación lo requiera. Por ejemplo, cuando un usuario selecciona un elemento de interfaz de usuario que usa la funcionalidad en el complemento VSTO (por ejemplo, un botón personalizado en la cinta de opciones).

Si la aplicación carga el complemento de VSTO correctamente, el valor LoadBehavior sigue siendo 9, pero el estado del complemento de VSTO en el cuadro de diálogo Complementos COM se actualiza para indicar que el complemento de VSTO está cargado. Si se produce un error al cargar el complemento de VSTO, el valor LoadBehavior cambia a 8.
16 Cargado Cargar la primera vez y, a continuación, cargar a petición Establezca este valor si desea que el complemento de VSTO se cargue según demanda. La aplicación carga el complemento de VSTO cuando el usuario ejecuta la aplicación por primera vez. La próxima vez que el usuario ejecute la aplicación, la aplicación carga todos los elementos de la interfaz de usuario definidos por el complemento VSTO. Sin embargo, el complemento VSTO no se carga hasta que el usuario selecciona un elemento de interfaz de usuario asociado al complemento VSTO.

Cuando la aplicación carga correctamente el complemento de VSTO por primera vez, el valor LoadBehavior sigue siendo 16 mientras el complemento de VSTO esté cargado. Después de cerrar la aplicación, el valor LoadBehavior cambia a 9.

Contenido relacionado