Suplementos do VSTO do programaProgram VSTO Add-ins

Quando você estende um aplicativo do Microsoft Office, criando um suplemento do VSTO, você escreve código diretamente no ThisAddIn classe em seu projeto.When you extend a Microsoft Office application by creating a VSTO Add-in, you write code directly against the ThisAddIn class in your project. Você pode usar essa classe para executar tarefas como acessar o modelo de objeto do aplicativo host do Microsoft Office, personalizando a interface do usuário (IU) do aplicativo e expor objetos no seu suplemento do VSTO para outras soluções do Office.You can use this class to perform tasks such as accessing the object model of the Microsoft Office host application, customizing the user interface (UI) of the application, and exposing objects in your VSTO Add-in to other Office solutions.

Aplica-se a: as informações neste tópico se aplicam para adicionar o VSTO-em projetos.Applies to: The information in this topic applies to VSTO Add-in projects. Para obter mais informações, consulte recursos disponíveis por tipo de projeto e aplicativo do Office.For more information, see Features available by Office application and project type.

Alguns aspectos de escrever código em projetos de suplemento do VSTO são diferentes de outros tipos de projetos no Visual Studio.Some aspects of writing code in VSTO Add-in projects are different from other types of projects in Visual Studio. Muitas dessas diferenças são causadas pela maneira como o Office modelos de objeto são expostos ao código gerenciado.Many of these differences are caused by the way the Office object models are exposed to managed code. Para obter mais informações, consulte escrever código em soluções do Office.For more information, see Write code in Office solutions.

Para obter informações gerais sobre o VSTO Add-ins 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).For general information about VSTO Add-ins and other types of solutions you can create by using the Office development tools in Visual Studio, see Office solutions development overview (VSTO).

Use a classe ThisAddInUse the ThisAddIn class

