Programmatic Limitations of Host Items and Host Controls

  • Article

Each host item and host control is designed to behave like a corresponding native Microsoft Office Word or Microsoft Office Excel object, with additional functionality. However, there are some fundamental differences between the behavior of host items and host controls and native Office objects at run time.

For general information about host items and host controls, see Host Items and Host Controls Overview.

Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2007 and Excel 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

Programmatically Creating Host Items

When you programmatically create or open a document, workbook, or worksheet at run time by using the Word or Excel object model, the item is not a host item. Instead, the new object is a native Office object. For example, if you use the Documents.Add method to create a new Word document at run time, it will be a native Microsoft.Office.Interop.Word.Document object rather than a Microsoft.Office.Tools.Word.Document host item. Similarly, when you create a new worksheet at run time using the Worksheets.Add method, you get a native Microsoft.Office.Interop.Excel.Worksheet object rather than a Microsoft.Office.Tools.Excel.Worksheet host item.

In document-level projects, you cannot create host items at run time. Host items can be created only at design time in document-level projects. For more information, see Document Host Item, Workbook Host Item, and Worksheet Host Item.

In application-level projects, you can create Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, or Microsoft.Office.Tools.Excel.Worksheet host items at run time. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Programmatically Creating Host Controls

You can programmatically add host controls to a Microsoft.Office.Tools.Word.Document or Microsoft.Office.Tools.Excel.Worksheet host item at run time. For more information, see Adding Controls to Office Documents at Run Time.

You cannot add host controls to a native Microsoft.Office.Interop.Word.Document or Microsoft.Office.Interop.Excel.Worksheet.

Note

The following host controls cannot be added programmatically to worksheets or documents: XmlMappedRange, XMLNode, and XMLNodes.

Understanding Type Differences Between Host Items, Host Controls, and Native Office Objects

For each host item and host control, there is an underlying native Microsoft Office Word or Microsoft Office Excel object. 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. If you try to cast a native Office object into the type of a host item or host control, an InvalidCastException is thrown.

There are several scenarios where the differences between the types of host items and host controls and the underlying native Office objects can affect your code.

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 to pass the host control to a method or property:

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

  • When the Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute is set to false in a project that targets the .NET Framework 3.5, and the method or property expects an Object instead of the underlying Excel object. For more information about the Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute, see Formatting Data in Excel with Various Regional Settings.

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.

Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")
Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

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);

Return Types of Native Office Methods and Properties

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 NamedRange host control in Excel returns a Microsoft.Office.Interop.Excel.Worksheet object rather than a Microsoft.Office.Tools.Excel.Worksheet host item. Similarly, the Parent property of a RichTextContentControl host control in Word returns a Microsoft.Office.Interop.Word.Document object rather than a Microsoft.Office.Tools.Word.Document host item.

Accessing Collections of Host Controls

The Visual Studio Tools for Office runtime does not provide individual collections for each type of host control. Instead, use the Controls property of a host item to iterate through all managed controls (both host controls and Windows Forms controls) on the document or worksheet, and then look for items that match the type of the host control you are interested in. The following code example examines each control on a Word document and determines whether the control is a Microsoft.Office.Tools.Word.Bookmark.

Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

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 bookmark here.
    }
}

For more information about the Controls property of host items, see Adding Controls to Office Documents at Run Time.

The Word and Excel object models include properties that expose collections of native controls on documents and worksheets. You cannot access managed controls by using these properties. For example, it is not possible to enumerate each Microsoft.Office.Tools.Word.Bookmark host control in a document by using the Bookmarks property of a Microsoft.Office.Interop.Word.Document or the Bookmarks property of a Microsoft.Office.Tools.Word.Document. These properties include only the Microsoft.Office.Interop.Word.Bookmark controls in the document; they do not contain the Microsoft.Office.Tools.Word.Bookmark host controls in the document.

Accessing New Excel 2010 and Word 2010 Members in Projects That Target the .NET Framework 3.5

In Excel 2010 and Word 2010 projects that target the .NET Framework 3.5, members that were introduced in Office 2010 are not available on host items and host controls. In these projects, host items and host controls only have members that were available in the 2007 Microsoft Office system. To access a member that was added in Excel 2010 or Word 2010, use the InnerObject property of the host control to return the underlying native object, and then access the member on that object.

For example, in Word 2010, Microsoft.Office.Interop.Word.ContentControl objects have a Checked property that can be used to determine whether a check box content control is selected (this property is not available in Word 2007, because Word 2007 does not have check box content controls). In Word 2010 projects that target the .NET Framework 3.5, the Microsoft.Office.Tools.Word.ContentControl host control does not have a Checked property. The following code example demonstrates how to use the InnerObject property to access the Checked property of the underlying Microsoft.Office.Interop.Word.ContentControl object.

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)

' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True

' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;

// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;

See Also

Reference

Worksheet.Controls

Document.Controls

Concepts

Host Items and Host Controls Overview

Automating Word by Using Extended Objects

Automating Excel by Using Extended Objects

Worksheet Host Item

Workbook Host Item

Document Host Item