宿主项和宿主控件的编程限制

项目
08/12/2011

每一个宿主项和宿主控件的行为都设计为与相应的本机 Microsoft Office Word 或 Microsoft Office Excel 对象的行为相似，并且提供了附加功能。但是，在运行时宿主项和宿主控件的行为与本机 Office 对象的行为存在一些根本差异。

有关宿主项和宿主控件的一般信息，请参见宿主项和宿主控件概述。

**适用于：**本主题中的信息适用于以下应用程序的文档级项目和应用程序级项目：Excel 2007 和 Excel 2010；Word 2007 和 Word 2010。有关更多信息，请参见按 Office 应用程序和项目类型提供的功能。

以编程方式创建宿主项

当使用 Word 或 Excel 对象模型在运行时以编程方式创建或打开文档、工作簿或工作表时，该项不是宿主项。实际上，新对象是本机 Office 对象。例如，如果使用 Documents.Add 方法在运行时创建新的 Word 文档，该新文档将是本机 Microsoft.Office.Interop.Word.Document 对象，而不是 Microsoft.Office.Tools.Word.Document 宿主项。同样，使用 Worksheets.Add 方法在运行时创建新的工作簿时，您会得到本机 Microsoft.Office.Interop.Excel.Worksheet 对象，而不是 Microsoft.Office.Tools.Excel.Worksheet 宿主项。

在文档级项目中，不能在运行时创建宿主项。在文档级项目中，只能在设计时创建宿主项。有关更多信息，请参见文档宿主项、工作簿宿主项和工作表宿主项。

在应用程序级项目中，可以在运行时创建 Microsoft.Office.Tools.Word.Document、Microsoft.Office.Tools.Excel.Workbook 或 Microsoft.Office.Tools.Excel.Worksheet 宿主项。有关更多信息，请参见在运行时在应用程序级外接程序中扩展 Word 文档和 Excel 工作簿。

以编程方式创建宿主控件

可以通过编程方式在运行时向 Microsoft.Office.Tools.Word.Document 或 Microsoft.Office.Tools.Excel.Worksheet 宿主项添加宿主控件。有关更多信息，请参见在运行时向 Office 文档添加控件。

不能向本机 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Worksheet 添加宿主控件。

提示

不能以编程方式将下列宿主控件添加到工作表或文档中：XmlMappedRange、XMLNode 和 XMLNodes。

了解宿主项、宿主控件与本机 Office 对象之间的类型差异

对于每一个宿主项和宿主控件，都有一个基础本机 Microsoft Office Word 或 Microsoft Office Excel 对象与之对应。可以使用宿主项或宿主控件的 InnerObject 属性访问基础对象。但是，无法将本机 Office 对象强制转换为与之对应的宿主项或宿主控件。如果尝试将本机 Office 对象强制转换为宿主项或宿主控件的类型，将引发 InvalidCastException。

在有些情况下，宿主项和宿主控件的类型与基础本机 Office 对象之间的差异可能影响您的代码。

将宿主控件传递给方法和属性

在 Word 中，不能将宿主控件传递给需要将本机 Word 对象作为参数的方法或属性。必须使用宿主控件的 InnerObject 属性来返回基础本机 Word 对象。例如，可以通过将 Microsoft.Office.Tools.Word.Bookmark 宿主控件的 InnerObject 属性传递给方法，将 Microsoft.Office.Interop.Word.Bookmark 对象传递给方法。

在 Excel 中，有两种情况您必须使用宿主控件的 InnerObject 属性将宿主控件传递给方法或属性：

当方法或属性需要基础 Excel 对象时。
当在面向 .NET Framework 3.5 的项目中将 Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute 设置为 false 并且方法或属性需要 Object 而不是基础 Excel 对象时。有关 Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute 的更多信息，请参见使用各种区域设置对 Excel 中的数据进行格式设置。

下面的示例创建一个 Microsoft.Office.Tools.Excel.NamedRange 控件，并将其传递给 AutoFill 方法。代码使用命名范围的 InnerObject 属性返回 AutoFill 方法所需的基础 Office Microsoft.Office.Interop.Excel.Range。

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

本机 Office 对象和属性的返回类型

宿主项的大部分方法和属性会返回它所基于的基础本机 Office 对象。例如，Excel 中的 NamedRange 宿主控件的 Parent 属性会返回 Microsoft.Office.Interop.Excel.Worksheet 对象，而非 Microsoft.Office.Tools.Excel.Worksheet 宿主项。同样，Word 中的 RichTextContentControl 宿主控件的 Parent 属性会返回 Microsoft.Office.Interop.Word.Document 对象，而非 Microsoft.Office.Tools.Word.Document 宿主项。

访问宿主控件的集合

Visual Studio Tools for Office Runtime不会为每种类型的宿主控件提供单独的集合，而是使用宿主项的 Controls 属性循环访问文档或工作表上的所有托管控件（宿主控件和 Windows 窗体控件），然后查找与您感兴趣的宿主控件类型相匹配的项。下面的代码示例检查 Word 文档中的每个控件，并确定哪个控件是 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.
    }
}

有关宿主项的 Controls 属性的更多信息，请参见在运行时向 Office 文档添加控件。

Word 和 Excel 对象模型包括公开文档和工作表中的本机控件集合的属性。不能使用这些属性访问托管控件。例如，不能使用 Microsoft.Office.Interop.Word.Document 的 Bookmarks 属性或 Microsoft.Office.Tools.Word.Document 的 Bookmarks 属性枚举文档中的每个 Microsoft.Office.Tools.Word.Bookmark 宿主控件。这些属性仅包含文档中的 Microsoft.Office.Interop.Word.Bookmark 控件；它们不包含文档中的 Microsoft.Office.Tools.Word.Bookmark 宿主控件。

访问面向 .NET Framework 3.5 的项目中的新 Excel 2010 和 Word 2010 成员

在面向 .NET Framework 3.5 的 Excel 2010 和 Word 2010 项目中，Office 2010 中引入的成员在宿主项和宿主控件上不可用。在这些项目中，宿主项和宿主控件只具有在 2007 Microsoft Office system 中可用的成员。若要访问 Excel 2010 或 Word 2010 中添加的成员，请使用宿主控件的 InnerObject 属性返回基础本机对象，然后访问该对象上的成员。

例如，在 Word 2010 中，Microsoft.Office.Interop.Word.ContentControl 对象具有 Checked 属性，该属性可用来确定是否选中复选框内容控件（该属性在 Word 2007 中不可用，这是因为 Word 2007 没有复选框内容控件）。在面向 .NET Framework 3.5 的 Word 2010 项目中，Microsoft.Office.Tools.Word.ContentControl 宿主控件没有 Checked 属性。下面的代码示例演示如何使用 InnerObject 属性访问基础 Microsoft.Office.Interop.Word.ContentControl 对象的 Checked 属性。

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;