Información general sobre elementos y controles Host

Artículo
08/10/2011

Los elementos host y los controles host son tipos que ayudan a proporcionar el modelo de programación para las soluciones de Office que se crean con las herramientas de desarrollo de Office en Visual Studio. Los elementos host y los controles host hacen que la interacción con los modelos de objetos de Microsoft Office Word y Microsoft Office Excel, que están basados en COM, sea más similar a la interacción con objetos administrados como los controles de Windows Forms.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento y los proyectos de nivel de aplicación para las siguientes aplicaciones: Excel 2007 y Excel 2010; Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Elementos host

Los elementos host son tipos que están en la parte superior de las jerarquías de los modelos de objetos en los proyectos de Office. El Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office define los siguientes elementos host para soluciones de Word y Excel:

Cada uno de estos tipos extiende un objeto que existe de manera nativa en el modelo de objetos de Word o Excel (denominado objeto de Office nativo). Por ejemplo, el elemento host Microsoft.Office.Tools.Word.Document extiende el objeto Microsoft.Office.Interop.Word.Document, que se define en el ensamblado de interoperabilidad primario para Word.

Los elementos host tienen, generalmente, la misma funcionalidad básica que los objetos de Office correspondientes, pero están mejorados con las características siguientes:

Capacidad de hospedar controles host administrados, incluidos los controles host y los controles de formularios Windows Forms.
Modelos de eventos más completos. Algunos eventos de documento, libro y hoja de cálculo de los modelos de objetos nativos de Word y de Excel solo se provocan en el nivel de la aplicación. Los elementos host proporcionan estos eventos en el nivel del documento, para que sea más fácil controlar los eventos para un documento concreto.

Comprender los elementos host de proyectos en el nivel del documento

En los proyectos en el nivel del documento, los elementos host proporcionan un punto de entrada para el código y tienen diseñadores que ayudan a desarrollar la solución.

Los elementos host Microsoft.Office.Tools.Word.Document y Microsoft.Office.Tools.Excel.Worksheet tienen asociados diseñadores que son la representación visual del documento o de la hoja de cálculo, como un diseñador de Windows Forms. Puede utilizar este diseñador para modificar directamente el contenido del documento en Word o de la hoja de cálculo en Excel, y para arrastrar los controles a la superficie de diseño. Para obtener más información, consulte Elemento host Document y Elemento host Worksheet.

El elemento host Microsoft.Office.Tools.Excel.Workbook no actúa como un contenedor para los controles que tienen interfaz de usuario. En cambio, el diseñador de este elemento host funciona como una bandeja de componentes que permite arrastrar un componente, como DataSet, a la superficie de diseño. Para obtener más información, consulte Elemento host Workbook.

No pueden crearse elementos host mediante programación en los proyectos en el nivel del documento. En su lugar, utilice las clases ThisDocument, ThisWorkbook o Sheetn que Visual Studio genera automáticamente en tiempo de diseño en el proyecto. Estas clases generadas se derivan de los elementos host y proporcionan un punto de entrada para el código. Para obtener más información, vea Limitaciones de programación de elementos y controles Host.

Comprender los elementos host de proyectos en el nivel de la aplicación

Al crear un complemento en el nivel de la aplicación, no tiene acceso a los elementos host de forma predeterminada. Sin embargo, puede generar en tiempo de ejecución elementos host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook y Microsoft.Office.Tools.Excel.Worksheet en los complementos de Word y Excel.

Después de generar un elemento host, puede hacer tareas como agregar controles a los documentos y crear etiquetas inteligentes que se reconocen en un documento concreto. Para obtener más información, vea Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución.

Nota

Las etiquetas inteligentes están desusadas en Excel 2010 y Word 2010. Para obtener más información, vea Información general sobre etiquetas inteligentes.

Controles de host

Los controles host amplían varios objetos de la interfaz de usuario en los modelos de objetos de Excel y Word, como los objetos Microsoft.Office.Interop.Excel.Range y Microsoft.Office.Interop.Word.ContentControl.

Los controles host siguientes están disponibles con proyectos de Excel:

Los controles host siguientes están disponibles con proyectos de Word:

Los controles host agregados a los documentos de Office se comportan como los objetos nativos de Office; sin embargo, los controles host poseen funcionalidad adicional que incluye eventos y capacidades de enlace a datos. Por ejemplo, cuando desea capturar los eventos de un objeto Microsoft.Office.Interop.Excel.Range nativo en Excel, en primer lugar debe administrar el evento de cambio de la hoja de cálculo. A continuación debe determinar si el cambio se produjo dentro de los intervalos Microsoft.Office.Interop.Excel.Range. En cambio, el control host Microsoft.Office.Tools.Excel.NamedRange tiene un evento Change que se puede administrar directamente.

La relación entre un elemento host y los controles host es muy parecida a la relación entre un formulario Windows Forms y los controles de formularios Windows Forms. Igual que colocaría un control de cuadro de texto en un formulario Windows Forms, puede colocar un control Microsoft.Office.Tools.Excel.NamedRange en un elemento host Microsoft.Office.Tools.Excel.Worksheet. En la ilustración siguiente se muestra la relación entre los elementos host y los controles host.

