Appel de code dans des personnalisations au niveau du document à partir de VBA

Article
04/28/2010

Mise à jour : novembre 2007

S'applique à
Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés. Type de projet Projets au niveau du document Version de Microsoft Office Version 2007 de Microsoft Office System Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés.

Type de projet

Projets au niveau du document

Version de Microsoft Office

Version 2007 de Microsoft Office System

Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

Vous pouvez configurer un projet au niveau du document pour Word 2007 ou Excel 2007 de manière à ce que le code VBA (Visual Basic pour Applications) du document puisse appeler le code de l'assembly de personnalisation. Cela s'avère utile dans les scénarios suivant :

Vous souhaitez étendre le code VBA existant d'un document en utilisant les fonctionnalités d'une solution Visual Studio Tools pour Office associée au même document.
Vous souhaitez rendre des services que vous développez à l'aide de Visual Studio Tools pour Office accessibles aux utilisateurs finaux. Ceux-ci pourront alors accéder aux services en écrivant le code VBA dans le document.

Visual Studio Tools pour Office propose également une fonctionnalité similaire pour les compléments au niveau de l'application. Si vous êtes en train de développer un complément, vous pouvez y appeler le code à partir d'autres solutions Microsoft Office. Pour plus d'informations, consultez Appel de code dans des compléments d'application à partir d'autres solutions Office.

Remarque :
Cette fonctionnalité ne peut pas être utilisée dans des projets de modèle Word. Elle ne peut l'être que dans des projets de document Word, de classeur Excel ou de modèle Excel.

Configuration requise

Pour que vous puissiez activer le code VBA à appeler dans l'assembly de personnalisation, votre projet doit remplir les conditions suivantes :

Le document doit avoir l'une des extensions de nom de fichier suivantes :
- Pour Word : .docm ou .doc
- Pour Excel : .xlsm, .xltm, .xls ou .xlt
Le document doit déjà contenir un projet VBA intégrant un code VBA.
Le code VBA du document doit pouvoir s'exécuter sans demander à l'utilisateur d'activer des macros. Vous pouvez approuver l'exécution du code VBA en ajoutant l'emplacement du projet Visual Studio Tools pour Office à la liste des emplacements de confiance dans les paramètres du Centre de gestion de la confidentialité de Word ou Excel.
Le projet Visual Studio Tools pour Office doit contenir au moins une classe publique contenant un ou plusieurs membres publics que vous exposez à VBA.

Vous pouvez exposer des méthodes, des propriétés et des événements à VBA. La classe exposée peut être une classe d'élément hôte (telle que ThisDocument pour Word ou ThisWorkbook et Sheet1 pour Excel) ou une autre classe définie dans votre projet. Pour plus d'informations sur les éléments hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.

Activation du code VBA à appeler dans l'assembly de personnalisation

Il existe deux façons différentes d'exposer des membres d'un assembly de personnalisation au code VBA du document :

Vous pouvez exposer des membres d'une classe d'élément hôte d'un projet Visual Basic à VBA. Pour ce faire, affectez la valeur True à la propriété EnableVbaCallers. Visual Studio Tools pour Office effectue automatiquement toutes les tâches requises pour permettre au code VBA d'appeler des membres de la classe.
Vous pouvez exposer à VBA des membres d'une classe publique quelconque d'un projet Visual C# ou des membres d'une classe d'élément non hôte d'un projet Visual Basic. Cette option vous offre davantage de liberté pour choisir les classes à exposer à VBA, mais requiert également plus d'étapes manuelles.

Pour ce faire, vous devez exécuter les principales étapes suivantes :
1. Exposez la classe à COM.
2. Substituez la méthode GetAutomationObject d'une classe d'élément hôte de votre projet pour retourner une instance de la classe que vous exposez à VBA.
3. Affectez la valeur True à la propriété ReferenceAssemblyFromVbaProject d'une classe d'élément hôte quelconque du projet. Cela permet d'intégrer la bibliothèque de types de l'assembly de personnalisation à l'assembly et d'ajouter une référence à la bibliothèque de types au projet VBA du document.

