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

  • Artikel

Sie können ein VSTO-Add-In verwenden, um Word-Dokumente und Excel-Arbeitsmappen wie folgt anzupassen:

  • Fügen Sie geöffneten Dokumenten oder Arbeitsblättern verwaltete Steuerelemente hinzu.

  • Konvertieren Sie ein vorhandenes Listenobjekt in einem Excel-Arbeitsblatt in ein erweitertes ListObject -Element, mit dem Ereignisse verfügbar gemacht werden und das mit dem Windows Forms-Datenbindungsmodell an Daten gebunden werden kann.

  • Greifen Sie auf Ereignisse auf Anwendungsebene zu, die von Word und Excel für bestimmte Dokumente, Arbeitsmappen und Arbeitsblätter verfügbar gemacht werden.

    Zum Verwenden dieser Funktionalität generieren Sie zur Laufzeit ein Objekt, mit dem das Dokument oder die Arbeitsmappe erweitert werden.

    Betrifft: Die Informationen in diesem Artikel betreffen VSTO-Add-In-Projekte für die folgenden Anwendungen: Excel und Word. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Generieren von erweiterten Objekten in VSTO-Add-Ins

Erweiterte Objekte sind Instanzen von Typen, die über die Visual Studio-Tools für Office-Laufzeit bereitgestellt werden. Hiermit wird Objekten Funktionalität hinzugefügt, die als systemeigene Elemente im Word- oder Excel-Objektmodell vorhanden sind (als systemeigene Office-Objektebezeichnet). Verwenden Sie die GetVstoObject-Methode, um ein erweitertes Objekt für ein Word- oder Excel-Objekt zu generieren. Wenn Sie die GetVstoObject-Methode zum ersten Mal für ein angegebenes Word- oder Excel-Objekt aufrufen, wird ein neues Objekt zurückgegeben, das das angegebene Objekt erweitert. Bei jedem Aufrufen der Methode und Angeben des gleichen Word- oder Excel-Objekts wird dasselbe erweiterte Objekt zurückgegeben.

Der Typ des erweiterten Objekts hat den gleichen Namen wie der Typ des systemeigenen Office-Objekts, aber der Typ wird im Namespace Microsoft.Office.Tools.Excel oder Microsoft.Office.Tools.Word definiert. Wenn Sie beispielsweise die GetVstoObject-Methode zum Erweitern eines Document-Objekts aufrufen, gibt die Methode ein Document-Objekt zurück.

Die GetVstoObject-Methoden sind hauptsächlich für die Verwendung in VSTO-Add-In-Projekten vorgesehen. Sie können diese Methoden auch in Projekten auf Dokumentebene verwenden. Hierbei weisen sie aber ein anderes Verhalten und weniger Anwendungsmöglichkeiten auf.

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

Generieren von Hostelementen

Wenn Sie mit dem GetVstoObject ein Objekt auf Dokumentebene erweitern (d. h. ein Workbook, Worksheet oder Document), wird das zurückgegebene Objekt als Hostelement bezeichnet. Ein Hostelement ist ein Typ, der andere Objekte enthalten kann, z. B. andere erweiterte Objekte und Steuerelemente. Der Typ ähnelt dem entsprechenden Typ in den primären Interopassemblys von Word oder Excel, verfügt aber über zusätzliche Funktionen. Weitere Informationen zu Hostelementen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Nachdem Sie ein Hostelement generiert haben, können Sie es verwenden, um dem Dokument, der Arbeitsmappe oder dem Arbeitsblatt verwaltete Steuerelemente 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 Sie ein Hostelement für das aktive Dokument generieren.

    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 Sie ein Hostelement für die aktive Arbeitsmappe generieren.

    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 Sie ein Hostelement für das aktive Arbeitsblatt in einem Projekt generieren.

    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 zum Erweitern eines ListObject-Elements verwenden, gibt die Methode ein ListObject-Element zurück. Das ListObject verfügt über alle Funktionen des ursprünglichen ListObject. Außerdem verfügt es über zusätzliche Funktionen und kann mithilfe des Windows Forms-Datenbindungsmodells an Daten gebunden werden. Weitere Informationen finden Sie unter ListObject-Steuerelement.

So generieren Sie ein Hoststeuerelement für ein ListObject-Steuerelement

  • Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein ListObject -Element für das erste ListObject -Element im aktiven Arbeitsblatt eines Projekts generieren.

    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

Nach dem Generieren eines Document - oder Worksheet-Elements können Sie dem Dokument oder Arbeitsblatt, für das diese erweiterten Objekte stehen, Steuerelemente hinzufügen. Verwenden Sie zum Hinzufügen von Steuerelementen die Controls-Eigenschaft des Document oder Worksheet. Weitere Informationen finden Sie unter Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit.

