Aufrufen von Code in Anpassungen auf Dokumentebene von VBA

Artikel
04/28/2010

Aktualisiert: November 2007

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

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

2007 Microsoft Office System

Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

Sie können ein Projekt auf Dokumentebene für Word 2007 oder Excel 2007 so konfigurieren, dass VBA (Visual Basic for Applications)-Code im Dokument Code in der Anpassungsassembly aufrufen kann. Dies ist in den folgenden Szenarien nützlich:

Sie möchten vorhandenen VBA-Code in einem Dokument mit Features in einer Visual Studio Tools for Office-Projektmappe erweitern, die demselben Dokument zugeordnet ist.
Sie möchten Dienste, die Sie mit Visual Studio Tools for Office entwickeln, für Endbenutzer verfügbar machen, die durch Schreiben von VBA-Code im Dokument auf die Dienste zugreifen können.

Visual Studio Tools for Office stellt auch ein ähnliches Feature für Add-Ins auf Anwendungsebene bereit. Wenn Sie ein Add-In entwickeln, können Sie Code im Add-In von anderen Microsoft Office-Projektmappen aufrufen. Weitere Informationen finden Sie unter Aufrufen von Code in Add-Ins auf Anwendungsebene von anderen Office-Projektmappen.

Hinweis:
Diese Funktion kann in Word-Vorlagenprojekten nicht verwendet werden. Sie kann nur in Word-Dokument-, Excel-Arbeitsmappen- oder Excel-Vorlagenprojekten verwendet werden.

Voraussetzungen

Bevor Sie VBA-Code Aufrufe in die Anpassungsassembly ermöglichen können, muss das Projekt die folgenden Voraussetzungen erfüllen:

Das Dokument muss eine der folgenden Dateinamenerweiterungen haben:
- Für Word: .docm oder .doc
- Für Excel: .xlsm, .xltm, .xls oder .xlt
Das Dokument muss bereits ein VBA-Projekt enthalten, das VBA-Code enthält.
VBA-Code im Dokument muss ausgeführt werden können, ohne dass der Benutzer Makros aktivieren muss. Sie können den auszuführenden VBA-Code als vertrauenswürdig festlegen, indem Sie den Speicherort des Visual Studio Tools for Office-Projekts zur Liste der vertrauenswürdigen Speicherorte in den Einstellungen für das Vertrauensstellungscenter für Word oder Excel hinzufügen.
Das Visual Studio Tools for Office-Projekt muss mindestens eine öffentliche Klasse enthalten, die einen oder mehrere öffentliche Member enthält, die Sie für VBA verfügbar machen.

Sie können Methoden, Eigenschaften und Ereignisse für VBA verfügbar machen. Die Klasse, die Sie verfügbar machen, kann eine Hostelementklasse (wie ThisDocument für Word oder ThisWorkbook und Sheet1 für Excel) oder eine andere Klasse sein, die Sie im Projekt definieren. Weitere Informationen zu Hostelementen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Ermöglichen von Aufrufen in die Anpassungsassembly durch VBA-Code

Es gibt zwei verschiedene Methoden, mit denen Sie Member in einer Anpassungsassembly für VBA-Code im Dokument verfügbar machen können:

Sie können Member einer Hostelementklasse in einem Visual Basic-Projekt für VBA verfügbar machen. Legen Sie dazu die EnableVbaCallers-Eigenschaft der Hostelementklasse auf True fest. Visual Studio Tools for Office führt automatisch alle Arbeitsschritte durch, die erforderlich sind, um VBA-Code den Aufruf von Membern der Klasse zu ermöglichen.
Sie können Member für VBA verfügbar machen, die sich in einer öffentlichen Klasse eines Visual C#-Projekts oder in einer nicht als Hostelementklasse fungierenden Klasse eines Visual Basic-Projekts befinden. Diese Option gibt Ihnen mehr Freiheiten bei der Auswahl der Klassen, die Sie für VBA verfügbar machen, erfordert aber auch mehr manuelle Schritte.