Pour des instructions détaillées, consultez Comment : exposer du code à VBA dans un projet Visual Basic et Comment : exposer du code à VBA dans un projet Visual C#.

Les propriétés EnableVbaCallers et ReferenceAssemblyFromVbaProject sont uniquement disponibles dans la fenêtre Propriétés au moment du design ; elles ne peuvent pas être utilisées au moment de l'exécution. Pour afficher les propriétés, ouvrez le concepteur d'un élément hôte dans Visual Studio. Pour plus d'informations sur les tâches spécifiques exécutées par Visual Studio Tools pour Office lorsque vous définissez ces propriétés, consultez Tâches effectuées par les propriétés d'élément hôte.

Remarque :
Si le classeur ou le document ne contient pas encore de code VBA ou si l'exécution du code VBA du document n'est pas approuvée, un message d'erreur s'affiche lorsque vous affectez la valeur True à la propriété EnableVbaCallers ou ReferenceAssemblyFromVbaProject. Cela est dû au fait que Visual Studio Tools pour Office ne peut pas modifier le projet VBA du document dans ce genre de situation.

Si le classeur ou le document ne contient pas encore de code VBA ou si l'exécution du code VBA du document n'est pas approuvée, un message d'erreur s'affiche lorsque vous affectez la valeur True à la propriété EnableVbaCallers ou ReferenceAssemblyFromVbaProject. Cela est dû au fait que Visual Studio Tools pour Office ne peut pas modifier le projet VBA du document dans ce genre de situation.

Utilisation de membres du code VBA à appeler dans l'assembly de personnalisation

Après avoir configuré votre projet pour activer le code VBA à appeler dans l'assembly de personnalisation, Visual Studio Tools pour Office ajoute les membres suivants au projet VBA du document :

Pour tous les projets, Visual Studio Tools pour Office ajoute une méthode globale appelée GetManagedClass.
Pour les projets Visual Basic dans lesquels vous exposez des membres d'une classe d'élément hôte en utilisant la propriété EnableVbaCallers, Visual Studio Tools pour Office ajoute également la propriété CallVSTOAssembly au module ThisDocument, ThisWorkbook, Sheet1, Sheet2 ou Sheet3 dans le projet VBA.

Vous pouvez utiliser la propriété CallVSTOAssembly ou la méthode GetManagedClass pour accéder aux membres publics de la classe que vous avez exposée au code VBA du projet Visual Studio Tools pour Office.

Remarque :
Lors du développement et du déploiement de votre solution, vous pouvez ajouter le code VAP à plusieurs copies différentes du document. Pour plus d'informations, consultez Instructions pour l'ajout de code VBA au document.

Utilisation de la propriété CallVSTOAssembly dans un projet Visual Basic

Utilisez la propriété CallVSTOAssembly pour accéder aux membres publics que vous avez ajoutés à la classe d'élément hôte. Par exemple, la macro VBA suivante appelle une méthode appelée MyVSTOMethod et définie dans la classe Sheet1 d'un projet de classeur Excel.

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

Cette propriété permet d'appeler directement l'assembly de personnalisation de manière plus pratique qu'avec la méthode GetManagedClass. CallVSTOAssembly retourne un objet qui représente la classe d'élément hôte exposée à VBA. Les membres et paramètres de méthode de l'objet retourné apparaissent dans IntelliSense.

La propriété CallVSTOAssembly a une déclaration similaire au code suivant. Ce code part du principe que vous avez exposé la classe d'élément hôte Sheet1 d'un projet de classeur Excel appelé ExcelWorkbook1 à VBA.

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

Utilisation de la méthode GetManagedClass

Pour utiliser la méthode GetManagedClass globale, passez dans l'objet VBA qui correspond à la classe d'élément hôte qui contient votre substitution de la méthode GetAutomationObject. Utilisez ensuite l'objet retourné pour accéder à la classe que vous avez exposée à VBA.

Par exemple, la macro VBA suivante appelle une méthode nommée MyVSTOMethod définie dans la classe d'élément hôte Sheet1 d'un projet de classeur Excel appelé ExcelWorkbook1.

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

