Arquitectura de las personalizaciones de nivel de documento

Actualización: noviembre 2007

Se aplica a
La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados. Tipo de proyecto Proyectos de nivel de documento Versión de Microsoft Office Microsoft Office System 2007 Microsoft Office 2003 Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

Visual Studio Tools para Office incluye proyectos para crear personalizaciones de nivel de documento en Microsoft Office Word y Microsoft Office Excel. En este tema se describen los aspectos siguientes de las personalizaciones de Visual Studio Tools para Office:

• Introducción a las personalizaciones

• Componentes de las personalizaciones

• Cómo funcionan las personalizaciones con Microsoft Office System 2007

• Cómo funcionan las personalizaciones con Microsoft Office 2003

Para obtener información general acerca de cómo se utilizan las personalizaciones de Visual Studio Tools para Office, vea Información general sobre el desarrollo de soluciones de Office, Introducción a la programación de personalizaciones de nivel de documento para Word y Introducción a la programación de personalizaciones de nivel de documento para Excel.

Introducción a las personalizaciones

Cuando genera una personalización con Visual Studio Tools para Office, crea un ensamblado de código administrado que está asociado con un documento concreto. De los documentos o libros que tienen un ensamblado vinculado se dice que tienen extensiones de código administrado. Para obtener más información, vea Información general sobre los ensamblados en las soluciones de Office.

Cuando un usuario abre el documento, la aplicación de Microsoft Office carga el ensamblado. Una vez cargado el ensamblado, la personalización puede responder a los eventos mientras el documento está abierto. La personalización también puede llamar al modelo de objetos para automatizar y extender la aplicación mientras el documento está abierto y puede utilizar cualquiera de las clases de .NET Framework.

El ensamblado se comunica con los componentes COM de la aplicación a través del ensamblado de interoperabilidad primario de la aplicación. Para obtener más información, consulte Ensamblados de interoperabilidad primarios de Office y Información general sobre el desarrollo de soluciones de Office.

Visual Studio Tools para Office carga cada ensamblado en un dominio de aplicación diferente. Esto significa que una solución que manifiesta un comportamiento incorrecto no provoca errores en otras soluciones. También garantiza que cuando se cierra el documento, se cierra todo el código y los ensamblados se descargan de la memoria. Las personalizaciones de nivel de documento están diseñadas para trabajar con un único documento en un único dominio de aplicación. No están diseñados para la comunicación entre documentos. Para obtener más información sobre dominios de aplicación, vea Información general sobre dominios de aplicación.

Nota:
Las personalizaciones de nivel de documento que se crean con Visual Studio Tools para Office están diseñadas para utilizarse exclusivamente cuando la aplicación la inicia un usuario final. Si la aplicación se inicia mediante programación (por ejemplo, utilizando Automatización), es posible que la personalización no funcione según lo previsto.

Experiencias en tiempo de diseño y en tiempo de ejecución

Comprender la arquitectura de las soluciones de Visual Studio Tools para Office, ayuda a entender la experiencia que supone diseñar y ejecutar una solución.

Tiempo de diseño

La experiencia en tiempo de diseño incluye los pasos siguientes:

1. El desarrollador crea un proyecto de nivel de documento en Visual Studio. El proyecto incluye el documento y el ensamblado que se ejecuta en el documento. Puede utilizarse un documento existente (posiblemente creado por un diseñador) o puede crearse un documento junto con el proyecto.

2. El diseñador (ya sea el desarrollador que crea el proyecto o cualquier otro profesional) define la apariencia y el estilo finales del documento para el usuario final.

Tiempo de ejecución

La experiencia en tiempo de ejecución incluye los pasos siguientes:

1. El usuario final abre un documento o libro que tiene extensiones de código administrado.

2. El documento o el libro carga el ensamblado compilado.

3. El ensamblado responde a los eventos cuando el usuario trabaja en el documento o libro.

