Suplemento VSTO do programa

  • Artigo

Quando você estende um aplicativo do Microsoft Office criando um suplemento VSTO, você escreve código diretamente na ThisAddIn classe em seu projeto. Você pode usar essa classe para executar tarefas como acessar o modelo de objeto do aplicativo host do Microsoft Office, personalizar a interface do usuário (UI) do aplicativo e expor objetos em seu suplemento VSTO para outras soluções do Office.

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.

Alguns aspectos de escrever código em projetos de suplemento VSTO são diferentes de outros tipos de projetos no Visual Studio. Muitas dessas diferenças são causadas pela maneira como os modelos de objeto do Office são expostos ao código gerenciado. Para obter mais informações, consulte Escrever código em soluções do Office.

Para obter informações gerais sobre suplementos VSTO e outros tipos de soluções que você pode criar usando as ferramentas de desenvolvimento do Office no Visual Studio, consulte Visão geral de desenvolvimento de soluções do Office (VSTO).

Usar a classe ThisAddIn

Você pode começar a escrever seu código de suplemento VSTO na ThisAddIn classe. O Visual Studio gera automaticamente essa classe no arquivo de código ThisAddIn.vb (no Visual Basic) ou ThisAddIn.cs (em C#) em seu projeto de suplemento VSTO. O tempo de execução do Visual Studio Tools for Office instancia automaticamente essa classe para você quando o aplicativo do Microsoft Office carrega seu suplemento VSTO.

Há dois manipuladores de eventos padrão na ThisAddIn classe. Para executar código quando o suplemento VSTO é carregado, adicione código ao manipulador de ThisAddIn_Startup eventos. Para executar o código antes do suplemento VSTO ser descarregado, adicione código ao manipulador de ThisAddIn_Shutdown eventos. Para obter mais informações sobre esses manipuladores de eventos, consulte Eventos em projetos do Office.

Observação

No Outlook, por padrão, o manipulador de eventos nem sempre é chamado quando o ThisAddIn_Shutdown suplemento VSTO é descarregado. Para obter mais informações, consulte Eventos em projetos do Office.

Acessar o modelo de objeto do aplicativo host

Para acessar o modelo de objeto do aplicativo host, use o ApplicationThisAddIn campo da classe. Esse campo retorna um objeto que representa a instância atual do aplicativo host. A tabela a seguir lista o tipo do valor de retorno para o Application campo em cada projeto de suplemento VSTO.

Aplicativo host Tipo de valor de retorno
Microsoft Office Excel Application
Microsoft Office InfoPath Application
Microsoft Office Outlook Application
Microsoft Office PowerPoint Aplicativo
Projeto do Microsoft Office Microsoft.Office.Interop.MSProject.Application
Microsoft Office Visio Microsoft.Office.Interop.Visio.Application
Microsoft Office Word Application

O exemplo de código a seguir mostra como usar o campo para criar uma nova pasta de trabalho em um suplemento VSTO para o Application Microsoft Office Excel. Este exemplo destina-se a ser executado a partir da ThisAddIn classe.

Excel.Workbook newWorkbook = this.Application.Workbooks.Add(System.Type.Missing);

Para fazer a mesma coisa de fora da ThisAddIn classe, use o Globals objeto para acessar a ThisAddIn classe. Para obter mais informações sobre o objeto, consulte Acesso global a objetos em projetos do Globals Office.

Excel.Workbook newWorkbook = Globals.ThisAddIn.Application.Workbooks.Add(System.Type.Missing);

Para obter mais informações sobre os modelos de objeto de aplicativos específicos do Microsoft Office, consulte os seguintes tópicos:

Acessar um documento quando o aplicativo do Office é iniciado

Nem todos os aplicativos do Office 2010 abrem automaticamente um documento quando você os inicia, e nenhum dos aplicativos do Office 2013 abre um documento quando você os inicia. Portanto, não adicione código no ThisAdd-In_Startup manipulador de eventos se o código exigir que um documento seja aberto. Em vez disso, adicione esse código a um evento que o aplicativo do Office gera quando um usuário cria ou abre um documento. Dessa forma, você pode garantir que um documento esteja aberto antes que seu código execute operações nele.

O exemplo de código a seguir funciona com um documento no Word somente quando o usuário cria um documento ou abre um documento existente.

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        this.Application.DocumentOpen +=
new Word.ApplicationEvents4_DocumentOpenEventHandler(WorkWithDocument);

        ((Word.ApplicationEvents4_Event)this.Application).NewDocument +=
            new Word.ApplicationEvents4_NewDocumentEventHandler(WorkWithDocument);  
    }
    
    private void WorkWithDocument(Microsoft.Office.Interop.Word.Document Doc)
    {
        try
        {
            Word.Range rng = Doc.Range(0, 0);
            rng.Text = "New Text";
            rng.Select();
        }
        catch (Exception ex)
        {
            // Handle exception if for some reason the document is not available.
        }
    }

