Host items provide an entry point for your code in Visual Studio Tools for Office solutions.

Application-level add-ins use the Microsoft.Office.Tools.AddIn host item. This host item provides access to the object model of the host application and members you can use to customize the user interface of the host application. For more information, see AddIn.

Document-level customizations use a different set of host items that includes Microsoft.Office.Tools.Word.Document and Microsoft.Office.Tools.Excel.Worksheet. These host items have designers that are the visual representation of the class, very much like the Windows Forms Designer. These host items can be bound to data and are a container for controls such as host controls and Windows Forms controls. For more information, see Document and Worksheet.

There is also a Microsoft.Office.Tools.Excel.Workbook host item, but it does not act as a container for host controls. The workbook functions as a component tray, enabling you to drag a component, such as a DataSet, onto its design surface. For more information, see Workbook.

Host controls extend objects that are in the Microsoft Office Word 2003 and Microsoft Office Excel 2003 object models; in other words, host controls are based on native Office objects. Host controls are only available in document-level customizations.

Host controls that are added to Office documents behave like the native Office objects, such as ranges; however, host controls have additional functionality, including events and data-binding capabilities. For example, when you want to capture the events of a native Microsoft.Office.Interop.Excel.Range object in Excel, you must first trap the change event of the worksheet. Then you must determine whether the change occurred within the Microsoft.Office.Interop.Excel.Range. With the Microsoft.Office.Tools.Excel.NamedRange control, you can access the change event directly.

The relationship between a host item and host controls in a customization is very similar to the relationship between a Windows Form and Windows Forms controls. Just as you would place a text box control on a Windows Form, you place a Microsoft.Office.Tools.Excel.NamedRange control on a Microsoft.Office.Tools.Excel.Worksheet host item.

Additionally, Visual Studio Tools for Office enables you to use Windows Forms controls in your document-level projects by adding them directly to the Word and Excel document surface. For more information, see Windows Forms Controls on Office Documents Overview.

Note
Adding host controls or Windows Forms controls to a Word subdocument is not supported.

Host items and host controls in document-level projects are different from the underlying native Office objects in several ways. Additionally, there are some limitations that exist with respect to programming against a host item or host control. For more information, see Programmatic Limitations of Host Items and Host Controls.

Host items and host controls differ from the native Office objects in the following ways:

• Host controls generally have the same base functionality as the Office objects they are based on, but are improved by:

  • Offering richer event models.

  • Having data-binding capabilities.

  In some cases, the base functionality differs because the control is created through a combination of different object types. For an example, see Bookmark Control.

• Host controls are Microsoft .NET-friendly classes that are built on top of the native Office objects.

• Host controls are of the type Microsoft.Office.Tools.Excel or Microsoft.Office.Tools.Word, whereas the native objects are of the type Microsoft.Office.Interop.Excel or Microsoft.Office.Interop.Word.

• Host items cannot be created programmatically; however, most of the host controls can be programmatically added to and deleted from your Word and Excel documents. For more information, see Programmatic Limitations of Host Items and Host Controls.

You can add host controls to your Word 2003 documents or Excel 2003 worksheets in four ways:

• Because host controls are extended Office objects, you can add them to your document at design-time from within Visual Studio, in the same manner you would add a native object. For example, on the Insert menu, click Bookmark to add a Microsoft.Office.Tools.Word.Bookmark control to your document.

• You can drag host controls from the Toolbox onto your documents and worksheets. Visual Studio Tools for Office adds the most common host controls to the Visual Studio Toolbox. Excel host controls are available in the Excel Controls tab in Excel projects, and Word host controls are available in the Word Controls tab in Word projects. For more information, see Word Host Controls and Excel Host Controls.

• You can drag host controls from the Data Sources window onto your documents and worksheets. This enables you to add controls that are already bound to data in your documents. For more information, see Binding Data to Controls Overview.

• You can programmatically create Bookmark, ListObject, NamedRange and Chart controls. For more information, see How to: Add Bookmark Controls to Word Documents, How to: Add ListObject Controls to Worksheets, How to: Add NamedRange Controls to Worksheets, and How to: Add Chart Controls to Worksheets.

If you drag a host control from the Toolbox to your document, the control will automatically be named using the control type and an incremental number appended at the end. For example, two bookmarks would be named Bookmark1 and Bookmark2. 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. You can also rename your controls using the Name property in the Properties window.

Note
You cannot use reserved words to name host controls. For example, if you add a NamedRange control to a worksheet and change the name to System, errors occur when you build the project.

In most cases, you can delete host controls at design time by selecting the control on the Excel worksheet or Word document and pressing the DELETE key. However, you must use the Define Name dialog box in Excel to delete NamedRange controls. For more information, see How to: Delete NamedRange Controls at Design Time.

If you add a host control to a document at design time, you should not remove it programmatically at run time because the next time you try to use the control in code, an exception is thrown. The Delete method of a host control only removes host controls that are added to the document at run time. If you call the Delete method of a host control that was created at design time, an exception is thrown. For example, Bookmark1.Delete only successfully deletes Bookmark1 if it was programmatically added to the document. Dynamically created host controls can also be removed by passing the control name to the Remove method of the ControlsCollection. For more information, see Adding Controls to Office Documents at Run Time.

If end users delete a host control, such a bookmark, from the document at run time, the solution might fail in unexpected ways. You can use the document protection features in Word and Excel to protect the host controls from being deleted. For more information, see Word Document Protection Techniques Sample and Excel Document Protection Techniques Sample.

Note
Do not programmatically remove controls during the Shutdown event handler of the document. The UI elements of the document are no longer available when the Shutdown event occurs. If you want to remove controls before the application closes, add your code to another event handler such as BeforeClose or BeforeSave.

Available Host Items and Host Controls

One way host controls extend Office objects is by adding events. For example, the Microsoft.Office.Interop.Excel.Range object in Excel and Microsoft.Office.Interop.Word.Bookmark object in Word do not have events, but Visual Studio Tools for Office extends these objects by adding programmable events. 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#. For more information, see Walkthrough: Programming Against Events of a NamedRange Control.

Note
You should not set the EnableEvents property of the Application object in Excel to false. Setting this property to false prevents Excel from raising any events, including the events of host controls.

Host controls also extend Office objects by enabling data binding. Host controls have the same data-binding capabilities as controls on Windows Forms. You can bind host controls to data sources such as datasets and data tables. Host controls enable either simple or complex data binding. For more information, see Walkthrough: Binding a Worksheet Cell to a Database Field and Walkthrough: Binding Cells to Multiple Columns in a Table.

Simple Data Binding

Complex Data Binding

Concepts

Other Resources