Comparación de las perspectivas del desarrollador y el usuario final

Dado que el programador trabaja principalmente en Visual Studio y el usuario final trabaja en Word o Excel, hay dos maneras de entender las personalizaciones de nivel de documento.

Perspectiva del desarrollador

Perspectiva del usuario final

Mediante el uso de Visual Studio, el desarrollador escribe código que es accesible tanto para Word como para Excel. Aunque pudiera parecer que el desarrollador está creando un archivo ejecutable que ejecuta Word o Excel, el proceso funciona realmente al contrario. El documento se asocia a un ensamblado y contiene un puntero a dicho ensamblado. Cuando el documento se abre, Word o Excel buscan el ensamblado y ejecutan el código en respuesta a todos los eventos controlados.

Las personas que utilizan la solución se limitan a abrir el documento o el libro (o a crear un nuevo documento a partir de una plantilla) del mismo modo que abrirían cualquier otro archivo de Microsoft Office. El ensamblado aporta personalizaciones al documento o al libro como, por ejemplo, rellenar uno u otro con los datos actuales o mostrar un cuadro de diálogo para solicitar información.

Formatos de documento admitidos para las personalizaciones de nivel de documento

Cuando crea un proyecto de personalización, puede elegir el formato del documento que desea utilizar en el proyecto. Para obtener más información, vea Cómo: Crear proyectos de Visual Studio para Office.

En la tabla siguiente se enumeran los formatos de documento que se pueden utilizar en las personalizaciones de nivel de documento de Excel.

Excel 2007	Excel 2003
Libro de Excel (.xlsx) Libro de Excel habilitado para macros (.xlsm) Libro binario de Excel (.xlsb) Libro de Excel 97-2003 (.xls) Plantilla de Excel (.xltx) Plantilla de Excel habilitada para macros (.xltm) Plantilla de Excel 97-2003 (.xlt)	Libro de Excel (.xls) Plantilla de Excel (.xlt)

En la tabla siguiente se enumeran los formatos de documento que se pueden utilizar en las personalizaciones de nivel de documento de Word.

Word 2007	Word 2003
Documento de Word (.docx) Documento de Word habilitado para macros (.docm) Documento de Word 97-2003 (.doc) Plantilla de Word (.dotx) Plantilla de Word habilitada para macros (.dotm) Plantilla de Word 97-2003 (.dot)	Documento de Word (.doc) Plantilla de Word (.dot)

Si basa una personalización de Microsoft Office 2007 en un documento creado en Microsoft Office 2003, Visual Studio Tools para Office no cambia el formato de archivo del documento.

Debe diseñar extensiones de código administrado sólo para documentos que tengan el formato admitido. De lo contrario, no se podrían provocar ciertos eventos al abrirse el documento en la aplicación. Por ejemplo, el evento Open no se provoca cuando se utilizan extensiones de código administrado con libros guardados en formato de hoja de cálculo XML de Excel o en formato de página web (.htm; .html).

Compatibilidad con documentos de Word que tienen extensiones de nombre de archivo .xml

Las plantillas de proyecto de nivel de documento de Word 2003 y Word 2007 no permiten crear proyectos basados en los formatos de archivo siguientes:

• Documento XML de Word (*xml).

• Documento XML de Word 2003 (*xml).

Si desea que los usuarios finales utilicen las personalizaciones en estos formatos de archivo, genere e implemente una personalización que utilice uno de los formatos de archivo compatibles especificados en la tabla anterior. Después de instalar la personalización, los usuarios finales pueden guardar el documento en el formato Documento XML de Word (*xml) en Word 2007 o Documento XML de Word 2003 (*xml) en Word 2003 y la personalización continuará funcionando del modo esperado.

Componentes de las personalizaciones

Los componentes principales de una personalización son el documento y el ensamblado. Además de estos componentes, hay otros elementos que representan un papel importante en el modo en que las aplicaciones de Microsoft Office detectan y cargan las personalizaciones.

