Arquitectura de personalizaciones de nivel de documento

  • Artículo

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

Descripción de las personalizaciones

Si usa Office Developer Tools en Visual Studio para compilar una personalización de nivel de documento, se crea un ensamblado de código administrado que se asocia con un documento concreto. Se dice que un documento o un libro con un ensamblado vinculado dispone de extensiones de código administrado. Para obtener más información, consulte Diseño y creación de soluciones de Office.

Cuando un usuario abre el documento, la aplicación de Microsoft Office carga el ensamblado. Cuando se carga el ensamblado, la personalización puede responder a eventos mientras el documento está abierto. La personalización también puede llamar al modelo de objetos para automatizar y ampliar la aplicación mientras el documento está abierto y puede usar 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 Introducción al desarrollo de soluciones de Office (VSTO) y ensamblados de interoperabilidad primarios de Office.

Si un usuario abre varias personalizaciones de nivel de documento a la vez, cada ensamblado se carga en un dominio de aplicación distinto. Esto significa que una solución que se comporta incorrectamente no puede hacer que otras generen un error. Las personalizaciones de nivel de documento están diseñadas para trabajar con un único documento en un dominio de aplicación único. No están diseñados para una comunicación entre documentos. Para obtener más información sobre los dominios de aplicación, consulte Dominios de aplicación.

Nota:

Las personalizaciones de nivel de documento que se crean con Office Developer Tools en Visual Studio están diseñadas para usarse solo cuando un usuario final inicia la aplicación. Si la aplicación se inicia mediante programación, por ejemplo, mediante Automatización, la personalización podría no funcionar según lo esperado.

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

Para entender la arquitectura de las personalizaciones de nivel de documento, resulta útil comprender las experiencias de diseño y de ejecución de una solución.

Tiempo de diseño

En la experiencia en tiempo de diseño se incluyen 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 detrás del documento. Es posible que el documento ya exista (creado por un diseñador) o se puede crear un nuevo documento junto con el proyecto.

  2. El diseñador, ya sea el desarrollador que crea el proyecto u otra persona, crea la apariencia final del documento para el usuario final.

Tiempo de ejecución

En la experiencia en tiempo de ejecución se incluyen los pasos siguientes:

  1. El usuario final abre un documento o un 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 mientras el usuario trabaja en el documento o el libro.

Perspectiva del desarrollador y del usuario final en comparación

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

Perspectiva del desarrollador Perspectiva del usuario final
Con Visual Studio, el desarrollador escribe código accesible para Word y Excel.

Aunque pueda parecer que el programador crea un archivo ejecutable que ejecuta Word o Excel, en realidad el proceso funciona al revés. El documento se asocia a un ensamblado y contiene un puntero a ese ensamblado. Cuando se abre el documento, Word o Excel localiza el ensamblado y ejecuta el código en respuesta a todos los eventos controlados.		 Los que usan la solución simplemente abren el documento o el libro (o crean un nuevo documento desde una plantilla) de la misma forma que abrirían cualquier otro archivo de Microsoft Office.

El ensamblado ofrece personalizaciones en el documento o el libro, como rellenarlos automáticamente con datos actuales o mostrar un cuadro de diálogo para solicitar información.

Formatos de documento admitidos para 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 Office en Visual Studio.

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

Excel Word
Libro de Excel (.xlsx)

Libro habilitado para macros de Excel (.xlsm)

Libro binario de Excel (.xlsb)

Libro de Excel 97-2003 (.xls)

Plantilla de Excel (.xltx)

Plantilla habilitada para macros de Excel (.xltm)

Plantilla de Excel 97-2003 (.xlt)		 Documento de Word (.docx)

Documento habilitado para macros de Word (.docm)

Documento de Word 97-2003 (.doc)

Plantilla de Word (.dotx)

Plantilla habilitada para macros de Word (.dotm)

Plantilla de Word 97-2003 (.dot)

Debe diseñar extensiones de código administrado únicamente para los documentos en los formatos que se admiten. De lo contrario, es posible que no se generen determinados eventos si el documento se abre en la aplicación. Por ejemplo, el Open evento no se genera cuando se usan extensiones de código administrado con libros guardados en el formato de hoja de cálculo XML de Excel o en la página web (.htm; . formato html).

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

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

  • 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, compile e implemente una personalización que use uno de los formatos de archivo compatibles que se especifican en la tabla anterior. Después de instalar la personalización, los usuarios finales pueden guardar el documento en formato documento XML de Word (*xml) o en el formato documento XML de Word 2003 (*xml) y la personalización seguirá funcionando según lo previsto.

