Programmgesteuerte Einschränkungen von Hostelementen und Hoststeuerelementen

Artikel
08/10/2011

Jedes Hostelement und jedes Hoststeuerelement ist dafür konzipiert, sich wie ein entsprechendes systemeigenes Microsoft Office Word- oder Microsoft Office Excel-Objekt mit zusätzlichen Funktionen zu verhalten. Es gibt jedoch einige grundlegende Unterschiede zwischen dem Verhalten von Hostelementen bzw. Hoststeuerelementen und systemeigenen Office-Objekten zur Laufzeit.

Allgemeine Informationen über Hostelemente und Hoststeuerelemente finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokument- und Anwendungsebene für die folgenden Anwendungen: Excel 2007 und Excel 2010, Word 2007 und Word 2010. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Programmgesteuertes Erstellen von Hostelementen

Wenn Sie ein Dokument, eine Arbeitsmappe oder ein Arbeitsblatt zur Laufzeit mit dem Word- oder Excel-Objektmodell programmgesteuert erstellen oder öffnen, ist das Element kein Hostelement. Das neue Objekt ist ein systemeigenes Office-Objekt. Wenn Sie beispielsweise die Documents.Add-Methode verwenden, um ein neues Word-Dokument zur Laufzeit zu erstellen, ist dieses ein systemeigenes Microsoft.Office.Interop.Word.Document-Objekt anstelle eines Microsoft.Office.Tools.Word.Document-Hostelements. Entsprechend erhalten Sie, wenn Sie mit der Worksheets.Add-Methode ein neues Arbeitsblatt zur Laufzeit erstellen, ein systemeigenes Microsoft.Office.Interop.Excel.Worksheet-Objekt anstelle eines Microsoft.Office.Tools.Excel.Worksheet-Hostelements.

In Projekten auf Dokumentebene können Sie zur Laufzeit keine Hostelemente erstellen. Hostelemente können in Projekten auf Dokumentebene nur zur Entwurfszeit erstellt werden. Weitere Informationen finden Sie unter Dokumenthostelement, Arbeitsmappenhostelement und Arbeitsblatthostelement.

In Projekten auf Anwendungsebene können Sie zur Laufzeit die Hostelemente Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook oder Microsoft.Office.Tools.Excel.Worksheet erstellen. Weitere Informationen finden Sie unter Erweitern von Word-Dokumenten und Excel-Arbeitsmappen in Add-Ins auf Anwendungsebene zur Laufzeit.

Programmgesteuertes Erstellen von Hoststeuerelementen

Sie können Hoststeuerelemente einem Microsoft.Office.Tools.Word.Document-Hostelement oder einem Microsoft.Office.Tools.Excel.Worksheet-Hostelement zur Laufzeit programmgesteuert hinzufügen. Weitere Informationen finden Sie unter Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit.

Sie können einem systemeigenen Microsoft.Office.Interop.Word.Document oder Microsoft.Office.Interop.Excel.Worksheet keine Hoststeuerelemente hinzufügen.

Tipp

Arbeitsblättern oder Dokumenten können die folgenden Hoststeuerelemente nicht programmgesteuert hinzugefügt werden: XmlMappedRange, XMLNode und XMLNodes.

Grundlagen zu Typunterschieden zwischen Hostelementen, Hoststeuerelementen und systemeigenen Office-Objekten

Jedem Hostelement und Hoststeuerelement liegt ein systemeigenes Microsoft Office Word- oder Microsoft Office Excel-Objekt zugrunde. Sie können auf das zugrunde liegende Objekt zugreifen, indem Sie die InnerObject-Eigenschaft des Hostelements oder Hoststeuerelements verwenden. Es gibt jedoch keine Möglichkeit, ein systemeigenes Office-Objekt in das entsprechende Hostelement oder Hoststeuerelement umzuwandeln. Wenn Sie versuchen, ein systemeigenes Office-Objekt in ein Hostelement oder Hoststeuerelement umzuwandeln, wird eine InvalidCastException ausgelöst.

In einigen Szenarien können die Typunterschiede zwischen Hostelementen bzw. Hoststeuerelementen und den zugrundeliegenden systemeigenen Office-Objekten Auswirkungen auf Ihren Code haben.

Übergeben von Hoststeuerelementen an Methoden und Eigenschaften

Sie können in Word kein Hoststeuerelement an eine Methode oder Eigenschaft übergeben, für die ein systemeigenes Word-Objekt als Parameter erforderlich ist. Verwenden Sie die InnerObject-Eigenschaft des Hoststeuerelements für die Rückgabe des zugrunde liegenden, systemeigenen Word-Objekts. Sie können z. B. ein Microsoft.Office.Interop.Word.Bookmark-Objekt an eine Methode übergeben, indem Sie die InnerObject-Eigenschaft des Microsoft.Office.Tools.Word.Bookmark-Hoststeuerelements an die Methode übergeben.

In Excel gibt es zwei Situationen, in denen Sie die InnerObject-Eigenschaft des Hoststeuerelements verwenden müssen, um das Hoststeuerelement an eine Methode oder Eigenschaft zu übergeben:

Wenn die Methode oder Eigenschaft das zugrunde liegende Excel-Objekt erwartet.
Wenn das Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute in einem Projekt, das auf .NET Framework 3.5 abzielt, auf false festgelegt ist und die Methode oder Eigenschaft ein Object statt des zugrunde liegenden Excel-Objekts erwartet. Weitere Informationen zum Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute finden Sie unter Formatieren von Daten in Excel mit verschiedenen regionalen Einstellungen.

Im folgenden Beispiel wird ein Microsoft.Office.Tools.Excel.NamedRange-Steuerelement erstellt und an die AutoFill-Methode übergeben. Der Code gibt mit der InnerObject-Eigenschaft des benannten Bereichs den zugrunde liegenden Office-Microsoft.Office.Interop.Excel.Range zurück, der von der AutoFill-Methode gefordert wird.

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

Rückgabetypen von systemeigenen Office-Methoden und -Eigenschaften

Die meisten Methoden und Eigenschaften von Hostelementen geben das zugrunde liegende systemeigene Office-Objekt zurück, auf dem das Hostelement basiert. Die Parent-Eigenschaft eines NamedRange-Hoststeuerelements in Excel gibt beispielsweise ein Microsoft.Office.Interop.Excel.Worksheet-Objekt anstelle eines Microsoft.Office.Tools.Excel.Worksheet-Hostelements zurück. In ähnlicher Weise gibt die Parent-Eigenschaft eines RichTextContentControl-Hoststeuerelements in Word ein Microsoft.Office.Interop.Word.Document-Objekt anstelle eines Microsoft.Office.Tools.Word.Document-Hostelements zurück.

Zugreifen auf Auflistungen von Hoststeuerelementen

Visual Studio Tools for Office-Laufzeit stellt keine getrennten Auflistungen für die einzelnen Typen von Hoststeuerelementen zur Verfügung. Verwenden Sie stattdessen die Controls-Eigenschaft eines Hostelements zum Durchlaufen aller verwalteten Steuerelemente (sowohl Hoststeuerelemente als auch Windows Forms-Steuerelemente) im Dokument oder Arbeitsblatt. Suchen Sie dann Elemente, die dem Typ des gewünschten Hoststeuerelements entsprechen. Im folgenden Codebeispiel wird jedes Steuerelement in einem Word-Dokument untersucht und bestimmt, ob das Steuerelement ein Microsoft.Office.Tools.Word.Bookmark ist.

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

Weitere Informationen zur Controls-Eigenschaft von Hostelementen finden Sie unter Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit.

Die Word- und Excel-Objektmodelle enthalten Eigenschaften, die Auflistungen systemeigener Steuerelemente in Dokumenten und Arbeitsblättern verfügbar machen. Sie können mithilfe dieser Eigenschaften nicht auf verwaltete Steuerelemente zugreifen. Es ist z. B. nicht möglich, jedes Microsoft.Office.Tools.Word.Bookmark-Hoststeuerelement in einem Dokument mit der Bookmarks-Eigenschaft eines Microsoft.Office.Interop.Word.Document oder der Bookmarks-Eigenschaft eines Microsoft.Office.Tools.Word.Document aufzulisten. Diese Eigenschaften enthalten nur die Microsoft.Office.Interop.Word.Bookmark-Steuerelemente im Dokument. Sie enthalten nicht die Microsoft.Office.Tools.Word.Bookmark-Hoststeuerelemente im Dokument.

Zugreifen auf neue Excel 2010-Member und Word 2010-Member in Projekten, die auf .NET Framework 3.5 abzielen

In Excel 2010- und Word 2010-Projekten, die auf .NET Framework 3.5 abzielen, sind Member, die in Office 2010 eingeführt wurden, in Hostelementen und Hoststeuerelementen nicht verfügbar. In diesen Projekten enthalten Hostelemente und Hoststeuerelemente nur Member, die in 2007 Microsoft Office System verfügbar waren. Verwenden Sie zum Zugreifen auf einen Member, der in Excel 2010 oder Word 2010 hinzugefügt wurde, die InnerObject-Eigenschaft des Hoststeuerelements, um das zugrunde liegende systemeigene Objekt zurückzugeben, und greifen Sie dann auf den Member in diesem Objekt zu.

In Word 2010 enthalten z. B. Microsoft.Office.Interop.Word.ContentControl-Objekte eine Checked-Eigenschaft, mit der bestimmt werden kann, ob ein Kontrollkästchen-Inhaltssteuerelement ausgewählt wurde (diese Eigenschaft ist in Word 2007 nicht verfügbar, da Word 2007 nicht über Kontrollkästchen-Inhaltssteuerelemente verfügt). In Word 2010-Projekten, die auf .NET Framework 3.5 abzielen, enthält das Microsoft.Office.Tools.Word.ContentControl-Hoststeuerelement keine Checked-Eigenschaft. Im folgenden Codebeispiel wird veranschaulicht, wie mithilfe der InnerObject-Eigenschaft auf die Checked-Eigenschaft des zugrunde liegenden Microsoft.Office.Interop.Word.ContentControl-Objekts zugegriffen wird.

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;