Relación entre elementos de host y controles de host

Asimismo, puede utilizar controles de Windows Forms en las soluciones de Office agregándolos directamente a la superficie del documento de Word y Excel. Para obtener más información, consulte Información general sobre controles de formularios Windows Forms en documentos de Office.

Nota

No se pueden agregar controles host ni controles de formularios Windows Forms a un subdocumento de Word.

Agregar controles host a sus documentos

En proyectos en el nivel del documento, puede agregar en tiempo de diseño los controles host a los documentos de Word o a las hojas de cálculo de Excel de las maneras siguientes:

Agregue los controles host al documento en tiempo de diseño de la misma manera que agregaría un objeto nativo.
Arrastre los controles host desde el Cuadro de herramientas hasta los documentos y hojas de cálculo. Los controles host de Excel están disponibles en la ficha Controles de Excel en los proyectos de Excel, mientras que los controles host de Word se encuentran en la ficha Controles de Word en los proyectos de Word.
Arrastre los controles host desde la ventana Orígenes de datos hasta los documentos y hojas de cálculo. Esto permite agregar controles ya enlazados a datos. Para obtener más información, vea Enlazar datos a controles en soluciones de Office.

En proyectos de nivel de documento y de aplicación, también puede agregar algunos controles host a los documentos en tiempo de ejecución. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Para obtener más información sobre cómo agregar controles host a los documentos, vea los temas siguientes:

Nombres de los controles host

Si arrastra un control host desde el Cuadro de herramientas hasta el documento, se asignará automáticamente al control un nombre en el que se utiliza el tipo de control y un número incremental al final. Por ejemplo, los marcadores se denominan bookmark1, bookmark2, etc. Si utiliza la funcionalidad nativa de Word o Excel para agregar el control, puede darle un nombre específico en el momento de crearlo. También es posible cambiar el nombre de los controles cambiando el valor de la propiedad Name en la ventana Propiedades.

Nota

No puede utilizar palabras reservadas como nombre de los controles host. Por ejemplo, si agrega un control NamedRange a una hoja de cálculo y le cambia el nombre a System, se producirán errores cuando genere el proyecto.

Eliminar controles host

En la mayoría de los proyectos en el nivel del documento, los controles host se pueden eliminar en tiempo de diseño seleccionando el control en la hoja de cálculo de Excel o en el documento de Word y presionando la tecla SUPR. Sin embargo, se debe utilizar el cuadro de diálogo Definir nombre en Excel para eliminar controles NamedRange. Para obtener más información, consulte How to: Delete NamedRange Controls at Design Time.

Si agrega un control host a un documento en tiempo de diseño, no debe quitarlo mediante programación en tiempo de ejecución porque la próxima vez que intente utilizar el control en el código, se produce una excepción. El método Delete de un control host sólo quita controles host agregados al documento en tiempo de ejecución. Si llama al método Delete de un control host creado en tiempo de diseño, se produce una excepción.

Por ejemplo, el método Delete de una NamedRange solo elimina correctamente el NamedRange si se agregó mediante programación a la hoja de cálculo, lo que se conoce como crear controles host dinámicamente. Los controles host creados dinámicamente también pueden quitarse pasando el nombre del control al método Remove de la propiedad Worksheet.Controls o Document.Controls. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Si los usuarios finales eliminan un control host del documento en tiempo de ejecución, se podrían producir errores inesperados en la solución. Es posible utilizar las características de protección de documentos de Word y Excel para evitar que se eliminen los controles host. Para obtener más información, vea Ejemplos y tutoriales del desarrollo de Office.

Nota

No quite controles mediante programación durante el funcionamiento del controlador de eventos Shutdown del documento o de la hoja de cálculo. Los elementos de la interfaz de usuario dejan de estar disponibles cuando se produce el evento Shutdown. Si desea quitar controles antes de que se cierre la aplicación, agregue su código a otro controlador de eventos como BeforeClose o BeforeSave.

Programar basándose en eventos de controles host

Una manera en que los controles host extienden los objetos de Office es agregando eventos. Por ejemplo, el objeto Microsoft.Office.Interop.Excel.Range de Excel y el objeto Microsoft.Office.Interop.Word.Bookmark de Word no tienen eventos, pero el Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office extiende estos objetos agregando eventos programables. Puede obtener acceso a estos eventos y escribir código basado en ellos de la misma manera que tiene acceso a los eventos de controles de formularios Windows Forms: a través de la lista desplegable de eventos en Visual Basic y la página de propiedades de eventos en C#. Para obtener más información, vea Tutorial: Programar basándose en los eventos de un control NamedRange.

Nota

No debe establecer la propiedad EnableEvents del objeto Application de Excel en false. Establecer esta propiedad en false impide que Excel active cualquier evento, incluidos los evento de los controles host.