Llamar a código en complementos VSTO desde otras soluciones de OfficeCall code in VSTO Add-ins from other Office solutions

Puede exponer un objeto en su complemento VSTO para otras soluciones, incluidas otras soluciones de Microsoft Office.You can expose an object in your VSTO Add-in to other solutions, including other Microsoft Office solutions. Esto resulta útil si su complemento VSTO proporciona un servicio que quiera habilitar para que lo usen otras soluciones.This is useful if your VSTO Add-in provides a service that you want to enable other solutions to use. Por ejemplo, si tiene un complemento VSTO para Microsoft Office Excel que realiza cálculos sobre datos financieros desde un servicio Web, otras soluciones pueden realizar estos cálculos llamando al complemento VSTO de Excel en tiempo de ejecución.For example, if you have a VSTO Add-in for Microsoft Office Excel that performs calculations on financial data from a Web service, other solutions can perform these calculations by calling into the Excel VSTO Add-in at runtime.

Se aplica a: La información de este tema se aplica a VSTO agregar-en los proyectos.Applies to: The information in this topic applies to VSTO Add-in projects. Para obtener más información, consulte características disponibles por tipo de aplicación y el proyecto de Office.For more information, see Features available by Office application and project type.

Hay dos pasos principales en este proceso:There are two main steps in this process:

  • En el complemento VSTO, exponga un objeto a otras soluciones.In your VSTO Add-in, expose an object to other solutions.

  • En otra solución, acceda al objeto expuesto por el complemento VSTP y llame a los miembros del objeto.In another solution, access the object exposed by your VSTO Add-in, and call members of the object.

Tipos de soluciones que pueden llamar a código en un complementoTypes of solutions that can call code in an add-in

Puede exponer un objeto en un complemento de VSTO a los siguientes tipos de soluciones:You can expose an object in a VSTO Add-in to the following types of solutions:

  • Código de Visual Basic para Aplicaciones (VBA) en un documento que se carga en el mismo proceso de aplicación que el complemento VSTO.Visual Basic for Applications (VBA) code in a document that is loaded in the same application process as your VSTO Add-in.

  • Personalizaciones de nivel de documento que se cargan en el mismo proceso de aplicación que el complemento VSTO.Document-level customizations that are loaded in the same application process as your VSTO Add-in.

  • Otros complementos VSTO creados con plantillas de proyecto de Office en Visual Studio.Other VSTO Add-ins created by using the Office project templates in Visual Studio.

  • Complementos COM VSTO (es decir, complementos que implementan la interfaz IDTExtensibility2 directamente).COM VSTO Add-ins (that is, VSTO Add-ins that implement the IDTExtensibility2 interface directly).

  • Cualquier solución que se ejecute en un proceso diferente que el complemento VSTO (estos tipos de soluciones también se llaman clientes fuera de proceso).Any solution that is running in a different process than your VSTO Add-in (these types of solutions are also named out-of-process clients). Estas soluciones incluyen aplicaciones que automatizan una aplicación de Office, como Windows Forms o la aplicación de consola, y complementos VSTO que se cargan en un proceso diferente.These include applications that automate an Office application, such as a Windows Forms or console application, and VSTO Add-ins that are loaded in a different process.

Exponer objetos a otras solucionesExpose objects to other solutions

Para exponer un objeto del complemento VSTO en otras soluciones, siga estos pasos en el complemento VSTO:To expose an object in your VSTO Add-in to other solutions, perform the following steps in your VSTO Add-in:

  1. Defina una clase que quiera exponer a otras soluciones.Define a class that you want to expose to other solutions.

  2. Invalide el método RequestComAddInAutomationService en la clase ThisAddIn .Override the RequestComAddInAutomationService method in the ThisAddIn class. Devuelva una instancia de la clase que quiere exponer a otras soluciones.Return an instance of the class that you want to expose to other solutions.

Definir la clase que desea exponer a otras solucionesDefine the class you want to expose to other solutions

Como mínimo, la clase que quiera exponer tiene que ser pública, debe tener el atributo ComVisibleAttribute establecido en truey debe exponer la interfaz IDispatch .At a minimum, the class you want to expose must be public, it must have the ComVisibleAttribute attribute set to true, and it must expose the IDispatch interface.

