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

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 Anwendungsebene Microsoft Office-Version Excel 2007 Word 2007 Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

Ab Visual Studio 2008 Service Pack 1 (SP1) können Sie mit einem Add-In auf Anwendungsebene Dokumente und Arbeitsmappen folgendermaßen anpassen:

• Hinzufügen von verwalteten Steuerelementen zu geöffneten Dokumenten oder Arbeitsblättern.

• Erstellen von Smarttags, die in einem bestimmten Dokument oder einer bestimmten Arbeitsmappe erkannt werden.

• Konvertieren eines vorhandenen Listenobjekts in einem Excel-Arbeitsblatt in ein Visual Studio Tools for Office-Listenobjekt, 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 Visual Studio Tools for Office-Objekt, mit dem das Dokument oder die Arbeitsmappe erweitert wird.

Erstellen von erweiterten Objekten in Add-Ins

Erweiterte Objekte 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). Um ein erweitertes Objekt in einem Add-In zu erstellen, verwenden Sie die GetVstoObject-Methode einer Instanz eines der folgenden Typen in den primären Interopassemblys von Excel und Word:

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

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

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

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

Beim ersten Aufruf der GetVstoObject-Methode eines systemeigenen Office-Objekts wird ein neues Visual Studio Tools for Office-Objekt zurückgegeben, das das Objekt erweitert. Bei jedem Aufruf der Methode für das gleiche systemeigene Office-Objekt wird das gleiche erweiterte Objekt zurückgegeben. 

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. Beispielsweise gibt die GetVstoObject-Methode eines Microsoft.Office.Interop.Word.Document-Objekts ein Microsoft.Office.Tools.Word.Document zurück.

Verwenden Sie die HasVstoObject-Methode des Office-Objekts zum Ermitteln, ob ein Visual Studio Tools for Office-Objekt bereits für ein bestimmtes systemeigenes Office-Objekt erstellt wurde. Weitere Informationen finden Sie unter Ermitteln, ob ein Office-Objekt erweitert wurde.

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. Weitere Informationen hierzu finden Sie unter Abrufen von erweiterten Objekten aus systemeigenen Office-Objekten in Anpassungen auf Dokumentebene.

Hinweis:
Sie müssen Ihr Projekt ändern, um die GetVstoObject-Methode und die HasVstoObject-Methode in einer von ThisAddIn.cs und ThisAddIn.vb verschiedenen Codedatei oder in einem Projekt zu verwenden, das Sie vor der Installation von SP1 erstellt haben. Weitere Informationen finden Sie unter Konfigurieren des Projekts zur Verwendung der 'GetVstoObject'-Methode und der 'HasVstoObject'-Methode.

Erstellen von Hostelementen

Wenn Sie die GetVstoObject-Methode eines Objekts auf Dokumentebene verwenden, d. h. eines Objekts vom Typ 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 erstellt haben, können Sie es verwenden, um dem Dokument, der Arbeitsmappe oder dem Arbeitsblatt Smarttags oder verwaltete Steuerelemente hinzuzufügen. Weitere Informationen finden Sie unter Hinzufügen von Smarttags zu Dokumenten und Arbeitsmappen und Hinzufügen von verwalteten Steuerelementen zu Dokumenten und Arbeitsblättern.

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

• Verwenden Sie die GetVstoObject-Methode eines Microsoft.Office.Interop.Word.Document. Im folgenden Codebeispiel wird ein Hostelement für das aktive Dokument erstellt.

  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 = _
          NativeDocument.GetVstoObject()
  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 =
          nativeDocument.GetVstoObject();
  }
  

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

• Verwenden Sie die GetVstoObject-Methode einer Microsoft.Office.Interop.Excel.Workbook. Im folgenden Codebeispiel wird ein Hostelement für die aktive Arbeitsmappe erstellt.

  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 = _
          NativeWorkbook.GetVstoObject()
  End If
  

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

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

• Verwenden Sie die GetVstoObject-Methode eines Microsoft.Office.Interop.Excel.Worksheet. Im folgenden Codebeispiel wird ein Hostelement für das aktive Arbeitsblatt erstellt.

  Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
      TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
      Microsoft.Office.Interop.Excel.Worksheet)
  
  If NativeSheet IsNot Nothing Then
      Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
          NativeSheet.GetVstoObject()
  End If
  

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

Generieren von ListObject-Hoststeuerelementen

Wenn Sie die GetVstoObject-Methode eines Microsoft.Office.Interop.Excel.ListObject verwenden, gibt die Methode ein Microsoft.Office.Tools.Excel.ListObject zurück. Das erstellte Microsoft.Office.Tools.Excel.ListObject verfügt über sämtliche Features 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 hierzu finden Sie unter ListObject-Steuerelement.

So erstellen Sie ein Hoststeuerelement für ein ListObject

• Verwenden Sie die GetVstoObject-Methode eines Microsoft.Office.Interop.Excel.ListObject. Im folgenden Codebeispiel wird ein Microsoft.Office.Tools.Excel.ListObject für das erste Microsoft.Office.Interop.Excel.ListObject im aktiven Arbeitsblatt erstellt.

  Dim sheet As 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 = _
          listObject.GetVstoObject()
  End If
  

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

Hinzufügen von Smarttags zu Dokumenten und Arbeitsmappen

Nachdem Sie ein Microsoft.Office.Tools.Word.Document oder eine Microsoft.Office.Tools.Excel.Workbook erstellt haben, können Sie ein Smarttag erstellen, das im Kontext des Dokuments oder der Arbeitsmappe erkannt wird, die von diesen Objekte dargestellt wird. Verwenden Sie dafür die VstoSmartTags-Eigenschaft des Microsoft.Office.Tools.Word.Document oder der Microsoft.Office.Tools.Excel.Workbook. Weitere Informationen finden Sie unter den folgenden Themen:

