Información general sobre los elementos host y los controles host
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. Tales elementos y controles hacen que la interacción con los modelos de objetos de Microsoft Office Word y Microsoft Office Excel, que se basan en COM, sea más similar a la interacción con objetos administrados como, por ejemplo, los controles de Windows Forms.
Se aplica a: La información de este tema se aplica a proyectos de nivel de documento y proyectos de complementos de VSTO para Excel y Word. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.
Elementos host
Los elementos host son tipos que están en la parte superior de las jerarquías del modelo de objetos en los proyectos de Office. El entorno de ejecución de Visual Studio Tools para Office define los siguientes elementos host para las soluciones de Word y Excel:
-
Cada uno de estos tipos extiende un objeto que existe de forma nativa en el modelo de objetos de Word o Excel, denominado un objeto nativo de Office. Por ejemplo, el elemento host Document extiende el objeto Document , que se define en el ensamblado de interoperabilidad primario para Word.
Los elementos host generalmente tienen la misma funcionalidad básica que los objetos de Office correspondientes, pero están mejorados con las características siguientes:
La capacidad de hospedar controles administrados, incluidos los controles host y controles de Windows Forms.
Modelos de eventos más completo. Algunos eventos de documento, libro y hoja de cálculo de los modelos de objetos nativos de Word y Excel solo se desencadenan en el nivel de aplicación. Los elementos host proporcionan estos eventos en el nivel de documento para que resulte más fácil controlar los eventos de un documento específico.
Descripción de los elementos host en proyectos de nivel de documento
En los proyectos de nivel de 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 Document y Worksheet tienen asociados diseñadores que son la representación visual del documento o la hoja de cálculo, como un diseñador de Windows Forms. Puede usar este diseñador para modificar el contenido del documento o la hoja de cálculo directamente en Word o Excel y para arrastrar controles a la superficie de diseño. Para obtener más información, vea Elemento host de documento y Elemento host de hoja de cálculo.
El elemento host Workbook no actúa como un contenedor para los controles que tienen una 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, vea Elemento host del libro.
No es posible crear elementos host mediante programación en proyectos de nivel de documento. En su lugar, use las clases ThisDocument, ThisWorkbooko 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, consulte Limitaciones mediante programación de elementos host y controles host.
Descripción de los elementos host en proyectos de complemento de VSTO
Al crear un complemento de VSTO, no tiene acceso a ningún elemento host de forma predeterminada. Sin embargo, puede generar en tiempo de ejecución los elementos host Document, Workbooky Worksheet en complementos de VSTO para Word y Excel.
Después de generar un elemento host, puede realizar tareas como agregar controles a documentos. Para obtener más información, vea Extender documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución.
Controles host
Los controles host extienden varios objetos de interfaz de usuario en los modelos de objetos de Word y Excel como, por ejemplo, los objetos Microsoft.Office.Interop.Word.ContentControl y Range.
Los siguientes controles host están disponibles para los proyectos de Excel:
-
Los siguientes controles host están disponibles para los proyectos de Word:
-
Los controles host que se agregan a documentos de Office se comportan como los objetos nativos de Office; sin embargo, los controles host tienen funcionalidad adicional que incluye eventos y capacidades de enlace de datos. Por ejemplo, cuando quiere capturar los eventos de un objeto Range nativo en Excel, primero debe controlar el evento de cambio de la hoja de cálculo. A continuación, debe determinar si el cambio se produjo dentro de Range. En cambio, el control host NamedRange tiene un evento Change que se puede controlar directamente.
La relación entre un elemento host y los controles host es similar a la relación entre un formulario Windows Forms y controles de Windows Forms. Del mismo modo que colocaría un control de cuadro de texto en un Windows Form, se coloca un control NamedRange en un elemento host Worksheet . En la siguiente ilustración se muestra la relación entre los elementos host y los controles host.
También puede usar 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, vea Controles de Windows Forms en la introducción a documentos de Office.
Nota:
No se permite agregar controles host ni controles de Windows Forms a un subdocumento de Word.
Adición de controles host a los documentos
En los proyectos de nivel de documento, puede agregar controles host a los documentos de Word o a las hojas de cálculo de Excel en tiempo de diseño de las maneras siguientes:
Agregue 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 las hojas de cálculo. Los controles host de Excel están disponibles en la pestaña Controles de Excel en proyectos de Excel, mientras que los controles host de Word están disponibles en la pestaña Controles de Word en proyectos de Word.
Arrastre los controles host desde la ventana Orígenes de datos hasta los documentos y las hojas de cálculo. Esto permite agregar controles que ya están 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 complementos de VSTO, también puede agregar algunos controles host a 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 documentos, vea los temas siguientes:
Nombres de los controles host
Si arrastra un control host desde el Cuadro de herramientas al documento, se asignará automáticamente un nombre al control. Este nombre se compone del tipo de control con un número incremental al final. Por ejemplo, los marcadores se denominan bookmark1, bookmark2, etc. Si usa la funcionalidad nativa de Word o Excel para agregar el control, puede asignarle un nombre específico en el momento de crearlo. También puede cambiar el nombre de los controles modificando el valor de la propiedad Name en la ventana Propiedades .
Nota:
No es posible usar palabras reservadas para denominar controles host. Por ejemplo, si agrega un el control NamedRange a una hoja de cálculo y cambia el nombre a System, se producen errores al compilar el proyecto.
Eliminación de controles host
En los proyectos de nivel de documento, puede eliminar controles host en tiempo de diseño seleccionando el control en la hoja de cálculo de Excel o documento de Word y presionando la tecla Eliminar . Sin embargo, debe usar el cuadro de diálogo Definir nombre en Excel para eliminar los controles NamedRange .
Si agrega un control host a un documento en tiempo de diseño, no debería quitarlo mediante programación en tiempo de ejecución porque la próxima vez que se intente usar el control en el código, se produce una excepción. El método Delete de un control host solo quita controles host agregados al documento en tiempo de ejecución. Si se 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 un control NamedRange solo elimina correctamente NamedRange si se agregó mediante programación a la hoja de cálculo, lo que se conoce como creación de 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 Controls o 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. Puede usar las características de protección de documentos en Word y Excel para evitar que se eliminen los controles host. Para obtener más información, vea Ejemplos y tutoriales de desarrollo de Office.
Nota:
No quite controles mediante programación durante el funcionamiento del controlador de eventos Shutdown del documento o la hoja de cálculo. Los elementos de la interfaz de usuario dejan de estar disponibles cuando se produce el evento Shutdown . Si quiere quitar controles antes de que se cierre la aplicación, agregue su código a otro controlador de eventos, como, por ejemplo, BeforeClose o BeforeSave.
Programa contra eventos de control de host
Una manera en que los controles host extienden los objetos de Office es agregando eventos. Por ejemplo, el Range objeto de Excel y Bookmark el objeto de Word no tienen eventos, pero el entorno de ejecución de Visual Studio Tools para Office extiende estos objetos agregando eventos programables. Puede obtener acceso y escribir código basado en estos eventos de la misma manera que tiene acceso a los eventos de los controles de Windows Forms: a través de la lista desplegable de eventos en Visual Basic y la página de propiedades de evento en C#. Para obtener más información, vea Tutorial: Programa con eventos de un control NamedRange.
Nota:
No debería establecer la propiedad EnableEvents del objeto Application en Excel como false. Al establecer esta propiedad en false , impide que Excel active cualquier evento, incluidos los eventos de los controles host.
Contenido relacionado
- Limitaciones mediante programación de elementos host y controles host
- Programas de complementos VSTO
- Personalizaciones de nivel de documento del programa
- Automatizar Word mediante objetos extendidos
- Automatizar Excel mediante objetos extendidos
- Controles en documentos de Office
- Enlace de datos a controles en soluciones de Office