La manera recomendada de exponer la interfaz IDispatch es realizar los siguientes pasos:The recommended way to expose the IDispatch interface is to perform the following steps:

  1. Defina una interfaz que declare los miembros que quiere exponer a otras soluciones.Define an interface that declares the members that you want to expose to other solutions. Puede definir esta interfaz en su proyecto de complemento VSTO.You can define this interface in your VSTO Add-in project. Sin embargo, puede que quiera definir esta interfaz en un proyecto de biblioteca de clase diferente, si quiere exponer la clase a soluciones que no son VBA; de ese modo, las soluciones que llaman al complemento VSTO pueden hacer referencia a la interfaz sin hacer referencia al proyecto de complemento VSTO.However, you might want to define this interface in a separate class library project if you want to expose the class to non-VBA solutions, so that the solutions that call your VSTO Add-in can reference the interface without referencing your VSTO Add-in project.

  2. Aplique el atributo ComVisibleAttribute a esta interfaz y establezca el atributo en true.Apply the ComVisibleAttribute attribute to this interface, and set this attribute to true.

  3. Modifique la clase para implementar esta interfaz.Modify your class to implement this interface.

  4. Aplicar el ClassInterfaceAttribute a la clase de atributo y establezca este atributo en el ninguno valor de la ClassInterfaceType enumeración.Apply the ClassInterfaceAttribute attribute to your class, and set this attribute to the None value of the ClassInterfaceType enumeration.

  5. Si desea exponer esta clase a clientes fuera de proceso, también es posible que deba hacer lo siguiente:If you want to expose this class to out-of-process clients, you might also need to do the following:

    • Derive la clase de StandardOleMarshalObject.Derive the class from StandardOleMarshalObject. Para obtener más información, consulte exponer clases a clientes fuera de proceso.For more information, see Expose classes to out-of-process clients.

    • Establezca la propiedad Registrar para interoperabilidad COM en el proyecto donde define la interfaz.Set the Register for COM interop property in the project where you define the interface. Esta propiedad solo es necesaria si desea permitir que los clientes usen enlace temprano para llamar al complemento VSTO.This property is necessary only if you want to enable clients to use early binding to call into the VSTO Add-in.

    El siguiente ejemplo de código muestra una clase AddInUtilities con un método ImportData al que otras soluciones pueden llamar.The following code example demonstrates an AddInUtilities class with an ImportData method that can be called by other solutions. Para ver este código en el contexto de un tutorial más amplio, consulte Tutorial: Llamar a código en un complemento de VSTO desde VBA.To see this code in the context of a larger walkthrough, see Walkthrough: Call code in a VSTO Add-in from VBA.

    [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";
            }
        }
    }
    
    <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
    

Exponer clases a VBAExpose classes to VBA

Cuando realice los pasos indicados arriba, el código VBA podrá llamar solo a los métodos que declare en la interfaz.When you perform the steps provided above, VBA code can call only the methods that you declare in the interface. El código VBA no puede llamar a ningún otro método de la clase, incluidos los métodos que la clase obtiene a partir de clases base, como Object.VBA code cannot call any other methods in your class, including methods that your class obtains from base classes such as Object.

Alternativamente, puede exponer el IDispatch interfaz estableciendo el ClassInterfaceAttribute en el valor en AutoDispatch o AutoDual del ClassInterfaceType enumeración.You can alternatively expose the IDispatch interface by setting the ClassInterfaceAttribute attribute to the AutoDispatch or AutoDual value of the ClassInterfaceType enumeration. Si expone la interfaz, no es necesario declarar los métodos en una interfaz independiente.If you expose the interface, you do not have to declare the methods in a separate interface. Sin embargo, el código VBA puede llamar a cualquier método público y no estático de su clase, incluidos los métodos obtenidos a partir de clases base tales como Object.However, VBA code can call any public and non-static methods in your class, including methods obtained from base classes such as Object. Además, los clientes fuera de proceso que usan enlace temprano no pueden llamar a su clase.In addition, out-of-process clients that use early binding cannot call your class.

Exponer clases a clientes fuera de procesoExpose classes to out-of-process clients

Si quiere exponer una clase de su complemento de VSTO a clientes fuera de proceso, debe derivar la clase de StandardOleMarshalObject para asegurarse de que los clientes fuera de proceso puedan llamar al objeto de complemento de VSTO expuesto.If you want to expose a class in your VSTO Add-in to out-of-process clients, you should derive the class from StandardOleMarshalObject to ensure that out-of-process clients can call your exposed VSTO Add-in object. De lo contrario, se podrían producir errores inesperados al intentar obtener una instancia del objeto expuesto en un cliente fuera de proceso.Otherwise, attempts to get an instance of your exposed object in an out-of-process client might fail unexpectedly.

Este error es porque todas las llamadas al modelo de objetos de una aplicación de Office deben realizarse en el subproceso de interfaz de usuario principal, pero las llamadas desde un cliente fuera de proceso al objeto llegarán en subproceso RPC (llamada a procedimiento remoto) arbitrario.This failure is because all calls into the object model of an Office application must be made on the main UI thread, but calls from an out-of-process client to your object will arrive on an arbitrary RPC (remote procedure call) thread. El mecanismo de cálculo de referencias COM en .NET Framework no cambiará los subprocesos y, en cambio, intentará calcular las referencias de la llamada al objeto en el subproceso de RPC entrante en lugar del subproceso principal de interfaz de usuario.The COM marshaling mechanism in the .NET Framework will not switch threads, and it will instead attempt to marshal the call to your object on the incoming RPC thread instead of the main UI thread. Si el objeto es una instancia de una clase que deriva de StandardOleMarshalObject, el cálculo de las referencias de las llamadas entrantes al objeto se realizará en el subproceso donde se creó el objeto expuesto, que será el subproceso principal de interfaz de usuario de la aplicación host.If your object is an instance of a class that derives from StandardOleMarshalObject, incoming calls to your object are automatically marshaled to the thread where the exposed object was created, which will be the main UI thread of the host application.

