Beibehalten von dynamischen Steuerelementen in Office-Dokumenten

Aktualisiert: Juli 2008

Zur Laufzeit hinzugefügte Steuerelemente werden nicht beibehalten, wenn das Dokument oder die Arbeitsmappe gespeichert und geschlossen wird. Das genaue Verhalten unterscheidet sich für Hoststeuerelemente und Windows Forms-Steuerelemente. In beiden Fällen können Sie der Projektmappe Code hinzufügen, damit die Hoststeuerelemente neu erstellt werden, wenn der Benutzer das Dokument erneut öffnet.

Steuerelemente, die Sie Dokumenten zur Laufzeit hinzufügen, werden als dynamische Steuerelemente bezeichnet. Weitere Informationen zu dynamischen Steuerelementen finden Sie unter Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit.

Beibehalten von Hoststeuerelementen im Dokument

Beim Speichern und Schließen eines Dokuments werden alle dynamischen Hoststeuerelemente aus dem Dokument entfernt. Nur die zugrunde liegenden systemeigenen Office-Objekte bleiben zurück. Zum Beispiel wird ein Microsoft.Office.Tools.Excel.ListObject-Hoststeuerelement ein Microsoft.Office.Interop.Excel.ListObject. Die systemeigenen Office-Objekte sind nicht mit den Hoststeuerelement-Ereignissen verbunden, und sie haben nicht die Datenbindungsfunktion des Hoststeuerelements.

In der folgenden Tabelle sind die systemeigenen Office-Objekte aufgeführt, die für jeden Typ von Hoststeuerelement in einem Dokument zurückbleiben.

Neuerstellen von Hoststeuerelementen beim Öffnen von Dokumenten

Sie können bei jedem Öffnen des Dokuments durch einen Benutzer dynamische Hoststeuerelemente anstelle von vorhandenen systemeigenen Steuerelementen neu erstellen. Das Erstellen von Hoststeuerelementen auf diese Weise, wenn ein Dokument geöffnet wird, simuliert das vom Benutzer erwartete Verhalten.

Verwenden Sie zum Neuerstellen eines Hoststeuerelements für Word, oder eines Microsoft.Office.Tools.Excel.NamedRange-Hoststeuerelements oder eines Microsoft.Office.Tools.Excel.ListObject-Hoststeuerelements für Excel eine Add<control class>-Methode der Microsoft.Office.Tools.Excel.ControlCollection-Klasse oder der Microsoft.Office.Tools.Word.ControlCollection-Klasse, die über einen Parameter für das systemeigene Office-Objekt verfügt.

Wenn Sie z. B. bei geöffnetem Dokument ein Microsoft.Office.Tools.Excel.ListObject-Hoststeuerelement aus einem vorhandenen systemeigenen Microsoft.Office.Interop.Excel.ListObject beim Öffnen des Dokuments erstellen möchten, verwenden Sie die AddListObject(ListObject)-Methode und übergeben das vorhandene Microsoft.Office.Interop.Excel.ListObject. Im folgenden Codebeispiel wird dies in einem Projekt auf Dokumentebene für Excel 2007 veranschaulicht. Der Code erstellt ein dynamisches Microsoft.Office.Tools.Excel.ListObject neu, das auf einem vorhandenen Microsoft.Office.Interop.Excel.ListObject mit dem Namen MyListObject in der Sheet1-Klasse basiert.

Private vstoListObject As Microsoft.Office.Tools.Excel.ListObject
Private Const DISP_E_BADINDEX As Integer = CInt(&H8002000B)

Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    Dim nativeListObject As Excel.ListObject = Nothing

    Try
        nativeListObject = Me.ListObjects("MyListObject")
    Catch ex As System.Runtime.InteropServices.COMException
        ' "MyListObject" does not exist.
        If ex.ErrorCode <> DISP_E_BADINDEX Then
            Throw
        End If
    End Try

    If nativeListObject IsNot Nothing Then
        vstoListObject = Me.Controls.AddListObject(nativeListObject)
    End If
End Sub

private Microsoft.Office.Tools.Excel.ListObject vstoListObject;
private const int DISP_E_BADINDEX = unchecked((int)0x8002000B);

private void Sheet1_Startup(object sender, System.EventArgs e)
{
    Excel.ListObject nativeListObject = null;

    try
    {
        nativeListObject = this.ListObjects.get_Item("MyListObject");
    }
    catch (System.Runtime.InteropServices.COMException ex)
    {
        // "MyListObject" does not exist.
        if (ex.ErrorCode != DISP_E_BADINDEX)
            throw;
    }

    if (nativeListObject != null)
    {
        vstoListObject = this.Controls.AddListObject(nativeListObject);
    }
}

Beispiele auf Dokumentebene, in denen dynamische Steuerelemente veranschaulicht werden, finden Sie unter Beispiel für dynamische Excel-Steuerelemente und unter Beispiel für dynamische Steuerelemente in Word.

Beispiele auf Anwendungsebene, in denen dynamische Steuerelemente veranschaulicht werden, finden Sie unter Beispiel für dynamische Add-In-Steuerelemente in Excel und unter Beispiel für dynamische Add-In-Steuerelemente in Word.

