Código de chamada no nível do aplicativo Add-ins de outras soluções do Office

Você pode expor um objeto no seu suplemento para outras soluções, incluindo outras soluções de Microsoft Office. Isso é útil se o seu suplemento fornece um serviço que você deseja ativar a outras soluções de usar. Por exemplo, se você tiver um suplemento do Excel de Microsoft Office que executa cálculos nos dados financeiros de um serviço Web, outras soluções podem executar esses cálculos chamando o suplemento do Excel em tempo de execução.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de aplicativo para Microsoft Office 2010 e o sistema 2007 do Microsoft Office. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Há duas etapas principais nesse processo:

• No seu suplemento, expõe um objeto para outras soluções.

• Outra solução, acesse o objeto exposto pelo suplemento e membros de chamada do objeto.

Tipos de soluções que podem chamar o código em um suplemento

Você pode expor um objeto em um suplemento para os seguintes tipos de soluções:

• Visual Basic for Applications o código VBA () em um documento que é carregado no mesmo processo do aplicativo como seu suplemento.

• Personalizações em nível de documento que são carregadas no mesmo processo do aplicativo como seu suplemento.

• Outros suplementos criados usando os modelos de projeto do Office em Visual Studio.

• Suplementos de COM (ou seja, add-ins que implementam o IDTExtensibility2 interface diretamente).

• Qualquer solução que está sendo executado em um processo diferente do suplemento (esses tipos de soluções também são nomeados clientes de fora do processo). Eles incluem aplicativos que automatizam a um aplicativo do Office, como, por exemplo, Windows Forms ou console application e suplementos que são carregados em um processo diferente.

Expor objetos a outras soluções

Para expor um objeto em seu suplemento a outras soluções, execute as seguintes etapas no seu suplemento:

1. Defina uma classe que você deseja expor a outras soluções.

2. Substituir o RequestComAddInAutomationService método de ThisAddIn classe. Retorne uma instância da classe que você deseja expor a outras soluções.

Definição da classe que você deseja expor a outras soluções

No mínimo, a classe que você deseja expor deve ser pública, ele deve ter o ComVisibleAttribute atributo definido como true, e ele deve expor a IDispatch interface.

A maneira recomendada para expor o IDispatch interface é executar as seguintes etapas:

1. Defina uma interface que declara os membros que você deseja expor a outras soluções. Você pode definir essa interface em seu projeto de suplemento. No entanto, convém definir esta interface em um projeto de biblioteca de classe separada se você deseja expor a classe soluções sem VBA, para que as soluções que chamam o add-in podem fazer referência a interface sem fazer referência a seu projeto de suplemento.

2. Aplicar o ComVisibleAttribute de atributo a esta interface e definir esse atributo para true.

3. Modificar sua classe para implementar essa interface.

4. Aplicar o ClassInterfaceAttribute à sua classe de atributo e definir esse atributo para o None valor de ClassInterfaceType enumeração.

5. Se você deseja expor a classe para clientes de fora do processo, você também pode precisar fazer o seguinte:

   • Derive a classe de StandardOleMarshalObject. Para obter mais informações, consulte Classes de expor aos clientes de fora do processo.

   • Definir o Register for COM interop a propriedade do projeto, onde você define a interface. Isso é necessário somente se você deseja permitir que os clientes usar ligação inicial para chamar o add-in. For more information, see Como: Registrar um componente para interoperabilidade COM.

O exemplo de código a seguir demonstra um AddInUtilities de classe com um ImportData método que pode ser chamado por outras soluções. Para ver este código no contexto de um passo a passo maior, consulte Demonstra Passo a passo: Chamar o código do VBA em um suplemento em nível de aplicativo.

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

Expondo as Classes de VBA

Quando você executa as etapas acima, o código VBA pode chamar apenas os métodos que você declara na interface do. Código do VBA não é possível chamar qualquer um dos outro métodos na sua classe, incluindo métodos de sua classe obtém a partir de classes base, como Object.

Como alternativa, você pode expor o IDispatch interface, definindo a ClassInterfaceAttribute atributo para o AutoDispatch ou AutoDual valor o ClassInterfaceType enumeração. Se você fizer isso, você precisa declarar os métodos de uma interface separada. No entanto, o código do VBA pode chamar quaisquer métodos públicos e não-static na sua classe, incluindo métodos obtidos a partir de classes base, como Object. Além disso, os clientes de fora do processo usam ligação inicial não podem chamar sua classe.

