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

Artikel
02/26/2013

Sie können Word-Dokumente und Excel-Arbeitsmappen wie folgt mithilfe eines Add-Ins auf Anwendungsebene anpassen:

Hinzufügen von verwalteten Steuerelementen zu geöffneten Dokumenten oder Arbeitsblättern.
Konvertieren eines vorhandenen Listenobjekts in einem Excel-Arbeitsblatt in ein erweitertes ListObject, das Ereignisse verfügbar macht und mit dem Datenbindungsmodell von Windows Forms an Daten gebunden werden kann.
Zugreifen auf Ereignisse auf Anwendungsebene, die von Word und Excel für bestimmte Dokumente, Arbeitsmappen und Arbeitsblätter verfügbar gemacht werden.

Um diese Funktionen verwenden zu können, erstellen Sie zur Laufzeit ein Objekt, mit dem das Dokument oder die Arbeitsmappe erweitert wird.

Gilt für:, das die Informationen in diesem Thema Projekten auf Anwendungsebene die folgenden Anwendungen anwenden: Excel 2010; Word 2010.Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Erstellen von erweiterten Objekten in Add-Ins

Erweiterte Objekte sind Instanzen von Typen, die von den Visual Studio Tools for Office-Laufzeit bereitgestellt werden, die Objekten Funktionalität hinzufügen, die systemeigen im Word- oder Excel-Objektmodell vorhanden sind (aufgerufen systemeigene Office-Objekte bezeichnet).Um ein erweitertes Objekt für ein Word-Objekt oder ein Excel-Objekt zu generieren, verwenden Sie die GetVstoObject-Methode.Beim ersten Aufruf der Methode GetVstoObject für ein angegebenes Word- oder Excel-Objekt aufrufen, wird ein neues Objekt zurück, das das angegebene Objekt erweitert. Immer wenn Sie die Methode aufrufen und das gleiche Word- oder Excel-Objekt angeben, gibt es das gleiche erweiterte Objekt zurück.

Der Typ des erweiterten Objekts hat denselben Namen wie der Typ des systemeigenen Office-Objekts, ist jedoch im Microsoft.Office.Tools.Excel-Namespace oder im Microsoft.Office.Tools.Word-Namespace definiert.Wenn Sie z. B. die GetVstoObject-Methode aufrufen, um ein Microsoft.Office.Interop.Word.Document-Objekt zu erweitern, gibt die Methode ein Microsoft.Office.Tools.Word.Document-Objekt zurück.

Die GetVstoObject-Methoden sind in erster Linie dazu vorgesehen, in Projekten auf Anwendungsebene verwendet zu werden.Sie können diese Methoden auch in Projekten auf Dokumentebene verwenden. Sie zeigen dann jedoch ein anderes Verhalten und haben weniger Anwendungen.

Um zu ermitteln, ob für ein erweitertes Objekt bereits ein bestimmtes systemeigenes Office-Objekt generiert wurde, verwenden Sie die HasVstoObject-Methode.Weitere Informationen finden Sie unter Ermitteln, ob ein Office-Objekt erweitert wurde.

Erstellen von Hostelementen

Wenn Sie GetVstoObject verwenden, um ein Objekt auf Dokumentebene zu erweitern (d. h. Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet oder Microsoft.Office.Interop.Word.Document), wird das zurückgegebene Objekt als Hostelement bezeichnet.Ein Hostelement ist ein Typ, der andere Objekte enthalten kann, einschließlich anderer erweiterter Objekte und Steuerelemente.Es ähnelt dem entsprechenden Typ in der primären Interopassembly von Word oder Excel, verfügt jedoch über zusätzliche Features.Weitere Informationen zu Hostelementen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Nachdem Sie ein Hostelement erstellen, können Sie es verwenden, um verwaltete Steuerelemente dem Dokument, der Arbeitsmappe oder dem Arbeitsblatt hinzuzufügen.Weitere Informationen finden Sie unter Hinzufügen von verwalteten Steuerelementen zu Dokumenten und Arbeitsblättern.

So generieren Sie ein Hostelement für ein Word-Dokument

Im folgenden Codebeispiel wird veranschaulicht, wie ein Hostelement für das aktive Dokument generiert.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

So generieren Sie ein Hostelement für eine Excel-Arbeitsmappe