Dazu müssen Sie die folgenden Hauptschritte ausführen:
1. Machen Sie die Klasse für COM verfügbar.
2. Überschreiben Sie die GetAutomationObject-Methode einer Hostelementklasse im Projekt, um eine Instanz der Klasse zurückzugeben, die Sie für VBA verfügbar machen.
3. Legen Sie die ReferenceAssemblyFromVbaProject-Eigenschaft einer Hostelementklasse im Projekt auf True fest. Dadurch wird die Typbibliothek der Anpassungsassembly in die Assembly eingebettet und ein Verweis auf die Typbibliothek zum VBA-Projekt im Dokument hinzugefügt.

Ausführliche Anweisungen finden Sie unter Gewusst wie: Verfügbarmachen von Code für VBA in einem Visual Basic-Projekt und unter Gewusst wie: Verfügbarmachen von Code für VBA in einem Visual C#-Projekt.

Die EnableVbaCallers-Eigenschaft und die ReferenceAssemblyFromVbaProject-Eigenschaft sind nur zur Entwurfszeit im Eigenschaftenfenster verfügbar; sie können nicht zur Laufzeit verwendet werden. Um die Eigenschaften anzuzeigen, öffnen Sie den Designer für ein Hostelement in Visual Studio. Weitere Informationen zu den spezifischen Aufgaben, die Visual Studio Tools for Office ausführt, wenn Sie diese Eigenschaften festlegen, finden Sie unter Aufgaben, die von den Hostelementeigenschaften ausgeführt werden.

Hinweis:
Wenn die Arbeitsmappe oder das Dokument noch keinen VBA-Code enthält oder der VBA-Code im Dokument nicht vertrauenswürdig ist und deshalb nicht ausgeführt werden kann, wird beim Festlegen der EnableVbaCallers-Eigenschaft oder der ReferenceAssemblyFromVbaProject-Eigenschaft auf True eine Fehlermeldung angezeigt. Der Grund hierfür ist, dass Visual Studio Tools for Office das VBA-Projekt in diesem Fall nicht im Dokument ändern kann.

Wenn die Arbeitsmappe oder das Dokument noch keinen VBA-Code enthält oder der VBA-Code im Dokument nicht vertrauenswürdig ist und deshalb nicht ausgeführt werden kann, wird beim Festlegen der EnableVbaCallers-Eigenschaft oder der ReferenceAssemblyFromVbaProject-Eigenschaft auf True eine Fehlermeldung angezeigt. Der Grund hierfür ist, dass Visual Studio Tools for Office das VBA-Projekt in diesem Fall nicht im Dokument ändern kann.

Verwenden von Membern in VBA-Code, um in die Anpassungsassembly aufzurufen

Nachdem Sie das Projekt so konfiguriert haben, dass VBA-Code Aufrufe in die Anpassungsassembly durchführen kann, fügt Visual Studio Tools for Office dem VBA-Projekt im Dokument folgende Member hinzu:

Für alle Projekte fügt Visual Studio Tools for Office eine globale Methode mit dem Namen GetManagedClass hinzu.
Für Visual Basic-Projekte, in denen Sie Member einer Hostelementklasse mit der EnableVbaCallers-Eigenschaft verfügbar machen, fügt Visual Studio Tools for Office außerdem eine Eigenschaft mit dem Namen CallVSTOAssembly zum Modul ThisDocument, ThisWorkbook, Sheet1, Sheet2 oder Sheet3 im VBA-Projekt hinzu.

Sie können mithilfe der CallVSTOAssembly-Eigenschaft oder der GetManagedClass-Methode auf öffentliche Member der Klasse zugreifen, die Sie für VBA-Code im Visual Studio Tools for Office-Projekt verfügbar gemacht haben.

Hinweis:
Während Sie Ihre Projektmappe entwickeln und bereitstellen, gibt es mehrere unterschiedliche Kopien des Dokuments, in denen Sie den VBA-Code hinzufügen können. Weitere Informationen finden Sie in Richtlinien zum Hinzufügen von VBA-Code zum Dokument.