Expor Classes para clientes de fora do processo

Se você deseja expor uma classe em seu suplemento para clientes de fora do processo, você deve derivar da classe de StandardOleMarshalObject para garantir que os clientes de fora do processo podem chamar seu expostos add-in do objeto. Caso contrário, as tentativas de obter uma instância do objeto exposto em um cliente de out-of-process podem falhar inesperadamente.

Isso ocorre porque todas as chamadas para o modelo de objeto de um aplicativo do Office devem ser feitas no thread da interface do usuário principal, mas as chamadas de um cliente de fora do processo para seu objeto chegarão em um thread de (chamada de procedimento remoto) do RPC arbitrário. O COM o empacotamento de mecanismo na.NET Framework não irá alternar os threads e, em vez disso, ele tentará empacotar a chamada para o objeto no segmento RPC de entrada em vez do segmento de interface do usuário principal. Se o seu objeto é uma instância de uma classe que deriva de StandardOleMarshalObject, chamadas de entrada para o objeto automaticamente são empacotadas para o segmento onde o objeto exposto foi criado, qual será o principal segmento de interface do usuário do aplicativo host.

Para obter mais informações sobre o uso de threads em soluções do Office, consulte Threading suporte no Office.

Substituindo o método RequestComAddInAutomationService

O exemplo de código a seguir demonstra como substituir RequestComAddInAutomationService na ThisAddIn classe em seu add-in. Este exemplo pressupõe que você tenha definido uma classe chamada AddInUtilities que você deseja expor para outras soluções. Para ver este código no contexto de um passo a passo maior, consulte Demonstra Passo a passo: Chamar o código do VBA em um suplemento em nível de aplicativo.

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

Quando seu suplemento é carregado, o Visual Studio Tools for Office runtime chamadas de RequestComAddInAutomationService método. O runtime atribui o objeto retornado para o Object propriedade de um COMAddIn objeto que representa o add-in. Isso COMAddIn o objeto está disponível para outras soluções do Office e soluções que automatizam o Office.

Acesso a objetos de outras soluções

Para chamar o objeto exposto no seu suplemento, execute as seguintes etapas na solução do cliente:

1. Obter o COMAddIn objeto que representa o exposto add-in. Os clientes podem acessar todos os suplementos disponíveis, usando o Application.COMAddIns a propriedade no modelo de objeto de host do aplicativo do Office.

2. Acesso a Object propriedade da COMAddIn objeto. Essa propriedade retorna o objeto exposto do add-in.

3. Chame os membros do objeto exposto.

A maneira que você usa o valor de retorno de COMAddIn.Object propriedade é diferente para os clientes VBA e não do VBA de clientes. Para clientes de fora do processo, o código adicional é necessário para evitar uma condição de corrida possíveis.

Acessando objetos a partir de soluções do VBA

O exemplo de código a seguir demonstra como usar o VBA para chamar um método que é exposto por um suplemento. Esta macro VBA chama um método chamado ImportData que é definido em um suplemento que é denominado ExcelImportData. Para ver este código no contexto de um passo a passo maior, consulte Demonstra Passo a passo: Chamar o código do VBA em um suplemento em nível de aplicativo.

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

Acesso a objetos sem VBA soluções

Em uma solução sem VBA, você deve converter o COMAddIn.Object o valor de propriedade para a interface que ele implementa, e em seguida, você pode chamar os métodos expostos no objeto de interface. O exemplo de código a seguir demonstra como chamar o ImportData método a partir de um suplemento diferente que foi criado usando as ferramentas de desenvolvedor do Office em 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();

Neste exemplo, se você tentar converter o valor da COMAddIn.Object propriedade para o AddInUtilities classe em vez de IAddInUtilities interface, o código irá lançar um InvalidCastException.

Consulte também

Tarefas

Demonstra Passo a passo: Chamar o código do VBA em um suplemento em nível de aplicativo

Como: Criar projetos do Office em Visual Studio

Conceitos

Personalizando os recursos de interface do usuário usando Interfaces de extensibilidade

Arquitetura dos suplementos de nível de aplicativo

Outros recursos

Os suplementos de nível de aplicativo de programação.

Desenvolvimento de soluções do Office

Histórico de alterações