Im folgenden Codebeispiel wird veranschaulicht, wie ein Hostelement für die aktive Arbeitsmappe generiert.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

So generieren Sie ein Hostelement für ein Excel-Arbeitsblatt

Im folgenden Codebeispiel wird veranschaulicht, wie ein Hostelement für das aktive Arbeitsblatt in einem Projekt generiert.

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Generieren von ListObject-Hoststeuerelementen

Wenn Sie die GetVstoObject-Methode verwenden, um Microsoft.Office.Interop.Excel.ListObject zu erweitern, gibt die Methode ein Microsoft.Office.Tools.Excel.ListObject zurück.Microsoft.Office.Tools.Excel.ListObject verfügt über sämtliche Funktionen des ursprünglichen Microsoft.Office.Interop.Excel.ListObject, besitzt jedoch zusätzliche Funktionen. Dazu gehört die Möglichkeit, das Objekt mithilfe des Datenbindungsmodells von Windows Forms an Daten zu binden.Weitere Informationen finden Sie unter ListObject-Steuerelement.

So erstellen Sie ein Hoststeuerelement für ein ListObject

Im folgenden Codebeispiel wird veranschaulicht, wie Microsoft.Office.Tools.Excel.ListObject für erste Microsoft.Office.Interop.Excel.ListObject im aktiven Arbeitsblatt in einem Projekt generiert.

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

Hinzufügen von verwalteten Steuerelementen zu Dokumenten und Arbeitsblättern

Nachdem Sie ein Microsoft.Office.Tools.Word.Document oder ein Microsoft.Office.Tools.Excel.Worksheet erstellt haben, können Sie dem Dokument oder Arbeitsblatt, das von diesen erweiterten Objekten dargestellt wird, Steuerelemente hinzufügen.Verwenden Sie dafür die Controls-Eigenschaft des Microsoft.Office.Tools.Word.Document oder des Microsoft.Office.Tools.Excel.Worksheet.Weitere Informationen hierzu finden Sie unter Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit.

Sie können Windows Forms-Steuerelemente oder Hoststeuerelemente hinzufügen.Ein Hoststeuerelement ist ein von der Visual Studio-Tools für Office-Laufzeit bereitgestelltes Steuerelement, das ein entsprechendes Steuerelement in der primären Interopassembly von Word oder Excel umschließt.Ein Hoststeuerelement macht das Verhalten des zugrunde liegenden systemeigenen Office-Objekts verfügbar. Es löst jedoch auch Ereignisse aus und kann mithilfe des Datenbindungsmodells von Windows Forms an Daten gebunden werden.Weitere Informationen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Hinweis
Sie können ein Steuerelement XmlMappedRange weder einem Arbeitsblatt oder ein XMLNode oder XMLNodes-Steuerelement hinzufügen, indem Sie einem Dokument ein Add-In verwenden.Diese Hoststeuerelemente können nicht programmgesteuert hinzugefügt werden.Weitere Informationen finden Sie unter Programmgesteuerte Einschränkungen von Hostelementen und Hoststeuerelementen.

Beibehalten und Entfernen von Steuerelementen

Wenn einem Dokument oder Arbeitsblatt verwaltete Steuerelemente hinzugefügt werden, werden die Steuerelemente beim Speichern und Schließen des Dokuments nicht beibehalten.Alle Hoststeuerelemente werden entfernt, sodass nur die zugrunde liegenden systemeigenen Office-Objekte zurückbleiben werden.Beispielsweise wird Microsoft.Office.Tools.Excel.ListObject Microsoft.Office.Interop.Excel.ListObject.Windows Forms-Steuerelemente werden ebenfalls entfernt, die ActiveX-Wrapper für die Steuerelemente verbleiben jedoch im Dokument.Sie müssen im Add-In Code zur Bereinigung der Steuerelemente sowie zur Neuerstellung der Steuerelemente beim nächsten Öffnen des Dokuments hinzufügen.Weitere Informationen finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

Zugreifen auf Ereignisse auf Anwendungsebene bei Dokumenten und Arbeitsmappen

