Elementos host y la información general sobre controles de hostHost items and host controls overview

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.Host items and host controls are types that help provide the programming model for Office solutions that are created by using the Office development tools in 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.Host items and host controls make interacting with the object models of Microsoft Office Word and Microsoft Office Excel, which are based on COM, more like interacting with managed objects such as Windows Forms controls.

Se aplica a: La información de este tema se aplica al documento-proyectos y agregar de VSTO de nivel-en los proyectos de Excel y Word.Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Excel and Word. Para obtener más información, consulte características disponibles por tipo de aplicación y el proyecto de Office.For more information, see Features available by Office application and project type.

Elementos hostHost items

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.Host items are types that are at the top of object model hierarchies in Office projects. El Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime define los siguientes elementos host para soluciones de Word y Excel:The Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime defines the following host items for Word and Excel solutions:

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    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.Each of these types extends an object that exists natively in the Word or Excel object model, called a native Office object. Por ejemplo, el elemento host Document extiende el objeto Document , que se define en el ensamblado de interoperabilidad primario para Word.For example, the Document host item extends the Document object, which is defined in the primary interop assembly for 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:Host items generally have the same base functionality as the corresponding Office objects, but are enhanced with the following features:

  • La capacidad de hospedar controles administrados, incluidos los controles host y controles de Windows Forms.The ability to host managed controls, including host controls and Windows Forms controls.

  • Modelos de eventos más completo.Richer event models. 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.Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. 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.Host items provide these events at the document level, so that it is easier to handle the events for a specific document.

Comprender los elementos host en proyectos de nivel de documentoUnderstand host items in document-level projects

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.In document-level projects, host items provide an entry point for your code, and they have designers that help you develop your solution.

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.The Document and Worksheet host items have associated designers that are the visual representation of the document or worksheet, like a Windows Forms designer. 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.You can use this designer to modify the content of the document or worksheet directly in Word or Excel, and to drag controls onto the design surface. Para obtener más información, consulte elemento host Document y elemento host Worksheet.For more information, see Document host item and Worksheet host item.

El elemento host Workbook no actúa como un contenedor para los controles que tienen una interfaz de usuario.The Workbook host item does not act as a container for controls that have a user interface. 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.Instead, the designer for this host item functions as a component tray, which enables you to drag a component, such as a DataSet, onto its design surface. Para obtener más información, consulte elemento host Workbook.For more information, see Workbook host item.

No es posible crear elementos host mediante programación en proyectos de nivel de documento.Host items cannot be created programmatically in document-level projects. En su lugar, use las clases ThisDocument, ThisWorkbooko Sheetn que Visual Studio genera automáticamente en tiempo de diseño en el proyecto.Instead, use the ThisDocument, ThisWorkbook, or Sheetn classes that Visual Studio automatically generates in your project at design time. Estas clases generadas se derivan de los elementos host y proporcionan un punto de entrada para el código.These generated classes derive from the host items, and they provide an entry point for your code. Para obtener más información, consulte limitaciones de programación de elementos host y controles host.For more information, see Programmatic limitations of host items and host controls.

Comprender los elementos host en proyectos de complemento VSTOUnderstand host items in VSTO Add-in projects

Al crear un complemento de VSTO, no tendrá acceso a los elementos host de forma predeterminada.When you create a VSTO Add-in, you do not have access to any host items by default. Sin embargo, puede generar Document, Workbook, y Worksheet hospedar elementos en Word y complementos de VSTO de Excel en tiempo de ejecución.However, you can generate Document, Workbook, and Worksheet host items in Word and Excel VSTO Add-ins at runtime.

Después de generar un elemento host, puede realizar tareas como agregar controles a documentos.After you generate a host item, you can perform tasks such as adding controls to documents. Para obtener más información, consulte documentos ampliar Word y libros de Excel en complementos VSTO en tiempo de ejecución.For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Controles hostHost controls

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.Host controls extend various user interface (UI) objects in the Word and Excel object models, such as Microsoft.Office.Interop.Word.ContentControl and Range objects.

Los siguientes controles host están disponibles para los proyectos de Excel:The following host controls are available for Excel projects:

  • Control de gráficoChart control

  • ListObject (control)ListObject control

  • NamedRange (control)NamedRange control

  • XmlMappedRange (control)XmlMappedRange control

    Los siguientes controles host están disponibles para los proyectos de Word:The following host controls are available for Word projects:

  • Bookmark (control)Bookmark control

  • Controles de contenidoContent controls

  • XMLNode (control)XMLNode control

  • XMLNodes (control)XMLNodes control

    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.Host controls that are added to Office documents behave like the native Office objects; however, host controls have additional functionality, including events and data-binding capabilities. 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.For example, when you want to capture the events of a native Range object in Excel, you must first handle the change event of the worksheet. A continuación, debe determinar si el cambio se produjo dentro de Range.Then you must determine whether the change occurred within the Range. En cambio, el control host NamedRange tiene un evento Change que se puede controlar directamente.In contrast, the NamedRange host control has a Change event that you can handle directly.

    La relación entre un elemento host y controles host es similar a la relación entre los controles de formulario de Windows y Windows Forms.The relationship between a host item and host controls is similar to the relationship between a Windows Form and Windows Forms controls. 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 .Just as you would place a text box control on a Windows Form, you place a NamedRange control on a Worksheet host item. En la siguiente ilustración se muestra la relación entre los elementos host y los controles host.The following illustration shows the relationship between host items and host controls.

    Relación entre los elementos host y controles hostRelationship between host items and host controls

    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.You can also use Windows Forms controls in your Office solutions by adding them directly to the Word and Excel document surface. Para obtener más información, consulte Windows Forms a los controles de información general sobre documentos de Office.For more information, see Windows Forms controls on Office documents overview.