Você pode começar a escrever seu código de suplemento do VSTO no ThisAddIn classe.You can start writing your VSTO Add-in code in the ThisAddIn class. Visual Studio gera automaticamente essa classe na ThisAddIn. vb (no Visual BasicVisual Basic) ou ThisAddIn.cs (em c#) código de arquivo em seu projeto de suplemento do VSTO.Visual Studio automatically generates this class in the ThisAddIn.vb (in Visual BasicVisual Basic) or ThisAddIn.cs (in C#) code file in your VSTO Add-in project. O Visual Studio Tools para Office RuntimeVisual Studio Tools for Office runtime automaticamente cria uma instância dessa classe para você quando o aplicativo do Microsoft Office carrega o suplemento do VSTO.The Visual Studio Tools para Office RuntimeVisual Studio Tools for Office runtime automatically instantiates this class for you when the Microsoft Office application loads your VSTO Add-in.

Há dois manipuladores de eventos padrão no ThisAddIn classe.There are two default event handlers in the ThisAddIn class. Para executar código quando o suplemento do VSTO é carregado, adicione código para o ThisAddIn_Startup manipulador de eventos.To run code when the VSTO Add-in is loaded, add code to the ThisAddIn_Startup event handler. Para executar código antes que o suplemento do VSTO é descarregado, adicione código para o ThisAddIn_Shutdown manipulador de eventos.To run code just before the VSTO Add-in is unloaded, add code to the ThisAddIn_Shutdown event handler. Para obter mais informações sobre esses manipuladores de eventos, consulte eventos em projetos do Office.For more information about these event handlers, see Events in Office projects.

Note

No Outlook, por padrão o ThisAddIn_Shutdown manipulador de eventos não é sempre chamado quando o suplemento do VSTO é descarregado.In Outlook, by default the ThisAddIn_Shutdown event handler is not always called when the VSTO Add-in is unloaded. Para obter mais informações, consulte eventos em projetos do Office.For more information, see Events in Office projects.

Acessar o modelo de objeto do aplicativo hostAccess the object model of the host application

Para acessar o modelo de objeto do aplicativo host, use o Application campo do ThisAddIn classe.To access the object model of the host application, use the Application field of the ThisAddIn class. Esse campo retorna um objeto que representa a instância atual do aplicativo host.This field returns an object that represents the current instance of the host application. A tabela a seguir lista o tipo do valor de retorno para o Application campo em cada projeto de suplemento do VSTO.The following table lists the type of the return value for the Application field in each VSTO Add-in project.

Aplicativo de hostHost application Tipo de valor de retornoReturn value type
Microsoft Office ExcelMicrosoft Office Excel Application
Microsoft Office InfoPathMicrosoft Office InfoPath Microsoft.Office.Interop.InfoPath.Application
Microsoft Office OutlookMicrosoft Office Outlook Microsoft.Office.Interop.Outlook.Application
Microsoft Office PowerPointMicrosoft Office PowerPoint Microsoft.Office.Interop.PowerPoint.Application
Microsoft Office ProjectMicrosoft Office Project Microsoft.Office.Interop.MSProject.ApplicationMicrosoft.Office.Interop.MSProject.Application
Microsoft Office VisioMicrosoft Office Visio Microsoft.Office.Interop.Visio.ApplicationMicrosoft.Office.Interop.Visio.Application
Microsoft Office WordMicrosoft Office Word Application

O exemplo de código a seguir mostra como usar o Application campo para criar uma nova pasta de trabalho em um suplemento do VSTO para o Microsoft Office Excel.The following code example shows how to use the Application field to create a new workbook in a VSTO Add-in for Microsoft Office Excel. Este exemplo se destina a ser executado a partir de ThisAddIn classe.This example is intended to be run from the ThisAddIn class.

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

Para fazer a mesma coisa de fora o ThisAddIn classe, use o Globals do objeto para o acesso a ThisAddIn classe.To do the same thing from outside the ThisAddIn class, use the Globals object to access the ThisAddIn class. Para obter mais informações sobre o Globals do objeto, consulte Global de acesso a objetos em projetos do Office.For more information about the Globals object, see Global access to objects in Office projects.

Dim newWorkbook As Excel.Workbook = Globals.ThisAddIn.Application.Workbooks.Add()  
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 tópicos a seguir:For more information about the object models of specific Microsoft Office applications, see the following topics:

Acessar um documento quando inicia o aplicativo do OfficeAccess a document when the Office application starts

Nem todos os Office 2010Office 2010 aplicativos de abrem um documento automaticamente quando você inicia e nenhum do Office 2013Office 2013 aplicativos abrem um documento quando você iniciá-los.Not all Office 2010Office 2010 applications automatically open a document when you start them, and none of the Office 2013Office 2013 applications open a document when you start them. Portanto, não adicione o código no ThisAdd-In_Startup se um documento a ser aberto exige que o código de manipulador de eventos.Therefore, don't add code in the ThisAdd-In_Startup event handler if the code requires a document to be open. Em vez disso, adicione esse código para um evento que o aplicativo do Office emite quando um usuário cria ou abre um documento.Instead, add that code to an event that the Office application raises when a user creates or opens a document. Dessa forma, você pode garantir que um documento está aberto antes de seu código executa operações nela.That way, you can guarantee that a document is open before your code performs operations on it.

O exemplo de código a seguir funciona com um documento do Word, somente quando o usuário cria um documento ou abrir um documento existente.The following code example works with a document in Word only when the user creates a document or opens an existing document.

    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 ThisAddIn a ser usado para outras tarefasThisAddIn members to use for other tasks

A tabela a seguir descreve outras tarefas comuns e mostra quais membros do ThisAddIn classe você pode usar para executar as tarefas.The following table describes other common tasks and shows which members of the ThisAddIn class you can use to perform the tasks.

TarefaTask Membro a ser usadoMember to use
Execute o código para inicializar o suplemento do VSTO, quando o suplemento do VSTO é carregado.Run code to initialize the VSTO Add-in when the VSTO Add-in is loaded. Adicione código para o ThisAddIn_Startup método.Add code to the ThisAddIn_Startup method. Isso é o manipulador de eventos padrão para o Startup eventos.This is the default event handler for the Startup event. Para obter mais informações, consulte eventos em projetos do Office.For more information, see Events in Office projects.
Execute o código para limpar os recursos usados pelo suplemento do VSTO antes que o suplemento do VSTO é descarregado.Run code to clean up resources used by the VSTO Add-in before the VSTO Add-in is unloaded. Adicione código para o ThisAddIn_Shutdown método.Add code to the ThisAddIn_Shutdown method. Isso é o manipulador de eventos padrão para o Shutdown eventos.This is the default event handler for the Shutdown event. Para obter mais informações, consulte eventos em projetos do Office.For more information, see Events in Office projects. Observação: no Outlook, por padrão o ThisAddIn_Startup manipulador de eventos não é sempre chamado quando o suplemento do VSTO é descarregado.Note: In Outlook, by default the ThisAddIn_Startup event handler is not always called when the VSTO Add-in is unloaded. Para obter mais informações, consulte eventos em projetos do Office.For more information, see Events in Office projects.
Exiba um painel de tarefas personalizado.Display a custom task pane. Use o CustomTaskPanes campo.Use the CustomTaskPanes field. Para obter mais informações, consulte painéis de tarefas personalizados.For more information, see Custom task panes.
Expor objetos no seu suplemento do VSTO para outras soluções do Microsoft Office.Expose objects in your VSTO Add-in to other Microsoft Office solutions. Substituir o método RequestComAddInAutomationService.Override the RequestComAddInAutomationService method. Para obter mais informações, consulte chamar o código no VSTO Add-ins de outras soluções do Office.For more information, see Call code in VSTO Add-ins from other Office solutions.
Personalize um recurso no Microsoft Office system com a implementação de uma interface de extensibilidade.Customize a feature in the Microsoft Office system by implementing an extensibility interface. Substituir o RequestService método para retornar uma instância de uma classe que implementa a interface.Override the RequestService method to return an instance of a class that implements the interface. Para obter mais informações, consulte recursos de interface do usuário personalizar usando interfaces de extensibilidade.For more information, see Customize UI features by using extensibility interfaces. Observação: para personalizar a interface do usuário da faixa de opções, você também pode substituir o CreateRibbonExtensibilityObject método.Note: To customize the ribbon UI, you can also override the CreateRibbonExtensibilityObject method.

Entender o design da classe ThisAddInUnderstand the design of the ThisAddIn class

Em projetos que se destinam a .NET Framework 4.NET Framework 4, AddIn é uma interface.In projects that target the .NET Framework 4.NET Framework 4, AddIn is an interface. O ThisAddIn classe deriva de AddInBase classe.The ThisAddIn class derives from the AddInBase class. Essa classe base redireciona todas as chamadas para seus membros para uma implementação interna do AddIn da interface no Visual Studio Tools para Office RuntimeVisual Studio Tools for Office runtime.This base class redirects all calls to its members to an internal implementation of the AddIn interface in the Visual Studio Tools para Office RuntimeVisual Studio Tools for Office runtime.

Em projetos de suplemento do VSTO para Outlook, o ThisAddIn classe deriva a Microsoft.Office.Tools.Outlook.OutlookAddIn classe nos projetos direcionados ao .NET Framework 3.5 e de OutlookAddInBase em projetos que segmentam o .NET Framework 4.NET Framework 4.In VSTO Add-in projects for Outlook, the ThisAddIn class derives from the Microsoft.Office.Tools.Outlook.OutlookAddIn class in projects that target the .NET Framework 3.5, and from OutlookAddInBase in projects that target the .NET Framework 4.NET Framework 4. Essas classes base fornecem algumas funcionalidades adicionais para dar suporte a regiões do formulário.These base classes provide some additional functionality to support form regions. Para obter mais informações sobre regiões de formulário, consulte regiões de formulário do Outlook criar.For more information about form regions, see Create Outlook form regions.

Personalizar a interface do usuário de aplicativos do Microsoft OfficeCustomize the user interface of Microsoft Office applications

Programaticamente, você pode personalizar os aplicativos de interface do usuário do Microsoft Office usando um suplemento do VSTO.You can programmatically customize the UI of Microsoft Office applications by using a VSTO Add-in. Por exemplo, pode personalizar a faixa de opções, exibir um painel de tarefas personalizado ou criar uma região de formulário personalizada no Outlook.For example, you can customize the ribbon, display a custom task pane, or create a custom form region in Outlook. Para obter mais informações, consulte personalização da interface do usuário do Office.For more information, see Office UI customization.

Visual Studio oferece designers e as 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.Visual Studio provides designers and classes that you can use to create custom task panes, ribbon customizations, and Outlook form regions. Essas classes e os designers de ajudam a simplificar o processo de personalização desses recursos.These designers and classes help to simplify the process of customizing these features. Para obter mais informações, consulte painéis de tarefas personalizados, Designer de faixa de opções, e regiões de formulário do Outlook criar.For more information, see Custom task panes, Ribbon Designer, and Create Outlook form regions.

Se você desejar personalizar um desses recursos de forma que não é compatível com as classes e os designers, você também pode personalizar esses recursos implementando uma interface de extensibilidade no seu suplemento do VSTO.If you want to customize one of these features in a way that is not supported by the classes and designers, you can also customize these features by implementing an extensibility interface in your VSTO Add-in. Para obter mais informações, consulte recursos de interface do usuário personalizar usando interfaces de extensibilidade.For more information, see Customize UI features by using extensibility interfaces.

Além disso, você pode modificar da interface do usuário de documentos do Word e pastas de trabalho do Excel por gerar itens de host que estendem o comportamento de documentos e pastas de trabalho.In addition, you can modify the UI of Word documents and Excel workbooks by generating host items that extend the behavior of documents and workbooks. Isso permite que você adicione controles gerenciados a documentos e planilhas.This enables you to add managed controls to documents and worksheets. Para obter mais informações, consulte documentos de estender o Word e pastas de trabalho do Excel em suplementos do VSTO em tempo de execução.For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Chamar o código no VSTO Add-ins de outras soluçõesCall code in VSTO Add-ins from other solutions

Você pode expor os objetos no seu suplemento do VSTO para outras soluções, incluindo outras soluções do Office.You can expose objects in your VSTO Add-in to other solutions, including other Office solutions. Isso é útil se o suplemento do VSTO fornece um serviço que você deseja habilitar usar outras soluções.This is useful if your VSTO Add-in provides a service that you want to enable other solutions to use. Por exemplo, se você tiver um suplemento do VSTO para o Microsoft Office Excel que executa cálculos nos dados financeiros de um serviço web, outras soluções podem executar esses cálculos chamando o suplemento do VSTO do Excel em tempo de execução.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 run time.

Para obter mais informações, consulte chamar o código no VSTO Add-ins de outras soluções do Office.For more information, see Call code in VSTO Add-ins from other Office solutions.

Consulte tambémSee also

Desenvolver soluções do Office Develop Office solutions
Estender documentos do Word e pastas de trabalho do Excel em suplementos do VSTO em tempo de execução Extend Word documents and Excel workbooks in VSTO Add-ins at runtime
Chamar o código no VSTO Add-ins de outras soluções do Office Call code in VSTO Add-ins from other Office solutions
Passo a passo: Chamar o código em um suplemento do VSTO do VBA Walkthrough: Call code in a VSTO Add-in from VBA
Personalizar os recursos de interface do usuário usando interfaces de extensibilidade Customize UI features By using extensibility interfaces
Como: criar projetos do Office no Visual Studio How to: Create Office projects in Visual Studio
Arquitetura de suplementos do VSTO Architecture of VSTO Add-ins
Escrever código em soluções do OfficeWrite code in Office solutions