Neuerstellen von ListObjects in Excel 2003-Projekten und Excel 2007-Projekten vor SP1

Die AddListObject(ListObject)-Methode ist für Excel 2007-Projekte in Visual Studio 2008 Service Pack 1 (SP1) neu. Wenn Sie mit einem Excel 2007-Projekt arbeiten und SP1 nicht installiert ist oder wenn Sie mit einem Excel 2003-Projekt arbeiten, können Sie mit dieser Methode kein dynamisches Microsoft.Office.Tools.Excel.ListObject neu erstellen.

Stattdessen müssen Sie zuerst das systemeigene Microsoft.Office.Interop.Excel.ListObject löschen und anschließend das dynamische Microsoft.Office.Tools.Excel.ListObject mithilfe der AddListObject(Range, String)-Methode neu erstellen. Code, in dem dies veranschaulicht wird, finden Sie unter Beispiel für dynamische Excel-Steuerelemente.

Wenn Sie nicht zuerst das systemeigene Microsoft.Office.Interop.Excel.ListObject löschen, wird eine COMException ausgelöst, wenn Sie versuchen, das Microsoft.Office.Tools.Excel.ListObject neu zu erstellen, da das Erstellen von überlappenden Listenobjekten in Excel nicht zulässig ist.

Neuerstellen von Diagrammen

Zum Neuerstellen eines Microsoft.Office.Tools.Excel.Chart-Hoststeuerelements müssen Sie zuerst das systemeigene Microsoft.Office.Interop.Excel.Chart löschen und anschließend das Microsoft.Office.Tools.Excel.Chart mithilfe der AddChart(Range, String)-Methode oder der AddChart(Double, Double, Double, Double, String)-Methode neu erstellen. Es ist keine Add<control class> -Methode vorhanden, mit der Sie ein neues Microsoft.Office.Tools.Excel.Chart auf der Grundlage eines vorhandenen Microsoft.Office.Interop.Excel.Chart erstellen können.

Wenn Sie nicht zuerst das systemeigene Microsoft.Office.Interop.Excel.Chart löschen, erstellen Sie beim Neuerstellen des Microsoft.Office.Tools.Excel.Chart ein zweites Diagramm (ein Duplikat).

Beibehalten von Windows Forms-Steuerelementen in Dokumenten

Beim Speichern und Schließen eines Dokuments werden alle dynamisch erstellten Windows Forms-Steuerelemente durch die Visual Studio Tools for Office-Laufzeit automatisch aus dem Dokument entfernt. Das Verhalten unterscheidet sich jedoch für Projekte auf Dokumentebene und für Projekte auf Anwendungsebene.

In Anpassungen auf Dokumentebene werden die Steuerelemente und ihre zugrunde liegenden ActiveX-Wrapper (die für das Hosten der Steuerelemente in dem Dokument verwendet werden) beim nächsten Öffnen des Dokuments entfernt. Es gibt keinen Hinweis darauf, dass die Steuerelemente jemals dort waren.

In Add-Ins auf Anwendungsebene werden die Steuerelemente entfernt, aber die ActiveX-Wrapper bleiben im Dokument. Wenn der Benutzer das Dokument das nächste Mal öffnet, sind die ActiveX-Wrapper sichtbar. In Excel werden die ActiveX-Wrapper als Abbildungen der Steuerelemente dargestellt, so wie diese beim letzten Speichern des Dokuments erschienen sind. In Word sind die ActiveX-Wrapper nicht sichtbar, sofern der Benutzer nicht darauf klickt. In diesem Fall werden sie als gestrichelte Linie dargestellt, die den Rand der Steuerelemente darstellt. Es gibt mehrere Möglichkeiten zum Entfernen der ActiveX-Wrapper. Weitere Informationen finden Sie unter Entfernen von ActiveX-Wrappern in einem Add-In.

Neuerstellen von Windows Forms-Steuerelementen beim Öffnen von Dokumenten

Sie können gelöschte Windows Forms-Steuerelemente neu erstellen, wenn der Benutzer das Dokument erneut öffnet. Hierzu muss die Projektmappe die folgenden Aufgaben ausführen:

1. Sie muss beim Speichern oder Schließen des Dokuments Informationen über die Größe, die Position und den Zustand der Steuerelemente speichern. In einer Anpassung auf Dokumentebene können Sie diese Daten im Datencache im Dokument speichern. In einem Add-In auf Anwendungsebene können Sie diese Daten zu einem benutzerdefinierten XML-Abschnitt im Dokument speichern.

2. Erstellen Sie die Steuerelemente in einem Ereignis neu, das beim Öffnen des Dokuments ausgelöst wird. In Projekten auf Dokumentebene kann dies im Sheetn_Startup-Ereignishandler oder im ThisDocument_Startup-Ereignishandler erfolgen. In Projekten auf Anwendungsebene kann dies in den Ereignishandlern für das WorkbookOpen-Ereignis oder das DocumentOpen-Ereignis erfolgen.

Beispiele auf Dokumentebene, in denen dynamische Steuerelemente veranschaulicht werden, finden Sie unter Beispiel für dynamische Excel-Steuerelemente und unter Beispiel für dynamische Steuerelemente in Word.