Note

No se permite agregar controles host ni controles de Windows Forms a un subdocumento de Word.Adding host controls or Windows Forms controls to a Word subdocument is not supported.

Agregar controles host a los documentosAdd host controls to your documents

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:In document-level projects, you can add host controls to your Word documents or Excel worksheets at design time in the following ways:

Denominar controles hostName host controls

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.When you drag a host control from the Toolbox to your document, the control is automatically named using the control type with an incremental number at the end. Por ejemplo, los marcadores se denominan bookmark1, bookmark2, etc.For example, bookmarks are named bookmark1, bookmark2, and so on. Si usa la funcionalidad nativa de Word o Excel para agregar el control, puede asignarle un nombre específico en el momento de crearlo.If you use the native functionality of Word or Excel to add the control, you can give it a specific name at the time that you create it. También puede cambiar el nombre de los controles modificando el valor de la propiedad Name en la ventana Propiedades .You can also rename your controls by changing the value of the Name property in the Properties window.

Note

No es posible usar palabras reservadas para denominar controles host.You cannot use reserved words to name host controls. 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.For example, if you add a NamedRange control to a worksheet and change the name to System, errors occur when you build the project.

Eliminar controles hostDelete host controls

En los proyectos de nivel de documento, puede eliminar controles host en tiempo de diseño, seleccione el control en la hoja de cálculo de Excel o documento de Word y presione la eliminar clave.In document-level projects, you can delete host controls at design time by selecting the control on the Excel worksheet or Word document and pressing the Delete key. Sin embargo, debe usar el cuadro de diálogo Definir nombre en Excel para eliminar los controles NamedRange .However, you must use the Define Name dialog box in Excel to delete NamedRange controls.

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 intente utilizar el control de código, se produce una excepción.If you add a host control to a document at design time, you should not remove it programmatically at runtime because the next time you try to use the control in code, an exception is thrown. El Delete método de un control host solo quita controles host que se agregan al documento en tiempo de ejecución.The Delete method of a host control only removes host controls that are added to the document at runtime. Si se llama al método Delete de un control host creado en tiempo de diseño, se produce una excepción.If you call the Delete method of a host control that was created at design time, an exception is thrown.

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.For example, the Delete method of a NamedRange only successfully deletes the NamedRange if it was programmatically added to the worksheet, which is known as creating host controls dynamically. 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 .Dynamically created host controls can also be removed by passing the control name to the Remove method of the Controls or Controls property. Para obtener más información, consulte agregar controles a documentos de Office en tiempo de ejecución.For more information, see Add controls to Office documents at runtime.

Si los usuarios finales eliminan un control host desde el documento en tiempo de ejecución, la solución podría producir errores inesperados.If end users delete a host control from the document at runtime, the solution might fail in unexpected ways. Puede usar las características de protección de documentos en Word y Excel para evitar que se eliminen los controles host.You can use the document protection features in Word and Excel to protect the host controls from being deleted. Para obtener más información, consulte tutoriales y ejemplos de desarrollo de Office.For more information, see Office development samples and walkthroughs.

Note

No quite controles mediante programación durante el funcionamiento del controlador de eventos Shutdown del documento o la hoja de cálculo.Do not programmatically remove controls during the Shutdown event handler of the document or worksheet. Los elementos de la interfaz de usuario dejan de estar disponibles cuando se produce el evento Shutdown .The UI elements are no longer available when the Shutdown event occurs. 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.If you want to remove controls before the application closes, add your code to another event handler such as BeforeClose or BeforeSave.

Programar eventos del control hostProgram against host control events

Una manera en que los controles host extienden los objetos de Office es agregando eventos.One way that host controls extend Office objects is by adding events. Por ejemplo, el objeto Range de Excel y el objeto Bookmark de Word no tienen eventos, pero el Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime extiende estos objetos agregando eventos programables.For example, the Range object in Excel and Bookmark object in Word do not have events, but the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime extends these objects by adding programmable events. 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#.You can access and code against these events the same way you access events of controls on Windows Forms: through the event drop-down list in Visual Basic and the event property page in C#. Para obtener más información, vea Tutorial: Programar basándose en eventos de un control NamedRange.For more information, see Walkthrough: Program against events of a NamedRange control.

Note

No debería establecer la propiedad EnableEvents del objeto Application en Excel como false.You should not set the EnableEvents property of the Application object in Excel to false. Al establecer esta propiedad en false , impide que Excel active cualquier evento, incluidos los eventos de los controles host.Setting this property to false prevents Excel from raising any events, including the events of host controls.

Vea tambiénSee also