La méthode GetManagedClass contient la déclaration suivante :

GetManagedClass(pdispInteropObject Object) As Object

Cette méthode retourne un objet qui représente la classe que vous avez exposée à VBA. Les membres et paramètres de méthode de l'objet retourné apparaissent dans IntelliSense.

Instructions concernant l'ajout de code VBA au document

Vous pouvez ajouter le code VBA qui appelle la personnalisation Visual Studio Tools pour Office dans plusieurs copies différentes du document.

Lors du développement et du test de votre solution, vous pouvez écrire du code VBA dans le document qui s'ouvre lorsque vous déboguez ou exécutez votre projet dans Visual Studio (autrement dit, le document situé dans le dossier de sortie de génération). Le code VBA que vous ajoutez au document est toutefois substitué la prochaine fois que vous générez le projet, car Visual Studio remplace alors le document dans le dossier de sortie de génération par une copie issue du dossier du projet principal.

Si vous souhaitez enregistrer le code VBA que vous ajoutez au document au moment du débogage ou de l'exécution de la solution, copiez le code VBA du document dans le dossier du projet. Pour plus d'informations sur le processus de génération, consultez Vue d'ensemble du processus de génération de solutions Office.

Lorsque vous êtes prêt à déployer votre solution, vous pouvez ajouter le code VBA à trois emplacements différents du document principal.

Dans le dossier du projet sur l'ordinateur de développement

Cet emplacement est commode si vous avez le contrôle complet sur le code VBA du document et le code de la personnalisation Visual Studio Tools pour Office. Comme le document est sur l'ordinateur de développement, vous pouvez facilement modifier le code VBA facilement si vous changez le code de personnalisation. Le code VBA que vous ajoutez à cette copie du document reste dans le document lorsque vous générez, déboguez et publiez votre solution.

Vous ne pouvez pas ajouter le code VBA au document pendant que celui-ci est ouvert dans le concepteur. Vous devez d'abord fermer le document dans le concepteur, puis ouvrir directement le document dans Word ou Excel.

Attention :
Si vous ajoutez un code VBA qui s'exécute lorsque le document est ouvert, ce code risque de temps à autre d'endommager le document ou de l'empêcher de s'ouvrir dans le concepteur.

Dans le dossier de publication ou d'installation

Il peut parfois s'avérer approprié d'ajouter le code VBA au document dans le dossier de publication ou d'installation. Par exemple, vous pouvez choisir cette option si le code VBA est écrit et testé par un développeur différent sur un ordinateur sur lequel Visual Studio Tools pour Office n'est pas installé.

Si les utilisateurs installent directement la solution depuis le dossier de publication, vous devez ajouter le code VBA au document chaque fois que vous publiez la solution. Visual Studio remplace le document dans l'emplacement de publication lorsque vous publiez la solution.

Si les utilisateurs installent la solution à partir d'un dossier d'installation différent du dossier de publication, vous pouvez éviter d'ajouter le code VBA dans le document chaque fois que vous publiez la solution. Lorsqu'une mise à jour de publication est prête à être déplacée du dossier de publication vers celui d'installation, copiez tous les fichiers dans le dossier d'installation à l'exception du document.

Sur l'ordinateur de l'utilisateur final

Si l'utilisateur final est un développeur VBA qui appelle des services que vous fournissez dans la personnalisation Visual Studio Tools pour Office, vous pouvez lui expliquer comment appeler votre code à l'aide de la propriété CallVSTOAssembly ou de la méthode GetManagedClass dans ses copies du document. Lorsque vous publiez des mises à jour de la solution, le code VBA du document sur l'ordinateur de l'utilisateur final n'est pas remplacé, car le document n'est pas modifié par les mises à jour de publication.

Tâches effectuées par les propriétés d'élément hôte

Lorsque vous utilisez les propriétés EnableVbaCallers et ReferenceAssemblyFromVbaProject, Visual Studio Tools pour Office effectue différentes séries de tâches.

EnableVbaCallers