Manifiesto de implementación y manifiesto de aplicación

Las personalizaciones utilizan manifiestos de implementación y manifiestos de aplicación para identificar y cargar la versión más reciente del ensamblado de personalización. El manifiesto de implementación apunta al manifiesto de la aplicación actual. El manifiesto de aplicación señala al ensamblado de personalización y especifica la clase (o clases) de punto de entrada que se van a ejecutar en el ensamblado. Para obtener más información, consulte Manifiestos de implementación y aplicación en soluciones de Office.

Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office

Para ejecutar personalizaciones creadas con Visual Studio Tools para Office, los equipos de usuario final deben tener instalado el motor en tiempo de ejecución de Visual Studio Tools para Office. El motor en tiempo de ejecución de Visual Studio Tools para Office incluye componentes no administrados que cargan el ensamblado de personalización además de un conjunto de ensamblados administrados. Estos ensamblados administrados proporcionan el modelo de objetos que utiliza el código de la personalización para automatizar y extender la aplicación host.

Para obtener más información, consulte Información general sobre el motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office.

Cómo funcionan las personalizaciones con Microsoft Office System 2007

Cuando un usuario abre un documento que forma parte de una personalización de Microsoft Office 2007, la aplicación utiliza el manifiesto de implementación vinculado al documento para buscar y cargar la versión más reciente del ensamblado de personalización. La ubicación del manifiesto de implementación está almacenada en una propiedad de documento personalizada denominada _AssemblyLocation. La cadena que identifica esta ubicación se inserta en la propiedad cuando se genera la solución.

El manifiesto de implementación señala al manifiesto de aplicación, que apunta al ensamblado más reciente. Para obtener más información, consulte Manifiestos de implementación y aplicación en soluciones de Office.

En la ilustración siguiente se muestra la arquitectura básica de una personalización de un documento de Microsoft Office System 2007.

Arquitectura de personalización en Microsoft Office System 2007

Proceso de carga de las personalizaciones de Microsoft Office System 2007

Los pasos siguientes tienen lugar cuando un usuario abre un documento que forma parte de una solución de Microsoft Office 2007:

1. La aplicación de Microsoft Office comprueba las propiedades de documento personalizadas para ver si son extensiones de código administrado asociadas al documento. Para obtener más información, consulte Información general sobre propiedades personalizadas del documento.

2. Si hay extensiones de código administrado, la aplicación carga VSTOEE.dll, que a su vez carga VSTOLoader.dll. Se trata de archivos DLL no administrados que son los componentes del cargador del Microsoft Visual Studio Tools para Microsoft Office System (versión 3.0 Runtime). Para obtener más información, consulte Información general sobre el motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office.

3. VSTOLoader.dll carga .NET Framework e inicia la parte administrada del motor en tiempo de ejecución de Visual Studio Tools para Office.

4. Si el documento se abre desde una ubicación que no se encuentra en el equipo local, el motor en tiempo de ejecución de Visual Studio Tools para Office comprueba que la ubicación del documento está en la lista Ubicaciones de confianza de Configuración del Centro de confianza de esa aplicación de Office en particular. Si la ubicación del documento no es una ubicación de confianza, no se confía en la personalización y el proceso de carga se detiene en ese punto.

5. El motor en tiempo de ejecución de Visual Studio Tools para Office instala la solución si aún no se ha instalado, descarga los manifiestos de aplicación e implementación más recientes y realiza una serie de comprobaciones de seguridad. Para obtener más información, consulte Seguridad en las soluciones de Office (2007 System).

6. Si se confía en la personalización para que se ejecute, el motor en tiempo de ejecución de Visual Studio Tools para Office utiliza los manifiestos de implementación y aplicación para buscar actualizaciones del ensamblado. Si una nueva versión del ensamblado está disponible, el motor en tiempo de ejecución descarga la nueva versión del ensamblado en la memoria caché de ClickOnce del equipo cliente. Para obtener más información, consulte Implementar soluciones de Office (2007 System).