Membros ThisAddIn para usar em outras tarefas

A tabela a ThisAddIn seguir descreve outras tarefas comuns e mostra quais membros da classe você pode usar para executar as tarefas.

Tarefa Membro a ser usado
Execute o código para inicializar o suplemento VSTO quando o suplemento VSTO é carregado. Adicione código ao ThisAddIn_Startup método. Esse é o manipulador de eventos padrão para o Startup evento. Para obter mais informações, consulte Eventos em projetos do Office.
Execute código para limpar os recursos usados pelo suplemento VSTO antes que o suplemento VSTO seja descarregado. Adicione código ao ThisAddIn_Shutdown método. Esse é o manipulador de eventos padrão para o Shutdown evento. Para obter mais informações, consulte Eventos em projetos do Office. Nota: No Outlook, por padrão, o manipulador de eventos nem sempre é chamado quando o ThisAddIn_Shutdown suplemento VSTO é descarregado. Para obter mais informações, consulte Eventos em projetos do Office.
Exibir um painel de tarefas personalizado. Use o CustomTaskPanes campo. Para obter mais informações, consulte Painéis de tarefas personalizados.
Exponha objetos em seu suplemento VSTO a outras soluções do Microsoft Office. Substitua o método RequestComAddInAutomationService. Para obter mais informações, consulte Código de chamada em suplementos VSTO de outras soluções do Office.
Personalize um recurso no Microsoft Office System implementando uma interface de extensibilidade. Substitua o RequestService método para retornar uma instância de uma classe que implementa a interface. Para obter mais informações, consulte Personalizar recursos da interface do usuário usando interfaces de extensibilidade. Nota: Para personalizar a interface do usuário da faixa de opções, você também pode substituir o CreateRibbonExtensibilityObject método.

Compreender o design da classe ThisAddIn

Em projetos que visam o .NET Framework 4, AddIn é uma interface. A classe ThisAddIn é derivada da classe AddInBase. Essa classe base redireciona todas as chamadas para seus membros para uma implementação interna da AddIn interface no Visual Studio Tools for Office runtime .

Em projetos de suplemento VSTO para Outlook, a ThisAddIn classe deriva da Microsoft.Office.Tools.Outlook.OutlookAddIn classe em projetos destinados ao .NET Framework 3.5 e de OutlookAddInBase projetos destinados ao .NET Framework 4. Essas classes base fornecem algumas funcionalidades adicionais para oferecer suporte a regiões de formulário. Para obter mais informações sobre regiões de formulário, consulte Criar regiões de formulário do Outlook.

Personalizar a interface do usuário de aplicativos do Microsoft Office

Você pode personalizar programaticamente a interface do usuário de aplicativos do Microsoft Office usando um suplemento VSTO. Por exemplo, você pode personalizar a faixa de opções, exibir um painel de tarefas personalizado ou criar uma região de formulário personalizada no Outlook. Para obter mais informações, consulte Personalização da interface do usuário do Office.

O Visual Studio fornece designers e classes que você pode usar para criar painéis de tarefas personalizados, personalizações da faixa de opções e regiões de formulário do Outlook. Esses designers e classes ajudam a simplificar o processo de personalização desses recursos. Para obter mais informações, consulte Painéis de tarefas personalizados, Designer da Faixa de Opções e Criar regiões de formulário do Outlook.

Se você quiser personalizar um desses recursos de uma maneira que não seja suportada pelas classes e designers, você também pode personalizar esses recursos implementando uma interface de extensibilidade em seu suplemento VSTO. Para obter mais informações, consulte Personalizar recursos da interface do usuário usando interfaces de extensibilidade.

Além disso, você pode modificar a interface do usuário de documentos do Word e pastas de trabalho do Excel gerando itens de host que estendem o comportamento de documentos e pastas de trabalho. Isso permite que você adicione controles gerenciados a documentos e planilhas. Para obter mais informações, consulte Estender documentos do Word e pastas de trabalho do Excel em suplementos VSTO em tempo de execução.

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

Você pode expor objetos em seu suplemento VSTO a outras soluções, incluindo outras soluções do 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.

Para obter mais informações, consulte Código de chamada em suplementos VSTO de outras soluções do Office.

Conteúdo relacionado