Programa de suplementos VSTO

Ao estender um aplicativo do Microsoft Office por meio da criação de um Suplemento VSTO, você escreve código diretamente contra a classe ThisAddIn 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 (interface do usuário) 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 Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Alguns aspectos da codificação em projetos de suplemento VSTO são diferentes de outros tipos de projetos no Visual Studio. Muitas dessas diferenças são causadas pela forma 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 a VSTO (visão geral de desenvolvimento de soluções do Office).

Usar a classe ThisAddIn

Você pode começar a escrever o código do suplemento VSTO na classe ThisAddIn. 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 runtime das Ferramentas do Visual Studio para Office instancia essa classe automaticamente para você quando o aplicativo do Microsoft Office carrega seu complemento VSTO.

Há dois manipuladores de eventos padrão na ThisAddIn classe. Para executar o código quando o Suplemento VSTO for carregado, adicione código ao ThisAddIn_Startup manipulador de eventos. Para executar o código pouco antes do suplemento VSTO ser descarregado, adicione código ao ThisAddIn_Shutdown manipulador de eventos. Para obter mais informações sobre esses manipuladores de eventos, 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 Application campo da ThisAddIn classe. Esse campo retorna um objeto que representa a instância atual do aplicativo host. A tabela a seguir lista o tipo do valor retornado para o Application campo em cada projeto de Suplemento VSTO.

O exemplo de código a seguir mostra como usar o campo Application para criar uma nova pasta de trabalho em um suplemento VSTO para o 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);

Dim newWorkbook As Excel.Workbook = Me.Application.Workbooks.Add()

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 Globals objeto, consulte o acesso global a objetos em projetos do Office.

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

Dim newWorkbook As Excel.Workbook = Globals.ThisAddIn.Application.Workbooks.Add()

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

• Visão geral do modelo de objeto do Excel

• Visão geral do modelo de objeto do Word

• Visão geral do modelo de objeto do Outlook

• Soluções do InfoPath

• Soluções do PowerPoint

• Soluções de projeto

• Visão geral do modelo de objeto do Visio

Acessar um documento ao iniciar o aplicativo do Office

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

Private Sub ThisAddIn_Startup() Handles Me.Startup

    AddHandler Application.NewDocument, AddressOf WorkWithDocument

End Sub

Private Sub WorkWithDocument(ByVal Doc As Microsoft.Office.Interop.Word.Document) _
    Handles Application.DocumentOpen

    Dim rng As Word.Range = Doc.Range(Start:=0, End:=0)
    rng.Text = " New Text "
    rng.Select()

End Sub

Membros do ThisAddIn para uso em outras tarefas

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

Entender o design da classe ThisAddIn

Em projetos direcionados ao .NET Framework 4, AddIn é uma interface. A ThisAddIn classe deriva da AddInBase classe. Essa classe base redireciona todas as chamadas para seus membros para uma implementação interna da AddIn interface no runtime das Ferramentas do Visual Studio para Office.

Em projetos de suplemento VSTO para o Outlook, a classe ThisAddIn deriva da classe Microsoft.Office.Tools.Outlook.OutlookAddIn em projetos direcionados ao .NET Framework 3.5 e da OutlookAddInBase em projetos direcionados ao .NET Framework 4. Essas classes base fornecem algumas funcionalidades adicionais para dar 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 a 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 de 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 tenha suporte para as classes e designers, também poderá personalizar esses recursos implementando uma interface de extensibilidade em seu Suplemento VSTO. Para obter mais informações, consulte Personalizar recursos de 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 adicionar controles gerenciados a documentos e planilhas. Para mais informações, consulte Estender documentos do Word e pastas de trabalho do Excel em complementos 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 para outras soluções, incluindo outras soluções do Office. Isso será útil se o suplemento VSTO fornecer um serviço que você deseja que outras soluções possam usar. Por exemplo, se você tiver um Add-in VSTO para Microsoft Office Excel que realiza cálculos em dados financeiros de um serviço web, outras soluções podem executar esses cálculos chamando o Add-in VSTO do Excel durante o runtime.

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

Conteúdo relacionado

• Desenvolver soluções do Office
• Estender documentos do Word e pastas de trabalho do Excel em Add-ins VSTO em tempo de execução
• Código de chamada em suplementos VSTO de outras soluções do Office
• Passo a passo: invocar código em um VSTO Add-in a partir do VBA
• Personalizar recursos de interface do usuário usando interfaces de extensibilidade
• Como criar projetos do Office no Visual Studio
• Arquitetura de suplementos VSTO
• Escrever código em soluções do Office