7. El motor en tiempo de ejecución de Visual Studio Tools para Office crea un nuevo dominio de aplicación en el que se carga el ensamblado de personalización.

8. El motor en tiempo de ejecución de Visual Studio Tools para Office carga el ensamblado de personalización en el nuevo dominio de aplicación.

9. El motor en tiempo de ejecución de Visual Studio Tools para Office llama al controlador de eventos Startup en el ensamblado de personalización. Para obtener más información, consulte Eventos de proyectos de Visual Studio Tools para Office.

Cómo funcionan las personalizaciones con Microsoft Office 2003

Cuando un usuario abre un documento que forma parte de una personalización de Microsoft Office 2003, la aplicación utiliza el manifiesto de aplicación que está incrustado en el documento para buscar y cargar la versión más reciente del ensamblado de personalización. El manifiesto de aplicación incrustado puede señalar directamente al ensamblado o puede señalar a un manifiesto de implementación que se utilice para buscar actualizaciones del ensamblado. Para obtener más información, consulte Manifiestos de implementación y aplicación en soluciones de Office.

El manifiesto de aplicación incrustado está incluido en un control incrustado no visible que se denomina Control de almacenamiento en tiempo de ejecución. Para obtener más información, vea Información general acerca del control de almacenamiento del motor en tiempo de ejecución.

En la ilustración siguiente se muestra la arquitectura básica de una personalización de un documento de Microsoft Office System 2003.

Arquitectura de la personalización en Microsoft Office 2003

Proceso de carga de las personalizaciones en Microsoft Office 2003

Los pasos siguientes tienen lugar cuando un usuario abre un documento que forma parte de una solución de Microsoft Office 2003:

1. La aplicación de Microsoft Office comprueba las propiedades de documento personalizadas para ver si son extensiones de código administrado asociadas al documento. Para obtener más información, consulte Información general sobre propiedades personalizadas del documento.

2. Si hay extensiones de código administrado, la aplicación carga AddinLoader.dll. Se trata de un archivo DLL no administrado que es el componente de carga de Visual Studio 2005 Tools para Office Second Edition runtime. Para obtener más información, consulte Información general sobre el motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office.

3. AddinLoader.dll carga .NET Framework e inicia la parte administrada del motor en tiempo de ejecución de Visual Studio Tools para Office.

4. El motor en tiempo de ejecución de Visual Studio Tools para Office crea un dominio de aplicación, establece la directiva del dominio de aplicación para no confiar en la zona de Mi PC y comprueba el almacén de directivas de seguridad de acceso del código para buscar una directiva para el ensamblado de personalización.

5. .NET Framework valida las pruebas presentadas por el ensamblado respecto a la directiva. Si no se cumple, se genera un error. Si la validación es correcta, el proceso continúa.

6. Si la personalización utiliza un manifiesto de implementación, el motor en tiempo de ejecución de Visual Studio Tools para Office lo utiliza para buscar actualizaciones del ensamblado. Si es necesario aplicar actualizaciones, se realizan en este momento.

7. El motor en tiempo de ejecución de Visual Studio Tools para Office carga el ensamblado en el dominio de aplicación.

8. El motor en tiempo de ejecución de Visual Studio Tools para Office llama al controlador de eventos Startup en el ensamblado de personalización. Para obtener más información, consulte Eventos de proyectos de Visual Studio Tools para Office.

Vea también

Conceptos

Arquitectura de los complementos de nivel de aplicación

Información general sobre el motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office

Crear soluciones de Office en Visual Studio

Información general sobre propiedades personalizadas del documento

Modelo de datos en las personalizaciones de nivel de documento

Información general acerca del control de almacenamiento del motor en tiempo de ejecución

Otros recursos

Arquitectura de las soluciones de Visual Studio Tools para Office

Seguridad en las soluciones de Office