Manche Dokument-, Arbeitsmappen- und Arbeitsblattereignisse im systemeigenen Word- und Excel-Objektmodell werden nur auf Anwendungsebene ausgelöst.Zum Beispiel wird das DocumentBeforeSave-Ereignis ausgelöst, wenn ein Dokument in Word geöffnet wird. Dieses Ereignis wird jedoch in der Microsoft.Office.Interop.Word.Application-Klasse und nicht in der Microsoft.Office.Interop.Word.Document-Klasse definiert.

Wenn Sie in einem Add-In nur systemeigene Office-Objekte verwenden, müssen Sie diese Ereignisse auf Anwendungsebene behandeln und zusätzlichen Code schreiben, mit dem ermittelt wird, ob es sich bei dem Dokument, das das Ereignis ausgelöst hat, um das von Ihnen angepasste Dokument handelt.Hostelemente stellen diese Ereignisse auf der Dokumentebene bereit, sodass es einfacher ist, die Ereignisse für ein bestimmtes Dokument zu behandeln.Sie können ein Hostelement erstellen und dann das Ereignis für dieses Hostelement behandeln.

Beispiel zum Verwenden systemeigener Word-Objekte

Im folgenden Codebeispiel wird veranschaulicht, wie ein Ereignis auf Anwendungsebene für Word-Dokumente behandelt wird.Die CreateDocument-Methode erstellt ein neues Dokument und definiert dann einen DocumentBeforeSave-Ereignishandler, der das Speichern des Dokuments verhindert.Da es sich um ein Ereignis auf Anwendungsebene handelt, das für das Microsoft.Office.Interop.Word.Application-Objekt ausgelöst wird, muss der Ereignishandler den Doc-Parameter mit dem document1-Objekt vergleichen, um zu ermitteln, ob document1 das gespeicherte Dokument darstellt.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Beispiele zum Verwenden eines Hostelements

In den folgenden Codebeispielen wird dieser Prozess vereinfacht, indem das BeforeSave-Ereignis eines Microsoft.Office.Tools.Word.Document-Hostelements behandelt wird.Die CreateDocument2-Methode in diesen Beispielen generiert ein Microsoft.Office.Tools.Word.Document, das das document2-Objekt erweitert. Daraufhin wird ein BeforeSave-Ereignishandler definiert, der das Speichern des Dokuments verhindert.Da dieser Ereignishandler nur aufgerufen wird, wenn document2 gespeichert wird, kann der Ereignishandler den Speichervorgang abbrechen, ohne zusätzlich überprüfen zu müssen, welches Dokument gespeichert wird.

Im folgenden Codebeispiel wird diese Aufgabe.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Ermitteln, ob ein Office-Objekt erweitert wurde

Um zu ermitteln, ob für ein erweitertes Objekt bereits ein bestimmtes systemeigenes Office-Objekt generiert wurde, verwenden Sie die HasVstoObject-Methode.Diese Methode gibt true zurück, wenn bereits ein erweitertes Objekt generiert wurde. Andernfalls gibt sie false zurück.

Verwenden Sie die Globals.Factory.HasVstoMethod-Methode.Übergeben Sie das systemeigene Word-Objekt oder Excel-Objekt, wie Microsoft.Office.Interop.Word.Document oder Microsoft.Office.Interop.Excel.Worksheet, die Sie für ein erweitertes Objekt testen möchten.

Die HasVstoObject-Methode ist sinnvoll, wenn Code nur dann ausgeführt werden soll, wenn ein bestimmtes Office-Objekt über ein erweitertes Objekt verfügt.Wenn Sie zum Beispiel ein Word-Add-In verwenden, das das DocumentBeforeSave-Ereignis behandelt, um vor dem Speichern verwaltete Steuerelemente aus einem Dokument zu entfernen, können Sie die HasVstoObject-Methode verwenden, um zu ermitteln, ob das Dokument erweitert wurde.Wenn das Dokument nicht erweitert wurde, kann es keine verwalteten Steuerelemente enthalten und die Ausführung des Ereignishandlers kann beendet werden, ohne Steuerelemente aus dem Dokument zu entfernen.

Siehe auch

Konzepte

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

Übersicht über Hostelemente und Hoststeuerelemente

Weitere Ressourcen

Programmieren von Add-Ins auf Anwendungsebene

Beispiele und exemplarische Vorgehensweisen für die Programmierung mit Office

Freigeben über