Host Items and Host Controls Overview
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Document-level projects
Application-level projects
For more information, see Features Available by Application and Project Type. |
Host items and host controls are classes that help provide the programming model for Visual Studio Tools for Office solutions. They 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.
Host Items
Host items are classes that are at the top of object model hierarchies in Visual Studio Tools for Office projects. Visual Studio Tools for Office defines the following host items for Word and Excel solutions:
Each of these classes extends a class that exists natively in the Word or Excel object model (called a native Office object). For example, the Microsoft.Office.Tools.Word.Document host item extends the Document class, which is defined in the primary interop assembly for Word.
Host items generally have the same base functionality as the corresponding Office objects, but are enhanced with the following features:
The ability to host managed controls, including host controls and Windows Forms controls.
Richer event models. Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. Host items provide these events at the document level, so that it is easier to handle the events for a specific document.
Understanding Host Items in Document-Level Projects
In document-level projects, host items provide an entry point for your code, and they have designers that help you develop your solution.
The Microsoft.Office.Tools.Word.Document and Microsoft.Office.Tools.Excel.Worksheet host items have designers that are the visual representation of the document or worksheet, like a Windows Forms designer. 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. For more information, see Document Host Item and Worksheet Host Item.
The Microsoft.Office.Tools.Excel.Workbook host item does not act as a container for controls that have a user interface. 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. For more information, see Workbook Host Item.
Host items cannot be created programmatically in document-level projects. Instead, use the ThisDocument, ThisWorkbook, or Sheetn classes that Visual Studio Tools for Office automatically generates in your project at design time. These generated classes derive from the host item classes, and they provide an entry point for your code. For more information, see Programmatic Limitations of Host Items and Host Controls.
Understanding Host Items in Application-Level Projects
When you create an application-level add-in, you do not have access to any host items by default. However, starting in Visual Studio 2008 Service Pack 1 (SP1), you can generate Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, and Microsoft.Office.Tools.Excel.Worksheet host items in add-ins at run time.
After you generate a host item, you can perform tasks such as adding controls to documents and creating smart tags that are recognized in a specific document. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.
Host Controls
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.
The following host controls are available for Excel projects:
The following host controls are available for Word projects:
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. 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. Then you must determine whether the change occurred within the Range. In contrast, the Microsoft.Office.Tools.Excel.NamedRange host control has a Change event that you can handle directly.
The relationship between a host item and host controls 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. The following illustration shows the relationship between host items and host controls.
.png "Relationship between host items and host controls")
Additionally, Visual Studio Tools for Office enables you to use Windows Forms controls in your Office solutions 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.
Adding Host Controls to Your Documents
In document-level projects, you can add host controls to your Word documents or Excel worksheets at design time in the following ways:
Add host controls to your document at design time in the same manner you would add a native object.
Drag host controls from the Toolbox onto your documents and worksheets. 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.
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. For more information, see Binding Data to Controls in Office Solutions.
In document-level projects, and in application-level projects starting in SP1, you can also add some host controls to documents at run time. For more information, see Adding Controls to Office Documents at Run Time.
For more information about how to add host controls to documents, see the following topics:
Naming Host Controls
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. For example, bookmarks are named bookmark1, bookmark2, and so on. 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 by changing the value of 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.
Deleting Host Controls
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. 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, 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. Dynamically created host controls can also be removed by passing the control name to the Remove method of the Worksheet.Controls or Document.Controls property. For more information, see Adding Controls to Office Documents at Run Time.
If end users delete a host control 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 or worksheet. The UI elements 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.
Programming Against Host Control Events
One way that host controls extend Office objects is by adding events. For example, the Range object in Excel and 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.
See Also
Concepts
Binding Data to Controls in Office Solutions
Programmatic Limitations of Host Items and Host Controls
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
July 2008 |
Added information about using host items and host controls in application-level add-ins. |
SP1 feature change. |