Componentes de las personalizaciones

Los componentes principales de una personalización son el documento y el ensamblado. Además de estos componentes, existen otras partes que desempeñan un papel importante en la forma en que las aplicaciones de Microsoft Office detectan y cargan personalizaciones.

Manifiesto de implementación y manifiesto de aplicación

Las personalizaciones usan 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 aplicación actual. El manifiesto de aplicación apunta al ensamblado de personalización y especifica la clase (o clases) de punto de entrada que se ejecutará en el ensamblado. Para obtener más información, vea Manifiestos de aplicación e implementación en soluciones de Office.

Visual Studio Tools para Office Runtime

Para ejecutar personalizaciones de nivel de documento creadas mediante las herramientas de desarrollo de Office en Visual Studio, los equipos de usuario final deben tener instalado el entorno de ejecución de Visual Studio Tools para Office. El entorno de ejecución de Visual Studio Tools para Office incluye componentes no administrados que cargan el ensamblado de personalización y también un conjunto de ensamblados administrados. Estos ensamblados administrados proporcionan el modelo de objetos que el código de personalización usa para automatizar y extender la aplicación host.

Para obtener más información, vea Visual Studio Tools for Office runtime overview (Información general del entorno de ejecución de Visual Studio para Office).

Cómo funcionan las personalizaciones con aplicaciones de Microsoft Office

Cuando un usuario abre un documento que forma parte de una personalización de Microsoft Office, la aplicación utiliza el manifiesto de implementación que está 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 se almacena en una propiedad de documento personalizada denominada AssemblyLocation. La cadena que identifica esta ubicación se inserta en la propiedad cuando se compila la solución.

El manifiesto de implementación apunta al manifiesto de aplicación, que a su vez apunta al ensamblado más actual. Para obtener más información, vea Manifiestos de aplicación e implementación en soluciones de Office.

En la ilustración siguiente se muestra la arquitectura básica de una personalización de nivel de documento.

2007 Office customization architecture

Nota:

En las soluciones de Office que tienen como destino .NET Framework 4, las soluciones llaman al modelo de objetos de la aplicación host mediante la información de tipo del ensamblado de interoperabilidad principal (PIA) incrustada en el ensamblado de la solución, en lugar de llamar directamente al PIA. Para obtener más información, consulte Diseño y creación de soluciones de Office.

Proceso de carga

Los pasos siguientes se producen cuando un usuario abre un documento que forma parte de una solución de Microsoft Office.

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

  2. Si hay extensiones de código administrado, la aplicación carga VSTOEE.dll, que carga VSTOLoader.dll. Estos son archivos DLL no administrados que son los componentes del cargador para el entorno de ejecución de Visual Studio 2010 Tools para Office. Para obtener más información, consulte Visual Studio Tools para Office información general del entorno de ejecución.

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

  4. Si el documento se abre desde una ubicación distinta del equipo local, el entorno de ejecución de Visual Studio Tools para Office comprueba que la ubicación del documento se encuentra en la lista Ubicaciones de confianza del Centro de confianza Configuración para ese aplicación de Office lication determinado. Si la ubicación del documento no está en una ubicación de confianza, la personalización no es de confianza y el proceso de carga se detiene ahí.

  5. El entorno de ejecución de Visual Studio Tools para Office instala la solución si aún no se ha instalado, descarga los manifiestos de implementación y la aplicación más recientes y realiza una serie de comprobaciones de seguridad. Para obtener más información, consulte Soluciones seguras de Office.

  6. Si la personalización es de confianza para ejecutarse, el entorno de ejecución de Visual Studio Tools para Office usa el manifiesto de implementación y el manifiesto de aplicación para comprobar si hay actualizaciones de ensamblado. Si hay disponible una nueva versión del ensamblado, el entorno de ejecución descarga la nueva versión del ensamblado en la caché clickOnce en el equipo cliente. Para obtener más información, vea Implementar una solución de Office.

  7. El entorno 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 Visual Studio Tools para Office tiempo de ejecución carga el ensamblado de personalización en el dominio de aplicación.

  9. El entorno 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, vea Eventos en proyectos de Office.

Contenido relacionado