Verwenden der CallVSTOAssembly-Eigenschaft in einem Visual Basic-Projekt

Verwenden Sie die CallVSTOAssembly-Eigenschaft, um auf öffentliche Member zuzugreifen, die Sie der Hostelementklasse hinzugefügt haben. Das folgende VBA-Makro ruft z. B. eine Methode namens MyVSTOMethod auf, die in der Sheet1-Klasse in einem Excel-Arbeitsmappenprojekt definiert ist.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Mit dieser Eigenschaft lassen sich Aufrufe in die Anpassungsassembly auf praktischere Weise ausführen als mit der direkten Verwendung der GetManagedClass-Methode. CallVSTOAssembly gibt ein Objekt zurück, das die Hostelementklasse darstellt, die Sie für VBA verfügbar gemacht haben. Die Member und die Methodenparameter des zurückgegebenen Objekts werden in IntelliSense angezeigt.

Die CallVSTOAssembly-Eigenschaft verfügt über eine Deklaration, die dem folgenden Code ähnelt. In diesem Code wird davon ausgegangen, dass Sie die Sheet1-Hostelementklasse in einem Excel-Arbeitsmappenprojekt namens ExcelWorkbook1 für VBA bereitgestellt haben.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

Verwenden der GetManagedClass-Methode

Um die globale GetManagedClass-Methode zu verwenden, übergeben Sie das VBA-Objekt, das der Hostelementklasse entspricht, die Ihre Überschreibung der GetAutomationObject-Methode enthält. Verwenden Sie dann das zurückgegebene Objekt, um auf die Klasse zuzugreifen, die Sie für VBA verfügbar gemacht haben.

Das folgende VBA-Makro ruft z. B. eine Methode namens MyVSTOMethod auf, die in der Sheet1-Hostelementklasse in einem Excel-Arbeitsmappenprojekt mit dem Namen ExcelWorkbook1 definiert ist.

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

Die GetManagedClass-Methode weist die folgende Deklaration auf.

GetManagedClass(pdispInteropObject Object) As Object

Diese Methode gibt ein Objekt zurück, das die Klasse darstellt, die Sie für VBA verfügbar gemacht haben. Die Member und die Methodenparameter des zurückgegebenen Objekts werden in IntelliSense angezeigt.

Richtlinien für das Hinzufügen von VBA-Code zum Dokument

Es gibt mehrere unterschiedliche Kopien des Dokuments, in denen Sie den VBA-Code hinzufügen können, der Aufrufe in die Visual Studio Tools for Office-Anpassung durchführt.

Während Sie Ihre Projektmappe entwickeln und testen, können Sie VBA-Code im Dokument schreiben, das geöffnet wird, während Sie das Projekt in Visual Studio debuggen oder ausführen (d. h. das Dokument im Buildausgabeordner). VBA-Code, den Sie diesem Dokument hinzufügen, wird jedoch beim nächsten Erstellen des Projekts überschrieben, da Visual Studio das Dokument im Buildausgabeordner durch eine Kopie des Dokuments aus dem Hauptprojektordner ersetzt.

Wenn Sie den VBA-Code speichern möchten, den Sie beim Debuggen oder Ausführen der Projektmappe dem Dokument hinzufügen, kopieren Sie den VBA-Code in das Dokument im Projektordner. Weitere Informationen über den Buildprozess finden Sie unter Übersicht über das Erstellen von Office-Projektmappen.

Wenn Sie bereit sind, Ihre Projektmappe bereitzustellen, gibt es drei Hauptdokumentspeicherorte, an denen Sie den VBA-Code hinzufügen können.

Im Projektordner auf dem Entwicklungscomputer

