Export (0) Print
Expand All

Programmatic Limitations of Host Items and Host Controls

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005


    Visual Studio Team System

  • Microsoft Office 2003

For each host item and host control provided in Microsoft Visual Studio 2005 Tools for the Microsoft Office System, there is an underlying native Microsoft Office Word or Microsoft Office Excel object. Many of the methods and properties of Office objects (host items, host controls, and native Office objects) get or set a value in the type of the underlying Office object, rather than the host item or host control. You can access the underlying object by using the InnerObject property of the host item or host control. However, there is no way to cast a native Office object to its corresponding host item or host control.

Programmatically Creating Host Items and Host Controls

Host items are not created automatically when you programmatically create a new document or worksheet at run time. For example, if you add a Word document at run time, it will be of the type Microsoft.Office.Interop.Word.Document rather than Microsoft.Office.Tools.Word.Document. Similarly, when you add a worksheet programmatically at run time using the Add method, you get a worksheet of the type Microsoft.Office.Interop.Excel.Worksheet not Microsoft.Office.Tools.Excel.Worksheet. Host controls can be created programmatically, but they can only be added to host items. If you programmatically create a document or worksheet, the item is not a host item, and you will not be able to add host controls to the programmatically created document or worksheet. You can create host items only at design time.

You can programmatically add host controls to a host item by using one of the Add<Control> methods. For example, to add a NamedRange control to your document, use the AddNamedRange method. Only the following host controls can be created programmatically:

You cannot add managed controls to a native Word Microsoft.Office.Interop.Word.Document or Excel Microsoft.Office.Interop.Excel.Worksheet. Host controls and Windows Forms controls can be added only to a host item. For more information about programmatically adding controls to documents, see Adding Controls to Office Documents at Run Time.

Return Types

Most methods and properties of host items return the underlying native Office object upon which the host item is based. For example, the Parent property of a host control in Excel returns a Microsoft.Office.Interop.Excel.Worksheet object rather than a Microsoft.Office.Tools.Excel.Worksheet host item, and the Parent property of a host control in Word returns a Microsoft.Office.Interop.Word.Document object rather than a Microsoft.Office.Tools.Word.Document host item. An InvalidCastException is thrown when you try to cast a native Office object into a host item or host control.

Accessing Collections

Visual Studio Tools for Office does not provide individual collections for each type of host control. For example, it is not possible to enumerate each Microsoft.Office.Tools.Word.Bookmark control in the document using the Microsoft.Office.Interop.Word.Bookmarks collection. All of the bookmarks in the document are included; the enumeration does not distinguish between a Microsoft.Office.Tools.Word.Bookmark control and a Microsoft.Office.Interop.Word.Bookmark.

You can use the ControlCollection to iterate through all controls (both host controls and Windows Forms controls) on the document, and then look for items that match the type of the host control you are interested in. The following example determines if a control is of the type Microsoft.Office.Tools.Word.Bookmark:

foreach (object targetControl in this.Controls)
    Microsoft.Office.Tools.Word.Bookmark bookMark
        = targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
        // Do some work with the book mark here.

Passing Host Controls to Methods and Properties

In Word, you cannot pass a host control to a method or property that requires a native Word object as a parameter. You must use the InnerObject property of the host control to return the underlying native Word object. For example, you can pass a Microsoft.Office.Interop.Word.Bookmark object to a method by passing the InnerObject property of the Microsoft.Office.Tools.Word.Bookmark host control to the method.

In Excel, there are two cases in which you must use the InnerObject property of the host control:

  • When the method or property expects the underlying Excel object.

  • When the ExcelLocale1033Attribute attribute is set to false and the method or property expects an Object instead of the underlying Excel object. For more information, see ExcelLocale1033Proxy.

The following example creates a Microsoft.Office.Tools.Excel.NamedRange control and passes it to the AutoFill method. The code uses the InnerObject property of the named range to return the underlying Office Microsoft.Office.Interop.Excel.Range that is required by the AutoFill method.

this.Range["A1", missing].Value2 = "Monday";
this.Range["A2", missing].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange 
    = this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");

this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

See Also

Community Additions

© 2014 Microsoft