Sie können Windows Forms-Steuerelemente oder Hoststeuerelementehinzufügen. Ein Hoststeuerelement ist ein Steuerelement, das von Visual Studio-Tools für Office-Laufzeit bereitgestellt wird und mit dem ein entsprechendes Steuerelement in der primären Word- oder Excel-Interopassembly eingeschlossen wird. Ein Hoststeuerelement macht das gesamte Verhalten des zugrunde liegenden systemeigenen Office-Objekts verfügbar. Außerdem löst es Ereignisse aus und kann mithilfe des Windows Forms-Datenbindungsmodells an Daten gebunden werden. Weitere Informationen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Hinweis

Es ist nicht möglich, ein XmlMappedRange -Steuerelement einem Arbeitsblatt oder ein XMLNode - oder XMLNodes -Steuerelement einem Dokument per VSTO-Add-In hinzuzufügen. 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 Sie einem Dokument oder Arbeitsblatt verwaltete Steuerelemente hinzufügen, werden die Steuerelemente nicht beibehalten, wenn das Dokument gespeichert und anschließend geschlossen wird. Alle Hoststeuerelemente werden entfernt, sodass nur die zugrunde liegenden systemeigenen Office-Objekte übrig bleiben. Beispielsweise wird ein ListObject -Element zu einem ListObject-Element. Außerdem werden alle Windows Forms-Steuerelemente entfernt, aber ActiveX-Wrapper für die Steuerelemente im Dokument bleiben erhalten. Sie müssen in Ihr VSTO-Add-In Code zum Bereinigen der Steuerelemente oder zum Neuerstellen der Steuerelemente beim nächsten Öffnen des Dokuments einfügen. Weitere Informationen finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

Zugreifen auf Ereignisse auf Anwendungsebene in Dokumenten und Arbeitsmappen

Einige Dokument-, Arbeitsmappen und Arbeitsblattereignisse in systemeigenen Word- und Excel-Objektmodellen werden nur auf Anwendungsebene ausgelöst. Beispielsweise wird das DocumentBeforeSave -Ereignis ausgelöst, wenn ein Dokument in Word geöffnet wird. Dieses Ereignis ist aber in der Application -Klasse definiert, nicht in der Document -Klasse.

Wenn Sie in Ihrem VSTO-Add-In nur systemeigene Office-Objekte verwenden, müssen Sie diese Ereignisse auf Anwendungsebene behandeln. Anschließend müssen Sie zusätzlichen Code schreiben, um zu ermitteln, ob das Dokument, von dem das Ereignis ausgelöst wurde, ein von Ihnen angepasstes Dokument ist. Hostelemente stellen diese Ereignisse auf Dokumentebene bereit, damit es einfacher ist, die Ereignisse für ein bestimmtes Dokument zu behandeln. Sie können ein Hostelement generieren und dann das Ereignis für dieses Hostelement behandeln.

Beispiel für die Verwendung systemeigener Word-Objekte

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Ereignis auf Anwendungsebene für Word-Dokumente behandeln. Mit der CreateDocument -Methode wird ein neues Dokument erstellt und dann ein DocumentBeforeSave -Ereignishandler definiert, der verhindert, dass dieses Dokument gespeichert wird. Das Ereignis wird auf Anwendungsebene für das Application-Objekt ausgelöst. Zudem muss der Ereignishandler den Parameter Doc mit dem document1-Objekt vergleichen und feststellen, ob document1 das gespeicherte Dokument darstellt.

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, in denen ein Hostelement verwendet wird

In den folgenden Codebeispielen wird dieser Prozess vereinfacht, indem das BeforeSave -Ereignis eines Document -Hostelements behandelt wird. Mit der CreateDocument2-Methode wird in diesen Beispielen ein Document-Element zum Erweitern des document2-Objekts generiert. Anschließend wird ein BeforeSave-Ereignishandler definiert, der das Speichern des Dokuments verhindert. Der Ereignishandler wird nur aufgerufen, wenn document2 gespeichert wird. Er kann die Speicheraktion abbrechen, ohne dass zusätzlicher Aufwand zur Überprüfung des Dokumentspeichervorgangs anfällt.

Diese Aufgabe wird im folgenden Codebeispiel veranschaulicht.

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

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

Sie verwenden die Globals.Factory.HasVstoObject-Methode. Übergeben Sie das systemeigene Word- oder Excel-Objekt, z. B. Document oder Worksheet, das Sie für ein erweitertes Objekt testen möchten.

Die HasVstoObject-Methode ist nützlich, falls Code nur ausgeführt werden soll, wenn ein bestimmtes Office-Objekt über ein erweitertes Objekt verfügt. Wenn Sie beispielsweise über ein Word-VSTO-Add-In verfügen, das das DocumentBeforeSave-Ereignis verarbeitet, um verwaltete Steuerelemente vor dem Speichern aus einem Dokument zu entfernen, können Sie mit der HasVstoObject-Methode bestimmen, ob das Dokument erweitert wurde. Wenn das Dokument nicht erweitert wurde, kann es keine verwalteten Steuerelemente enthalten und der Ereignishandler kann die Rückgabe durchführen, ohne zu versuchen, Steuerelemente im Dokument zu bereinigen.

Zugehöriger Inhalt