Lorsque vous affectez la valeur True à la propriété EnableVbaCallers d'un élément hôte dans un projet Visual Basic, Visual Studio Tools pour Office effectue les tâches suivantes :

Il ajoute les attributs ComClassAttribute et ComVisibleAttribute à la classe d'élément hôte.
Il substitue la méthode GetAutomationObject de la classe d'élément hôte.
Il affecte la valeur True à la propriété ReferenceAssemblyFromVbaProject de l'élément hôte.

Lorsque vous réaffectez la valeur False à la propriété EnableVbaCallers, Visual Studio Tools pour Office effectue les tâches suivantes :

Il supprime les attributs ComClassAttribute et ComVisibleAttribute de la classe ThisDocument.

Il supprime la méthode GetAutomationObject de la classe d'élément hôte.

Remarque :
Visual Studio Tools pour Office ne réaffecte pas automatiquement la valeur False à la propriété ReferenceAssemblyFromVbaProject. Vous pouvez affecter manuellement la valeur False à cette propriété à l'aide de la fenêtre Propriétés.

ReferenceAssemblyFromVbaProject

Lorsque vous affectez la valeur True à la propriété ReferenceAssemblyFromVbaProject d'un élément hôte quelconque dans un projet Visual Basic ou Visual C#, Visual Studio Tools pour Office effectue les tâches suivantes :

Il génère une bibliothèque de types pour l'assembly de personnalisation et l'incorpore dans l'assembly.
Il ajoute une référence aux bibliothèques de types suivantes du projet VBA dans le document :
- La bibliothèque de types de votre assembly de personnalisation
- La bibliothèque de types Microsoft Visual Studio Tools pour Office Execution Engine 9.0 Cette bibliothèque de types est incluse dans le runtime de Visual Studio Tools pour Office.

Lorsque vous réaffectez la valeur False à la propriété ReferenceAssemblyFromVbaProject, Visual Studio Tools pour Office effectue les tâches suivantes :

Il supprime les références de la bibliothèque de types du projet VBA dans le document.
Il supprime la bibliothèque de types incorporée de l'assembly.

Dépannage

Le tableau suivant répertorie quelques erreurs courantes et des suggestions pour les résoudre.

Erreur	Suggestion
Après avoir défini la propriété EnableVbaCallers ou ReferenceAssemblyFromVbaProject, un message d'erreur déclare que le document ne contient pas de projet VBA ou que vous n'avez pas l'autorisation d'accéder au projet VBA du document.	Vérifiez que le document dans le projet contient au moins une macro VBA, que le projet VBA a reçu un niveau de confiance suffisant pour s'exécuter et qu'il n'est pas protégé par un mot de passe.
Après avoir défini la propriété EnableVbaCallers ou ReferenceAssemblyFromVbaProject, un message d'erreur indique que la déclaration GuidAttribute est manquante ou endommagée.	Vérifiez que la déclaration GuidAttribute est localisée dans le fichier AssemblyInfo.cs ou AssemblyInfo.vb de votre projet et que cet attribut possède un GUID valide.
Après avoir défini la propriété EnableVbaCallers ou ReferenceAssemblyFromVbaProject, un message d'erreur indique que le numéro de version spécifié par AssemblyVersionAttribute n'est pas valide.	Vérifiez que la déclaration AssemblyVersionAttribute dans le fichier AssemblyInfo.cs ou AssemblyInfo.vb de votre projet est définie sur un numéro de version d'assembly valide. Pour plus d'informations sur les numéros de version d'assembly valides, consultez la classe AssemblyVersionAttribute.
Après avoir renommé l'assembly de personnalisation, le code VBA qui appelle l'assembly de personnalisation s'interrompt.	Si vous modifiez le nom de l'assembly de personnalisation après l'avoir exposé au code VBA, le lien entre le projet VBA du document et votre assembly de personnalisation est rompu. Pour résoudre ce problème, remplacez la valeur de la propriété ReferenceFromVbaAssembly dans votre projet par False, puis à nouveau par True, et remplacez ensuite toutes les références à l'ancien nom de l'assembly dans le code VBA par le nouveau nom.