• Gewusst wie: Hinzufügen von Smarttags zu Word-Dokumenten

• Gewusst wie: Hinzufügen von Smarttags zu Excel-Arbeitsmappen

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 Visual Studio Tools for Office-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 hierzu finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Hinweis:
Sie können mithilfe eines Add-Ins weder einem Arbeitsblatt ein XmlMappedRange-Steuerelement, noch einem Dokument ein XMLNode-Steuerelement oder ein XMLNodes-Steuerelement hinzufügen. Diese Hoststeuerelemente können nicht programmgesteuert hinzugefügt werden. Weitere Informationen hierzu 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 (zum Beispiel wird ein Microsoft.Office.Tools.Excel.ListObject zu einem 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 hierzu 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 CreateDocument1-Methode in diesem Beispiel 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;
    }
}

Beispiel zum Verwenden eines Hostelements

Im folgenden Codebeispiel wird dieser Prozess vereinfacht, indem das BeforeSave-Ereignis eines Microsoft.Office.Tools.Word.Document-Hostelements behandelt wird. Die CreateDocument2-Methode in diesem Beispiel erstellt 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.

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 = document2.GetVstoObject()
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 = document2.GetVstoObject();
    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 bestimmtes systemeigenes Office-Objekt bereits ein Visual Studio Tools for Office-Objekt erstellt wurde, verwenden Sie die HasVstoObject-Methode des Office-Objekts. Diese Methode gibt true zurück, wenn bereits ein erweitertes Objekt erstellt wurde. Andernfalls gibt sie false zurück.

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

Konfigurieren des Projekts zur Verwendung der 'GetVstoObject'-Methode und der 'HasVstoObject'-Methode

Wenn Sie nach der Installation von Visual Studio 2008 SP1 ein Projekt auf Anwendungsebene erstellen, ist das Projekt automatisch für die Verwendung der GetVstoObject-Methode und der HasVstoObject-Methode in der ThisAddIn.cs-Codedatei und der ThisAddIn.vb-Codedatei konfiguriert.

Um diese Methoden in einer von ThisAddIn.cs und ThisAddIn.vb verschiedenen Codedatei verwenden zu können, müssen Sie die folgenden Änderungen in der Codedatei vornehmen.

So ändern Sie eine Codedatei in einem Excel-Projekt zur Erstellung erweiterter Objekte

• Fügen Sie die folgenden using-Anweisungen (in C#) bzw. Imports-Anweisungen (in Visual Basic) am Anfang der Codedatei hinzu, in der Sie die GetVstoObject-Methode und die HasVstoObject-Methode verwenden möchten.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

So ändern Sie eine Codedatei in einem Word-Projekt zur Erstellung erweiterter Objekte

• Fügen Sie die folgenden using-Anweisungen (in C#) bzw. Imports-Anweisungen (in Visual Basic) am Anfang der Codedatei hinzu, in der Sie die GetVstoObject-Methode und die HasVstoObject-Methode verwenden möchten.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

Um diese Methoden in einem Projekt auf Anwendungsebene zu verwenden, das Sie vor der Installation von SP1 erstellt haben, müssen Sie folgende Änderungen an Ihrem Projekt vornehmen.

So ändern Sie ein vorhandenes Excel-Add-In zum Erstellen erweiterter Objekte

1. Fügen Sie einen Verweis auf die Microsoft.Office.Tools.Excel.v9.0.dll-Assembly hinzu.

2. Fügen Sie die folgenden using-Anweisungen (in C#) bzw. Imports-Anweisungen (in Visual Basic) am Anfang der Codedatei hinzu, in der Sie die GetVstoObject-Methode und die HasVstoObject-Methode verwenden möchten.

   Imports Microsoft.Office.Tools.Excel.Extensions
   

   using Microsoft.Office.Tools.Excel.Extensions;
   

So ändern Sie ein vorhandenes Word-Add-In zum Erstellen erweiterter Objekte

1. Fügen Sie einen Verweis auf die Microsoft.Office.Tools.Word.v9.0.dll-Assembly hinzu.

2. Fügen Sie die folgenden using-Anweisungen (in C#) bzw. Imports-Anweisungen (in Visual Basic) am Anfang der Codedatei hinzu, in der Sie die GetVstoObject-Methode und die HasVstoObject-Methode verwenden möchten.

   Imports Microsoft.Office.Tools.Word.Extensions
   

   using Microsoft.Office.Tools.Word.Extensions;
   

Diese Änderungen sind erforderlich, da die GetVstoObject-Methode und die HasVstoObject-Methode als Erweiterungsmethoden implementiert sind. Obwohl die GetVstoObject-Methode und die HasVstoObject-Methode so verwendet werden, als wären sie in Typen in den primären Interopassemblys von Excel oder Word definiert, sind sie tatsächlich in Typen im Microsoft.Office.Tools.Excel.Extensions-Namespace und dem Microsoft.Office.Tools.Word.Extensions-Namespace der Visual Studio Tools for Office-Laufzeit definiert. Weitere Informationen über Erweiterungsmethoden finden Sie unter Erweiterungsmethoden (C#-Programmierhandbuch) und Erweiterungsmethoden (Visual Basic).

Siehe auch

Aufgaben

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

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

Konzepte

Programmieren von Add-Ins auf Anwendungsebene

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

Übersicht über Hostelemente und Hoststeuerelemente

Übersicht über Smarttags

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

Änderungsprotokoll

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