Abrufen von erweiterten Objekten aus systemeigenen Office-Objekten in Anpassungen auf Dokumentebene

Aktualisiert: Juli 2008

Betrifft
Die Informationen in diesem Thema gelten nur für die angegebenen Projekte und Versionen von Visual Studio Tools for Office von Microsoft Office. Projekttyp Projekte auf Dokumentebene Microsoft Office-Version Excel 2007 Word 2007 Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

Viele Ereignishandler für Office-Ereignisse empfangen ein systemeigenes Office-Objekt, das die Arbeitsmappe, das Arbeitsblatt oder das Dokument darstellt, durch die/das das Ereignis ausgelöst wurde. In bestimmten Fällen möchten Sie eventuell Code nur dann ausführen, wenn das Ereignis durch die Arbeitsmappe oder das Dokument in der Anpassung auf Dokumentebene ausgelöst wurde. In einer Anpassung auf Dokumentebene für Excel möchten Sie z. B. Code ausführen, wenn der Benutzer eines der Microsoft.Office.Tools.Excel.Worksheet-Hostelemente in der Anpassung aktiviert, jedoch nicht, wenn der Benutzer ein Arbeitsblatt in einer anderen Arbeitsmappe aktiviert, die zufällig zur gleichen Zeit geöffnet ist.

Ab Visual Studio 2008 Service Pack 1 (SP1) können Sie beim Abrufen eines systemeigenen Office-Objekts testen, ob das betreffende Objekt in einer Anpassung auf Dokumentebene zu einem Hostelement oder zu einem Microsoft.Office.Tools.Excel.ListObject-Hoststeuerelement erweitert wurde.

Hostelemente und Hoststeuerelemente sind Visual Studio Tools for Office-Objekte, die Objekten Funktionalität hinzufügen, die systemeigen im Word- oder Excel-Objektmodell vorhanden sind (diese werden als systemeigene Office-Objekte bezeichnet). Gemeinsam werden Hostelemente und Hoststeuerelemente auch als erweiterte Objekte bezeichnet. Weitere Informationen über Hostelemente und Hoststeuerelemente finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Verwenden der GetVstoObject-Methode und der HasVstoObject-Methode

Verwenden Sie zum Testen eines systemeigenen Office-Objekts die HasVstoObject-Methode und die GetVstoObject-Methode einer Instanz eines der folgenden systemeigenen Office-Objekte:

• Eine Microsoft.Office.Interop.Excel.ListObject.

• Eine Microsoft.Office.Interop.Excel.Workbook.

• Eine Microsoft.Office.Interop.Excel.Worksheet.

• Eine Microsoft.Office.Interop.Word.Document.

Wenn Sie lediglich feststellen möchten, ob das systemeigene Office-Objekt in Ihrer Anpassung über ein erweitertes Objekt verfügt, verwenden Sie die HasVstoObject-Methode. Diese Methode gibt true zurück, wenn das systemeigene Office-Objekt über ein erweitertes Objekt verfügt, andernfalls gibt sie false zurück.

Wenn Sie das erweiterte Objekt abrufen möchten, verwenden Sie die GetVstoObject-Methode. Diese Methode gibt ein Microsoft.Office.Tools.Excel.ListObject-Objekt, ein Microsoft.Office.Tools.Excel.Workbook-Objekt, ein Microsoft.Office.Tools.Excel.Worksheet-Objekt oder ein Microsoft.Office.Tools.Word.Document-Objekt zurück, wenn das systemeigene Office-Objekt über ein solches Objekt verfügt. Andernfalls gibt GetVstoObjectnull zurück. Die GetVstoObject-Methode eines Microsoft.Office.Interop.Word.Document-Objekts gibt z. B. ein Microsoft.Office.Tools.Word.Document zurück, wenn das Microsoft.Office.Interop.Word.Document das zugrunde liegende Objekt für das Dokument in Ihrem Word-Dokumentprojekt ist.

Sie können GetVstoObject nicht in einer Projektmappe auf Dokumentebene verwenden, um zur Laufzeit ein neues Hostelement zu erstellen. Sie können es nur für den Zugriff auf vorhandene Hostelemente verwenden, die zur Entwurfszeit im Projekt generiert werden. Weitere Informationen hierzu finden Sie unter Programmgesteuerte Einschränkungen von Hostelementen und Hoststeuerelementen.

In Projekten auf Anwendungsebene können Sie die GetVstoObject-Methode verwenden, um zur Laufzeit neue Hostelemente zu generieren. Weitere Informationen hierzu finden Sie unter Erweitern von Word-Dokumenten und Excel-Arbeitsmappen in Add-Ins auf Anwendungsebene zur Laufzeit.

Hinweis:

Um die GetVstoObject-Methode und die HasVstoObject-Methode zu verwenden, müssen Sie eine using-Anweisung (bei C#) bzw. eine Imports-Anweisung (bei Visual Basic) für den Microsoft.Office.Tools.Excel.Extensions-Namespace oder den Microsoft.Office.Tools.Word.Extensions-Namespace am Anfang der Codedatei hinzufügen. Die GetVstoObject-Methode und die HasVstoObject-Methode werden in der Visual Studio Tools for Office-Laufzeit als Erweiterungsmethoden implementiert, sodass Sie diese Methoden mit diesen Anweisungen aufrufen können.

Feststellen, ob ein Hostelement ein Ereignis ausgelöst hat

In den folgenden Codebeispielen werden die HasVstoObject-Methode und die GetVstoObject-Methode veranschaulicht. In beiden Beispielen wird das SheetActivate-Ereignis der ThisWorkbook-Klasse in einem Excel-Arbeitsmappenprojekt behandelt.

Im ersten Beispiel wird festgestellt, ob eines der Microsoft.Office.Tools.Excel.Worksheet-Hostelemente aktiviert wurde. Dazu wird der Sh-Parameter mit der InnerObject-Eigenschaft jedes Standardhostelements verglichen.

Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing

    If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet1
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate1(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;

    if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet1;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

Im nächsten Beispiel wird dieser Prozess mithilfe der HasVstoObject-Methode und der GetVstoObject-Methode des Sh-Parameters vereinfacht.

Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso _
        interopWorksheet.HasVstoObject() Then
        vstoWorksheet = interopWorksheet.GetVstoObject()
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet = 
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && interopWorksheet.HasVstoObject())
    {
        vstoWorksheet = interopWorksheet.GetVstoObject();
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

Siehe auch

Konzepte

Programmieren von Anpassungen auf Dokumentebene

Übersicht über Hostelemente und Hoststeuerelemente

Erweitern von Word-Dokumenten und Excel-Arbeitsmappen in Add-Ins auf Anwendungsebene zur Laufzeit

Erweiterungsmethoden (Visual Basic)

Referenz

Erweiterungsmethoden (C#-Programmierhandbuch)

Änderungsprotokoll

Date	Versionsgeschichte	Grund
Juli 2008	Thema hinzugefügt.	SP1-Featureänderung.