Appel de code dans des compléments d'application à partir d'autres solutions Office

Article
08/10/2011

Vous pouvez exposer un objet dans votre complément à d'autres solutions, notamment à d'autres solutions Microsoft Office. Cette fonctionnalité est utile si votre complément propose un service que vous souhaitez rendre accessible à d'autres solutions. Par exemple, si vous disposez d'un complément pour Microsoft Office Excel qui effectue des calculs sur des données financières d'un service Web, d'autres solutions peuvent effectuer ces calculs en appelant le complément Excel au moment de l'exécution.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau application pour Microsoft Office 2010 et la version 2007 de Microsoft® Office System. Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Ce processus comporte deux étapes principales :

Dans votre complément, exposez un objet à d'autres solutions.
Dans une autre solution, accédez à l'objet exposé par votre complément et appelez des membres de l'objet.

Types de solutions pouvant appeler du code dans un complément

Vous pouvez exposer un objet dans un complément aux types de solutions suivants :

Le code VBA (Visual Basic pour Applications) d'un document chargé dans le même processus d'application que votre complément.
Des personnalisations au niveau du document chargées dans le même processus d'application que votre complément.
D'autres compléments créés en utilisant les modèles de projet Office dans Visual Studio.
Des compléments COM (c'est-à-dire des compléments qui implémentent l'interface IDTExtensibility2 directement).
Toute solution qui s'exécute dans un processus différent de votre complément (ces types de solutions sont également nommés clients hors processus). Ceux-ci incluent des applications qui automatisent une application Office, telles qu'un Windows Forms ou une application console, et des compléments chargés dans un processus différent.

Exposition d'objets à d'autres solutions

Pour exposer un objet dans votre complément à d'autres solutions, exécutez les étapes suivantes dans votre complément :

Définissez une classe que vous souhaitez exposer à d'autres solutions.
Substituez la méthode RequestComAddInAutomationService de la classe ThisAddIn. Retourne une instance de la classe que vous souhaitez exposer à d'autres solutions.

Définition d'une classe que vous souhaitez exposer à d'autres solutions

Au minimum, la classe que vous voulez exposer doit être publique, son attribut ComVisibleAttribute doit avoir la valeur true et elle doit exposer l'interface IDispatch.

La méthode recommandée pour exposer l'interface IDispatch consiste à effectuer les opérations suivantes :

Définissez une interface qui déclare les membres que vous souhaitez exposer à d'autres solutions. Vous pouvez définir cette interface dans votre projet de complément. Cependant, vous pouvez souhaiter définir cette interface dans un projet de bibliothèque de classes distinct si vous voulez exposer la classe aux solutions autres que VBA, afin que les solutions qui appellent votre complément puissent référencer l'interface sans référencer votre projet de complément.
Appliquez l'attribut ComVisibleAttribute à cette interface et affectez à cet attribut la valeur true.
Modifiez votre classe pour implémenter cette interface.
Appliquez l'attribut ClassInterfaceAttribute à votre classe et affectez à cet attribut la valeur None de l'énumération ClassInterfaceType.
Si vous souhaitez exposer la classe aux clients hors processus, vous devrez peut-être effectuer les opérations suivantes :
- Dérivez la classe de StandardOleMarshalObject. Pour plus d'informations, consultez Exposition des classes aux clients hors processus.
- Définissez la propriété Inscrire pour COM interop dans le projet dans lequel vous définissez l'interface. Ceci n'est nécessaire que si vous souhaitez permettre aux clients d'utiliser la liaison anticipée pour appeler le complément. Pour plus d'informations, consultez Comment : inscrire un composant pour COM Interop.

L'exemple de code suivant montre une classe AddInUtilities avec une méthode ImportData pouvant être appelée par d'autres solutions. Pour voir ce code dans le contexte d'une procédure pas à pas plus vaste, consultez Procédure pas à pas : appel de code dans un complément d'application à partir de VBA.

<ComVisible(True)> _
Public Interface IAddInUtilities
    Sub ImportData()
End Interface

<ComVisible(True)> _
<ClassInterface(ClassInterfaceType.None)> _
Public Class AddInUtilities
    Implements IAddInUtilities

    ' This method tries to write a string to cell A1 in the active worksheet.
    Public Sub ImportData() Implements IAddInUtilities.ImportData

        Dim activeWorksheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

        If activeWorksheet IsNot Nothing Then
            Dim range1 As Excel.Range = activeWorksheet.Range("A1")
            range1.Value2 = "This is my data"
        End If
    End Sub
End Class