Dieser Speicherort ist günstig, wenn Sie sowohl den VBA-Code im Dokument als auch den Visual Studio Tools for Office-Anpassungscode vollständig kontrollieren. Da das Dokument sich auf dem Entwicklungscomputer befindet, können Sie den VBA-Code auf einfache Weise ändern, wenn Sie den Anpassungscode ändern. VBA-Code, den Sie dieser Kopie des Dokuments hinzufügen, bleibt im Dokument, wenn Sie Ihre Projektmappe erstellen, debuggen und veröffentlichen.

Sie können den VBA-Code dem Dokument nicht hinzufügen, während es im Designer geöffnet ist. Sie müssen zunächst das Dokument im Designer schließen und dann das Dokument direkt in Word oder Excel öffnen.

Vorsicht:
Wenn Sie VBA-Code hinzufügen, der bei geöffnetem Dokument ausgeführt wird, könnte dieser Code in seltenen Fällen das Dokument beschädigen oder verhindern, dass es im Designer geöffnet wird.

Im Veröffentlichungs- oder Installationsordner

In manchen Fällen ist es möglicherweise angebracht, den VBA-Code dem Dokument im Veröffentlichungs- oder Installationsordner hinzuzufügen. Sie könnten diese Option z. B. auswählen, wenn der VBA-Code von einem anderen Entwickler auf einem Computer geschrieben und getestet wird, auf dem Visual Studio Tools for Office nicht installiert ist.

Wenn Benutzer die Projektmappe direkt vom Veröffentlichungsordner aus installieren, müssen Sie den VBA-Code bei jeder Veröffentlichung der Projektmappe zum Dokument hinzufügen. Visual Studio überschreibt das Dokument am Veröffentlichungsspeicherort, wenn Sie die Projektmappe veröffentlichen.

Wenn Benutzer die Projektmappe von einem anderen Installationsordner als dem Veröffentlichungsordner aus installieren, können Sie vermeiden, dass Sie den VBA-Code bei jeder Veröffentlichung der Projektmappe zum Dokument hinzufügen müssen. Wenn ein Update für die Veröffentlichung vom Veröffentlichungsordner in den Installationsordner verschoben werden kann, kopieren Sie alle Dateien mit Ausnahme des Dokuments in den Installationsordner.

Auf dem Endbenutzercomputer

Wenn die Endbenutzer VBA-Entwickler sind, die Aufrufe in Dienste ausführen, die Sie in der Visual Studio Tools for Office bereitstellen, können Sie ihnen Anweisungen für den Aufruf Ihres Codes geben. Verwenden Sie dazu die CallVSTOAssembly-Eigenschaft oder die GetManagedClass-Methode in ihren Kopien des Dokuments. Wenn Sie Updates für die Projektmappe veröffentlichen, wird VBA-Code im Dokument auf dem Endbenutzercomputer nicht überschrieben, da das Dokument von Updates für die Veröffentlichung nicht geändert wird.

Aufgaben, die von den Hostelementeigenschaften ausgeführt werden

Wenn Sie die EnableVbaCallers-Eigenschaft und die ReferenceAssemblyFromVbaProject-Eigenschaft verwenden, führt Visual Studio Tools for Office unterschiedliche Gruppen von Aufgaben aus.

EnableVbaCallers

Wenn Sie die EnableVbaCallers-Eigenschaft eines Hostelements in einem Visual Basic-Projekt auf True festgelegt haben, führt Visual Studio Tools for Office die folgenden Aufgaben aus:

Das ComClassAttribute-Attribut und das ComVisibleAttribute-Attribut werden der Hostelementklasse hinzugefügt.
Die GetAutomationObject-Methode der Hostelementklasse wird überschrieben.
Die ReferenceAssemblyFromVbaProject-Eigenschaft des Hostelements wird auf True festgelegt.

Wenn Sie die EnableVbaCallers-Eigenschaft wieder auf False festlegen, führt Visual Studio Tools for Office die folgenden Aufgaben aus:

Das ComClassAttribute-Attribut und das ComVisibleAttribute-Attribut werden aus der ThisDocument-Klasse entfernt.

Die GetAutomationObject-Methode wird aus der Hostelementklasse entfernt.