Beispiele für die Anwendungsebene finden Sie unter Beispiel für dynamische Add-In-Steuerelemente in Excel und Beispiel für dynamische Add-In-Steuerelemente in Word.

Entfernen von ActiveX-Wrappern in einem Add-In

Wenn Sie mit einem Add-In dynamische Steuerelemente zu Dokumenten hinzufügen, können Sie auf folgende Weise verhindern, dass die ActiveX-Wrapper für die Steuerelemente beim nächsten Öffnen im Dokument erscheinen.

Entfernen von ActiveX-Wrappern, wenn das Dokument geöffnet wird

Um alle ActiveX-Wrapper zu entfernen, rufen Sie die GetVstoObject-Methode von Microsoft.Office.Interop.Word.Document oder Microsoft.Office.Interop.Excel.Workbook, die das neu geöffnete Dokument repräsentiert, auf. Um beispielsweise alle ActiveX-Wrapper aus einem Word-Dokument zu entfernen, können Sie die GetVstoObject-Methode des Document-Objekts aufrufen, das für das DocumentOpen-Ereignis an den Ereignishandler weitergegeben wird.

Diese Vorgehensweise ist nützlich, wenn Sie wissen, dass das Dokument nur auf Computern geöffnet wird, auf denen das Add-In installiert ist. Wenn das Dokument an andere Benutzer weitergegeben werden könnte, die das Add-In nicht installiert haben, sollten Sie das Entfernen der Steuerelemente vor dem Schließen des Dokuments erwägen.

Im folgenden Codebeispiel wird veranschaulicht, wie die GetVstoObject-Methode beim Öffnen des Dokuments aufgerufen wird.

Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
    ByVal Doc As Word.Document) Handles Application.DocumentOpen
    Dim vstoDocument As Microsoft.Office.Tools.Word.Document = Doc.GetVstoObject()
End Sub

private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
    Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
}

Die GetVstoObject-Methode wird zwar primär verwendet, um ein neues Hostelement zur Laufzeit zu generieren, aber diese Methode löscht auch alle ActiveX-Wrapper aus dem Dokument, wenn sie zum ersten Mal für ein bestimmtes Dokument aufgerufen wird. Weitere Informationen zum Verwenden der GetVstoObject-Methode finden Sie unter Erweitern von Word-Dokumenten und Excel-Arbeitsmappen in Add-Ins auf Anwendungsebene zur Laufzeit.

Beachten Sie: Wenn Ihr Add-In beim Öffnen des Dokuments dynamische Steuerelemente erstellt, ruft Ihr Add-In im Rahmen des Prozesses zum Erstellen der Steuerelemente bereits die GetVstoObject-Methode auf. Sie müssen in diesem Szenario keinen zusätzlichen Aufruf der GetVstoObject-Methode einfügen, um die ActiveX-Wrapper zu entfernen.

Entfernen der dynamischen Steuerelemente vor dem Schließen des Dokuments

Das Add-In kann jedes dynamische Steuerelement aus dem Dokument explizit entfernen, bevor das Dokument geschlossen wird. Diese Vorgehensweise ist nützlich für Dokumente, die an Benutzer weitergegeben werden könnten, auf deren Computern das Add-In nicht installiert ist.

Das folgende Codebeispiel veranschaulicht das Entfernen aller Windows Forms-Steuerelemente aus einem Word-Dokument beim Schließen des Dokuments.

Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
    ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose

    If Doc.HasVstoObject() Then
        Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
            Doc.GetVstoObject()
        Dim controlsToRemove As System.Collections.ArrayList = _
            New System.Collections.ArrayList()

        ' Get all of the Windows Forms controls.
        For Each control As Object In vstoDocument.Controls
            If TypeOf control Is System.Windows.Forms.Control Then
                controlsToRemove.Add(control)
            End If
        Next

        ' Remove all of the Windows Forms controls from the document.
        For Each control As Object In controlsToRemove
            vstoDocument.Controls.Remove(control)
        Next
    End If
End Sub

void Application_DocumentBeforeClose(Word.Document Doc, ref bool Cancel)
{
    if (Doc.HasVstoObject())
    {
        Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
        System.Collections.ArrayList controlsToRemove = 
            new System.Collections.ArrayList();

        // Get all of the Windows Forms controls.
        foreach (object control in vstoDocument.Controls)
        {
            if (control is System.Windows.Forms.Control)
            {
                controlsToRemove.Add(control);
            }
        }

        // Remove all of the Windows Forms controls from the document.
        foreach (object control in controlsToRemove)
        {
            vstoDocument.Controls.Remove(control);
        }
    }
}

Siehe auch

Aufgaben

Beispiel für dynamische Excel-Steuerelemente

Beispiel für dynamische Steuerelemente in Word

Beispiel für dynamische Add-In-Steuerelemente in Excel

Beispiel für dynamische Add-In-Steuerelemente in Word

Konzepte

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

Hilfsmethoden für Hoststeuerelemente

Hilfsmethoden für Windows Forms-Steuerelemente

Änderungsprotokoll