[ComVisible(true)]
public interface IAddInUtilities
{
    void ImportData();
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class AddInUtilities : IAddInUtilities
{
    // This method tries to write a string to cell A1 in the active worksheet.
    public void ImportData()
    {
        Excel.Worksheet activeWorksheet = Globals.ThisAddIn.Application.ActiveSheet as Excel.Worksheet;

        if (activeWorksheet != null)
        {
            Excel.Range range1 = activeWorksheet.get_Range("A1", System.Type.Missing);
            range1.Value2 = "This is my data";
        }
    }
}

Exposition des classes au code VBA

Lorsque vous exécutez les étapes ci-dessus, le code VBA peut appeler uniquement les méthodes que vous déclarez dans l'interface. Le code VBA ne peut pas appeler d'autres méthodes dans votre classe, notamment les méthodes que votre classe obtient de classes de base telles que Object.

Vous pouvez également exposer l'interface IDispatch en définissant l'attribut ClassInterfaceAttribute sur la valeur AutoDispatch ou AutoDual de l'énumération ClassInterfaceType. Dans ce cas, vous n'avez pas à déclarer les méthodes dans une interface distincte. Toutefois, le code VBA peut appeler n'importe quelle méthode publique et non statique dans votre classe, notamment les méthodes obtenues à partir de classes de base telles que Object. En outre, les clients hors processus qui utilisent la liaison anticipée ne peuvent pas appeler votre classe.

Exposition des classes aux clients hors processus

Si vous souhaitez exposer une classe de votre complément aux clients hors processus, vous devez dériver la classe StandardOleMarshalObject pour garantir que les clients hors processus puissent appeler votre objet de complément exposé. Sinon, vos tentatives d'obtention d'une instance de votre objet exposé dans un client hors processus peuvent échouer de façon inattendue.

En effet, tous les appels dans le modèle objet d'une application Office doivent être effectués sur le thread d'interface utilisateur principal, mais les appels d'un client hors processus à votre objet arriveront sur un thread de RPC (appel de procédure distante) arbitraire. Le mécanisme de marshaling COM dans .NET Framework ne basculera pas de threads ; en revanche, il essaiera de marshaler l'appel à votre objet sur le thread de RPC entrant au lieu du thread d'interface utilisateur principal. Si votre objet est une instance d'une classe dérivée de StandardOleMarshalObject, les appels entrants à votre objet sont marshalés automatiquement au thread où l'objet exposé a été créé, qui sera le thread d'interface utilisateur principal de l'application hôte.

Pour plus d'informations sur l'utilisation de threads dans les solutions Office, consultez Prise en charge des threads dans Office.

Substitution de la méthode RequestComAddInAutomationService

L'exemple de code suivant illustre comment remplacer RequestComAddInAutomationService dans la classe ThisAddIn de votre complément. Cet exemple suppose que vous avez défini une classe nommée AddInUtilities que vous souhaitez exposer à d'autres solutions. Pour voir ce code dans le contexte d'une procédure pas à pas plus vaste, consultez Procédure pas à pas : appel de code dans un complément d'application à partir de VBA.

Private utilities As AddInUtilities

Protected Overrides Function RequestComAddInAutomationService() As Object
    If utilities Is Nothing Then
        utilities = New AddInUtilities()
    End If
    Return utilities
End Function

private AddInUtilities utilities;

protected override object RequestComAddInAutomationService()
{
    if (utilities == null)
        utilities = new AddInUtilities();

    return utilities;
}

Lorsque votre complément est chargé, Visual Studio Tools pour Office Runtime appelle la méthode RequestComAddInAutomationService. Le runtime assigne à l'objet retourné la propriété Object d'un objet COMAddIn qui représente votre complément. Cet objet COMAddIn est accessible à d'autres solutions Office, et aux solutions qui automatisent Office.

Accès aux objets à partir d'autres solutions

Pour appeler l'objet exposé dans votre complément, exécutez les étapes suivantes dans la solution cliente :

Obtenez l'objet COMAddIn qui représente le complément exposé. Les clients peuvent accéder à tous les compléments disponibles à l'aide de la propriété Application.COMAddIns du modèle objet de l'application Office hôte.
Accédez à la propriété Object de l'objet COMAddIn. Cette propriété retourne l'objet exposé du complément.
Appelez les membres de l'objet exposé.

La manière dont vous utilisez la valeur de retour de la propriété COMAddIn.Object est différente pour les clients VBA et les clients non VBA. Pour les clients hors processus, du code supplémentaire est nécessaire pour éviter une éventuelle condition de concurrence.

Accès aux objets à partir de solutions VBA

L'exemple de code suivant montre comment utiliser VBA pour appeler une méthode exposée par un complément. Cette macro VBA appelle une méthode nommée ImportData définie dans un complément nommé ExcelImportData. Pour voir ce code dans le contexte d'une procédure pas à pas plus vaste, consultez Procédure pas à pas : appel de code dans un complément d'application à partir de VBA.

Sub CallVSTOMethod()
    Dim addIn As COMAddIn
    Dim automationObject As Object
    Set addIn = Application.COMAddIns("ExcelImportData")
    Set automationObject = addIn.Object
    automationObject.ImportData
End Sub

Accès aux objets à partir de solutions non VBA

Dans une solution non VBA, vous devez effectuer un cast de la valeur de propriété COMAddIn.Object en l'interface qu'il implémente, puis vous pouvez appeler les méthodes exposées sur l'objet interface. L'exemple de code suivant montre comment appeler la méthode ImportData depuis un autre complément créé à l'aide des outils de développement Office de Visual Studio.

Dim addIn As Office.COMAddIn = Globals.ThisAddIn.Application.COMAddIns.Item("ExcelImportData")
Dim utilities As ExcelImportData.IAddInUtilities = TryCast( _
    addIn.Object, ExcelImportData.IAddInUtilities)
utilities.ImportData()

object addInName = "ExcelImportData";
Office.COMAddIn addIn = Globals.ThisAddIn.Application.COMAddIns.Item(ref addInName);
ExcelImportData.IAddInUtilities utilities = (ExcelImportData.IAddInUtilities)addIn.Object;
utilities.ImportData();

Dans cet exemple, si vous essayez de convertir la valeur de la propriété COMAddIn.Object en la classe AddInUtilities plutôt que l'interface IAddInUtilities, le code lèvera une exception InvalidCastException.

Voir aussi

Historique des modifications

Date	Historique	Motif
Septembre 2010	Amélioration de l'organisation du contenu et suppression des informations redondantes.	Améliorations apportées aux informations.

Septembre 2010

Amélioration de l'organisation du contenu et suppression des informations redondantes.

Améliorations apportées aux informations.

Partager via