Hinweis:
Visual Studio Tools for Office legt die ReferenceAssemblyFromVbaProject-Eigenschaft nicht automatisch wieder auf False fest. Sie können diese Eigenschaft manuell auf False festlegen, indem Sie das Eigenschaftenfenster verwenden.

ReferenceAssemblyFromVbaProject

Wenn die ReferenceAssemblyFromVbaProject-Eigenschaft eines Hostelements in einem Visual Basic- oder Visual C#-Projekt auf True festgelegt ist, führt Visual Studio Tools for Office die folgenden Aufgaben aus:

Es wird eine Typbibliothek für die Anpassungsassembly generiert und in die Assembly eingebettet.
Ein Verweis auf die folgenden Typbibliotheken im VBA-Projekt wird im Dokument hinzugefügt:
- Die Typbibliothek für die Anpassungsassembly.
- Die Typbibliothek für Microsoft Visual Studio Tools for Office Execution Engine 9.0. Diese Typbibliothek ist in der Visual Studio Tools for Office-Laufzeit enthalten.

Wenn die ReferenceAssemblyFromVbaProject-Eigenschaft wieder auf False festgelegt wird, führt Visual Studio Tools for Office die folgenden Aufgaben aus:

Die Typbibliotheksverweise werden aus dem VBA-Projekt im Dokument entfernt.
Die eingebettete Typbibliothek wird aus der Assembly entfernt.

Problembehandlung

In der folgenden Tabelle werden einige häufige Fehler und Vorschläge zur Behebung der Fehler aufgelistet.

Fehler	Vorschlag
Nachdem Sie die EnableVbaCallers-Eigenschaft oder die ReferenceAssemblyFromVbaProject-Eigenschaft festgelegt haben, wird in einer Fehlermeldung angegeben, dass das Dokument kein VBA-Projekt enthält, oder Sie sind nicht berechtigt, auf das VBA-Projekt im Dokument zuzugreifen.	Stellen Sie sicher, dass das Dokument im Projekt mindestens ein VBA-Makro enthält, das VBA-Projekt für die Ausführung ausreichend vertrauenswürdig ist und es nicht durch ein Kennwort geschützt ist.
Nachdem Sie die EnableVbaCallers-Eigenschaft oder die ReferenceAssemblyFromVbaProject-Eigenschaft festgelegt haben, wird in einer Fehlermeldung angegeben, dass die GuidAttribute-Deklaration fehlt oder beschädigt ist.	Stellen Sie sicher, dass die GuidAttribute-Deklaration sich in der Datei AssemblyInfo.cs oder AssemblyInfo.vb im Projekt befindet und dass dieses Attribut auf eine gültige GUID festgelegt ist.
Nachdem Sie die EnableVbaCallers-Eigenschaft oder die ReferenceAssemblyFromVbaProject-Eigenschaft festgelegt haben, wird in einer Fehlermeldung angegeben, dass die im AssemblyVersionAttribute angegebene Versionsnummer ungültig ist.	Stellen Sie sicher, dass die AssemblyVersionAttribute-Deklaration in der Datei AssemblyInfo.cs oder AssemblyInfo.vb auf eine gültige Assemblyversionsnummer festgelegt ist. Informationen über gültige Assemblyversionsnummern finden Sie in den Ausführungen zur AssemblyVersionAttribute-Klasse.
Nachdem Sie die Anpassungsassembly umbenannt haben, funktioniert VBA-Code, der Aufrufe in die Anpassungsassembly durchführt, nicht mehr.	Wenn Sie den Namen der Anpassungsassembly ändern, nachdem Sie sie für VBA-Code verfügbar gemacht haben, ist der Link zwischen dem VBA-Projekt im Dokument und der Anpassungsassembly unterbrochen. Um dieses Problem zu beheben, ändern Sie die ReferenceFromVbaAssembly-Eigenschaft im Projekt in False und dann wieder in True, und ersetzen Sie dann alle Verweise auf den alten Assemblynamen im VBA-Code durch den neuen Assemblynamen.