Código de chamada em suplementos VSTO de outras soluções do Office

  • Artigo

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

Aplica-se a: As informações neste tópico se aplicam a projetos de suplemento VSTO. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Há duas etapas principais nesse processo:

  • No suplemento VSTO, exponha um objeto a outras soluções.

  • Em outra solução, acesse o objeto exposto pelo suplemento VSTO e chame membros do objeto.

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

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

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

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

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

  • Suplementos VSTO COM (ou seja, suplementos VSTO que implementam a IDTExtensibility2 interface diretamente).

  • Qualquer solução que esteja sendo executada em um processo diferente do seu suplemento VSTO (esses tipos de soluções também são chamados de clientes fora do processo). Isso inclui aplicativos que automatizam um aplicativo do Office, como um aplicativo do Windows Forms ou de console, e suplementos VSTO que são carregados em um processo diferente.

Expor objetos a outras soluções

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

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

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

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

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

A maneira recomendada de expor a interface IDispatch é executar as seguintes etapas:

  1. Defina uma interface que declare os membros que você deseja expor a outras soluções. Você pode definir essa interface em seu projeto de suplemento VSTO. No entanto, convém definir essa interface em um projeto de biblioteca de classes separado se desejar expor a classe a soluções não-VBA, para que as soluções que chamam seu suplemento VSTO possam fazer referência à interface sem fazer referência ao projeto de suplemento VSTO.

  2. Aplique o ComVisibleAttribute atributo a essa interface e defina esse atributo como true.

  3. Modifique sua classe para implementar essa interface.

  4. Aplique o atributo à sua classe e defina esse atributo como o ClassInterfaceAttributevalor None da ClassInterfaceType enumeração.

  5. Se você quiser expor essa classe a clientes fora do processo, talvez seja necessário fazer o seguinte:

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

    • Defina a propriedade Register for COM interop no projeto em que você define a interface. Essa propriedade é necessária somente se você quiser permitir que os clientes usem a vinculação antecipada para chamar o suplemento VSTO.

    O exemplo de código a seguir demonstra uma AddInUtilities classe com um ImportData método que pode ser chamado por outras soluções. Para ver esse código no contexto de uma explicação passo a passo maior, consulte Passo a passo: código de chamada em um suplemento VSTO do 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";
        }
    }
}

Expor classes ao VBA

Quando você executa as etapas fornecidas acima, o código VBA pode chamar somente os métodos que você declara na interface. O código VBA não pode chamar nenhum outro método em sua classe, incluindo métodos que sua classe obtém de classes base, como Object.

Como alternativa, você pode expor a interface IDispatch definindo o ClassInterfaceAttribute atributo como o valor AutoDispatch ou AutoDual da ClassInterfaceType enumeração. Se você expor a interface, não será necessário declarar os métodos em uma interface separada. No entanto, o código VBA pode chamar qualquer método público e não estático em sua classe, incluindo métodos obtidos de classes base, como Object. Além disso, os clientes fora do processo que usam vinculação antecipada não podem chamar sua classe.

Expor classes a clientes fora do processo

Se desejar expor uma classe em seu Suplemento VSTO a clientes fora do processo, você deverá derivar a classe de para garantir que os clientes fora do processo possam chamar seu objeto de StandardOleMarshalObject suplemento VSTO exposto. Caso contrário, as tentativas de obter uma instância do objeto exposto em um cliente fora do processo podem falhar inesperadamente.

Essa falha ocorre porque todas as chamadas para o modelo de objeto de um aplicativo do Office devem ser feitas no thread principal da interface do usuário, mas as chamadas de um cliente fora de processo para o objeto chegarão em um thread RPC (chamada de procedimento remoto) arbitrário. O mecanismo de empacotamento COM no .NET Framework não alternará threads e, em vez disso, tentará organizar a chamada para seu objeto no thread RPC de entrada em vez do thread de interface do usuário principal. Se o objeto for uma instância de uma classe derivada do , as chamadas de entrada para o objeto serão automaticamente empacotadas para o thread onde o objeto exposto foi criado, que será o thread principal da interface do StandardOleMarshalObjectusuário do aplicativo host.

Para obter mais informações sobre como usar threads em soluções do Office, consulte Suporte a threading no Office.

Substituir o método RequestComAddInAutomationService

O exemplo de código a seguir demonstra como substituir RequestComAddInAutomationService na ThisAddIn classe em seu suplemento VSTO. O exemplo pressupõe que você definiu uma classe chamada AddInUtilities que deseja expor a outras soluções. Para ver esse código no contexto de uma explicação passo a passo maior, consulte Passo a passo: código de chamada em um suplemento VSTO do VBA.

private AddInUtilities utilities;

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

    return utilities;
}

Quando o suplemento VSTO é carregado, o tempo de execução do Visual Studio Tools for Office chama o RequestComAddInAutomationService método. O tempo de execução atribui o objeto retornado à propriedade COMAddIn.Object de um COMAddIn objeto que representa seu suplemento VSTO. Esse COMAddIn objeto está disponível para outras soluções do Office e para soluções que automatizam o Office.

Acessar objetos de outras soluções

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

  1. Obtenha o objeto que representa o COMAddIn suplemento VSTO exposto. Os clientes podem acessar todos os suplementos VSTO disponíveis usando a Application.COMAddIns propriedade no modelo de objeto do aplicativo host do Office.

  2. Acesse a propriedade COMAddIn.Object do COMAddIn objeto. Essa propriedade retorna o objeto exposto do suplemento VSTO.

  3. Chame os membros do objeto exposto.

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

Acessar objetos de soluções VBA

O exemplo de código a seguir demonstra como usar VBA para chamar um método que é exposto por um suplemento VSTO. Essa macro VBA chama um método chamado ImportData que é definido em um suplemento VSTO chamado ExcelImportData. Para ver esse código no contexto de uma explicação passo a passo maior, consulte Passo a passo: código de chamada em um suplemento VSTO do VBA.

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

Acessar objetos de soluções não-VBA

Em uma solução não-VBA, você deve converter o valor da propriedade COMAddIn.Object 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 de um suplemento VSTO diferente que foi criado usando as ferramentas de desenvolvedor do Office no Visual Studio.

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 propriedade COMAddIn.Object para a AddInUtilities classe em vez da IAddInUtilities interface, o código lançará um InvalidCastExceptionarquivo .

Conteúdo relacionado