Para obtener más información sobre cómo usar subprocesos en soluciones de Office, consulte compatibilidad del subprocesamiento en Office.For more information about using threads in Office solutions, see Threading support in Office.

Invalide el método RequestComAddInAutomationServiceOverride the RequestComAddInAutomationService method

El ejemplo de código siguiente muestra cómo invalidar RequestComAddInAutomationService en la clase ThisAddIn del complemento de VSTO.The following code example demonstrates how to override RequestComAddInAutomationService in the ThisAddIn class in your VSTO Add-in. El ejemplo se supone que ha definido una clase denominada AddInUtilities que desea exponer a otras soluciones.The example assumes that you have defined a class named AddInUtilities that you want to expose to other solutions. Para ver este código en el contexto de un tutorial más amplio, consulte Tutorial: Llamar a código en un complemento de VSTO desde VBA.To see this code in the context of a larger walkthrough, see Walkthrough: Call code in a VSTO Add-in from VBA.

private AddInUtilities utilities;

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

    return utilities;
}
Private utilities As AddInUtilities

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

Una vez cargado el complemento de VSTO, Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime llama al método RequestComAddInAutomationService .When your VSTO Add-in is loaded, the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime calls the RequestComAddInAutomationService method. El tiempo de ejecución asigna el objeto devuelto a la propiedad COMAddIn.Object de un Microsoft.Office.Core.COMAddIn objeto que representa el complemento VSTO.The runtime assigns the returned object to the COMAddIn.Object property of a Microsoft.Office.Core.COMAddIn object that represents your VSTO Add-in. Este objeto Microsoft.Office.Core.COMAddIn está disponible para otras soluciones de Office y para soluciones que automatizan Office.This Microsoft.Office.Core.COMAddIn object is available to other Office solutions, and to solutions that automate Office.

Obtener acceso a objetos desde otras solucionesAccess objects from other solutions

Para llamar al objeto expuesto en el complemento de VSTO, siga estos pasos en la solución cliente:To call the exposed object in your VSTO Add-in, perform the following steps in the client solution:

  1. Obtenga el objeto Microsoft.Office.Core.COMAddIn que representa el complemento de VSTO expuesto.Get the Microsoft.Office.Core.COMAddIn object that represents the exposed VSTO Add-in. Los clientes pueden acceder a todos los complementos de VSTO disponibles usando la propiedad Application.COMAddIns del modelo de objetos de la aplicación host de Office.Clients can access all of the available VSTO Add-ins by using the Application.COMAddIns property in the object model of the host Office application.

  2. Acceso a la propiedad COMAddIn.Object de la Microsoft.Office.Core.COMAddIn objeto.Access the COMAddIn.Object property of the Microsoft.Office.Core.COMAddIn object. Esta propiedad devuelve el objeto expuesto desde el complemento de VSTO.This property returns the exposed object from the VSTO Add-in.

  3. Llame a los miembros del objeto expuesto.Call the members of the exposed object.

    La forma que utiliza el valor devuelto de la propiedad COMAddIn.Object es diferente para los clientes de VBA y que no son VBA.The way that you use the return value of the COMAddIn.Object property is different for VBA clients and non-VBA clients. En los clientes fuera de proceso, es necesario código adicional para evitar una posible condición de carrera.For out-of-process clients, additional code is necessary to avoid a possible race condition.

Obtener acceso a objetos desde soluciones VBAAccess objects from VBA solutions

En el ejemplo de código siguiente se muestra cómo usar VBA para llamar a un método que se expone mediante un complemento de VSTO.The following code example demonstrates how to use VBA to call a method that is exposed by a VSTO Add-in. Esta macro VBA llama a un método denominado ImportData que se define en un complemento de VSTO que se denomina ExcelImportData.This VBA macro calls a method named ImportData that is defined in a VSTO Add-in that is named ExcelImportData. Para ver este código en el contexto de un tutorial más amplio, consulte Tutorial: Llamar a código en un complemento de VSTO desde VBA.To see this code in the context of a larger walkthrough, see Walkthrough: Call code in a VSTO Add-in from VBA.

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

Obtener acceso a objetos desde soluciones que no son VBAAccess objects from non-VBA solutions

En una solución que no son VBA, debe convertir el valor de propiedad COMAddIn.Object a la interfaz que implementa y, a continuación, puede llamar a los métodos expuestos en el objeto de interfaz.In a non-VBA solution, you must cast the COMAddIn.Object property value to the interface it implements, and then you can call the exposed methods on the interface object. El ejemplo de código siguiente muestra cómo llamar al método ImportData desde un complemento de VSTO diferente que se creó usando las herramientas de desarrollador de Office en Visual Studio.The following code example demonstrates how to call the ImportData method from a different VSTO Add-in that was created by using the Office developer tools in 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();

En este ejemplo, si se intenta convertir el valor de la propiedad COMAddIn.Object a la AddInUtilities clase en lugar de IAddInUtilities interfaz, el código iniciará una InvalidCastException.In this example, if you try to cast the value of the COMAddIn.Object property to the AddInUtilities class rather than the IAddInUtilities interface, the code will throw an InvalidCastException.

Vea tambiénSee also