Combinaison de VBA et de personnalisations au niveau du document

Vous pouvez utiliser du code Visual Basic for Applications (VBA) dans un document faisant partie d'une personnalisation au niveau du document pour Microsoft Office Word ou Microsoft Office Excel.Vous pouvez appeler du code VBA dans le document de l'assembly de personnalisation ou configurer votre projet pour permettre au code VBA du document d'appeler le code de l'assembly de personnalisation.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document pour les applications suivantes : Excel 2013, Excel 2010, Word 2013 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Comportement de code VBA dans une personnalisation au niveau du document

Lorsque vous ouvrez votre projet dans Visual Studio, le document s'ouvre en mode Design.Le code VBA ne s'exécute pas lorsque le document est en mode Design, afin que vous puissiez travailler sur le document et coder sans exécuter le code VBA.

Lorsque vous exécutez la solution, les gestionnaires d'événements du VBA et de l'assembly de personnalisation prennent des événements déclenchés dans le document et les deux ensembles d'exécution de code.Il est impossible de savoir à l'avance quel code s'exécutera avant l'autre ; vous devez le déterminer de manière empirique dans chaque cas.Vous pouvez obtenir des résultats inattendus si les deux jeux de codes ne sont pas coordonnés et testés avec soin.

Appel du code VBA à partir de l'assembly de personnalisation

Vous pouvez appeler des macros dans les documents Word, ainsi que des macros et des fonctions dans les classeurs Excel.Pour ce faire, utilisez l'une des méthodes suivantes :

• Pour Word, appelez la méthode Run de la classe Microsoft.Office.Interop.Word.Application.

• Pour Excel, appelez la méthode Run de la classe Microsoft.Office.Interop.Excel.Application.

Pour chaque méthode, le premier paramètre identifie le nom de la macro ou de la fonction que vous souhaitez appeler, et les paramètres optionnels restants spécifient les paramètres à passer à la macro ou à la fonction.Le premier paramètre peut avoir des formats différents pour Word et Excel :

• Pour Word, le premier paramètre est une chaîne qui peut être toute combinaison de nom de modèle, de module et de macro.Si vous spécifiez le nom de document, votre code peut exécuter uniquement des macros dans les documents en rapport avec le contexte actuel — et non pas dans toute macro de tout document.

• Pour Excel, le premier paramètre peut être une chaîne qui spécifie le nom de macro, un Range qui indique où se trouve la fonction, ou un ID de registre pour une fonction DLL (XLL) enregistrée.Si vous passez une chaîne, la chaîne sera évaluée dans le contexte de la feuille active.

L'exemple de code suivant montre comment appeler une macro nommée MyMacro à partir d'un projet au niveau du document pour Excel.Cet exemple suppose que MyMacro est défini dans Sheet1.

Globals.Sheet1.Application.Run("MyMacro")

Globals.Sheet1.Application.Run("MyMacro", missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing, 
    missing, missing, missing, missing, missing, missing);

[!REMARQUE]

Pour plus d'informations sur l'utilisation de la variable globale missing à la place de paramètres optionnels dans Visual C#, consultez Écriture de code dans les solutions Office.

Le code appelant dans les personnalisations au niveau de le document depuis VBA

Vous pouvez configurer un projet au niveau du document pour Word 2007 ou Excel de manière à ce que le code VBA 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 dans un document à l'aide des fonctionnalités d'une personnalisation au niveau du document associée au même document.

• Vous souhaitez rendre disponibles des services développés dans une personnalisation au niveau du document pour les utilisateurs finaux qui peuvent accéder aux services en écrivant du code VBA dans le document.

Les outils de développement Office dans Visual Studio fournissent une fonctionnalité semblable pour les compléments d'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 le code VBA à exécuter en ajoutant l'emplacement du projet Office à la liste des emplacements approuvés dans les paramètres du Centre de gestion de la confidentialité pour Word ou Excel.

• Le projet Office doit contenir au moins une classe publique contenant un ou plusieurs membres publics que vous exposez au code 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 cela, affectez à la propriété EnableVbaCallers de l'élément hôte la valeur True dans la fenêtre Propriétés pendant que l'élément hôte (autrement dit, le document, la feuille de calcul ou le classeur) est ouvert dans le concepteur.Visual Studio exécute automatiquement tout le travail requis 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 que Visual Studio effectue lorsque vous définissez ces propriétés, consultez la section 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 ne peut pas modifier le projet VBA dans le document dans ce type de situation.

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

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

• Pour tous les projets, Visual Studio ajoute une méthode globale nommée GetManagedClass.

• Pour les projets Visual Basic dans lesquels vous exposez les membres d'une classe d'élément hôte à l'aide de la propriété EnableVbaCallers, Visual Studio ajoute également une propriété nommée 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.

[!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é est plus pratique pour appeler directement l'assembly de personnalisation que l'utilisation directe de la méthode GetManagedClass.CallVSTOAssembly retourne un objet qui représente la classe d'élément hôte que vous avez exposée au code 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

Il existe plusieurs copies du document auxquelles vous pouvez ajouter du code VBA qui appelle la personnalisation au niveau 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 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 pratique si vous avez le contrôle complet du code VBA du document et du code de la personnalisation .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.Vous pouvez, par exemple, choisir cette option si le code VBA est écrit et testé par un développeur différent sur un ordinateur sur lequel Visual Studio 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 les utilisateurs finaux sont des développeurs VBA qui appellent des services que vous fournissez dans la personnalisation au niveau du document, vous pouvez leur dire comment appeler votre code en utilisant la propriété CallVSTOAssembly ou la méthode GetManagedClass dans leurs propres 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 exécute plusieurs ensembles de tâches.

EnableVbaCallers

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

1. Il ajoute les attributs ComClassAttribute et ComVisibleAttribute à la classe d'élément hôte.

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

3. Il affecte la valeur True à la propriété ReferenceAssemblyFromVbaProject de l'élément hôte.

Lorsque vous affectez de nouveau à la propriété EnableVbaCallers la valeur False, Visual Studio effectue les tâches suivantes :

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

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

   [!REMARQUE]

   Visual Studio n'affecte pas automatiquement à la propriété ReferenceAssemblyFromVbaProject de nouveau la valeur False.Vous pouvez affecter manuellement la valeur False à cette propriété à l'aide de la fenêtre Propriétés.

ReferenceAssemblyFromVbaProject

Lorsque la propriété ReferenceAssemblyFromVbaProject d'un élément hôte d'un projet Visual Basic ou Visual C# a la valeur True, Visual Studio effectue les tâches suivantes :

1. Il génère une bibliothèque de types pour l'assembly de personnalisation et l'incorpore dans l'assembly.

2. 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 Visual Studio Tools pour Office Runtime.

Lorsque vous affectez de nouveau à la propriété ReferenceAssemblyFromVbaProject la valeur False, Visual Studio effectue les tâches suivantes :

1. Il supprime les références de la bibliothèque de types du projet VBA dans le document.

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

Voir aussi

Tâches

Comment : exposer du code à VBA dans un projet Visual Basic

Comment : exposer du code à VBA dans un projet Visual C#

Procédure pas à pas : appel de code à partir de VBA dans un projet Visual Basic

Procédure pas à pas : appel de code à partir de VBA dans un projet Visual C#

Concepts

Comparaison des solutions VBA et Office dans Visual Studio

Autres ressources

Conception et création de solutions Office

Programmation de personnalisations au niveau du document