Example of VSTO add-in / plugin for Office Word,
Excel, PowerPoint, Visio and InfoPath in C#, VB.NET

Add-in Express Home > Add-in Express for VSTO > Online Guide > Creating Office plugins in VSTO

Creating Office add-in in VSTO

On this page you will find an example of creating Add-ins for Microsoft Office applications (including Excel, Word, PowerPoint, Visio, or InfoPath) in VSTO 2008. You can find this sample project in the Demo Projects folder of the Add-in Express install folder. The sample demonstrates how to create the add-in for Microsoft Excel, but in the same way you can also build add-ins for Word, PowerPoint, Visio, or InfoPath.

Add-in Express provides additional components for COM Add-ins in Outlook. For more information, please see:

• Sample Outlook plug-in in VSTO with sourse code
• Sample Word add-in (VB.NET, C#) with sourse code
• How to program Outlook plug-in in VSTO step-by-step
• HowTo for Outlook plug-ins (VSTO 2005 and 2008)

Step 1. Creating the Excel Add-in project

To create a new Excel (Word, PowerPoint, Visio, or InfoPath) add-in project, close all opened solutions, choose “File | New | Project…”, then select the “Excel Add-in" item in either Visual Basic / Office / 2003 Add-ins (2007 Add-ins) or Visual C# / Office / 2003 Add-ins (2007 Add-ins) folder in the New Project dialog window, and click the OK button. This creates a solution with two projects: the add-in project (ExcelAddin1 in this VSTO example) and the setup project (ExcelAddin1Setup). Open the Add New Item dialog for the add-in project, choose the Add-in Module item, and click OK.

 
This modifies the code of ThisAddin.vb (or ThisAddin.cs) as follows:

Public Class ThisAddIn
   Private Sub ThisAddIn_Startup(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles Me.Startup
      'Add-in Express for VSTO generated code
      ADXModule1.Initialize(Me, _
         System.Type.GetType("ExcelAddIn1.ADXModule1")) 
      ' Start of VSTO generated code
      Me.Application = _
         CType(Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy.Wrap _
         (GetType(Excel.Application), Me.Application), Excel.Application)
      ' End of VSTO generated code
   End Sub 
   Private Sub ThisAddIn_Shutdown(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles Me.Shutdown
      'Add-in Express for VSTO generated code
      ADXModule1.Finalize(Me)
   End Sub
End Class 

Also, this adds the ADXModule1.vb (or ADXModule1.cs) file to the add-in project.

Step 2. Add-in Express module

The ADXModule1.vb (or ADXModule1.cs) is a COM Add-in module that is the core part of the Excel add-in project (see Add-in Express module). It is a container of the Add-in Express components which allow you to concentrate on the functionality of your Office add-in. You specify the add-in properties in the module's properties, add the Add-in Express components to the module's designer, and write the functional code of your add-in in this module. To review its source code, in the Solution Explorer window, right-click the AddinModule1.vb (or AddinModule1.cs) file and choose the View Code popup menu item. The code for ADXModule1.vb is as follows:

Imports System.Runtime.InteropServices
Imports System.ComponentModel
Imports System.Windows.Forms
Imports Excel = Microsoft.Office.Interop.Excel
Imports Office = Microsoft.Office.Core 
'Add-in Express for VSTO Module
<ComVisible(True)> _
Public Class ADXModule1
   Inherits AddinExpress.VSTO.ADXExcelAddin 
#Region " Component Designer generated code. "
   'Required by designer
   Private components As System.ComponentModel.IContainer 
   'Required by designer - do not modify
   'the following method
   Private Sub InitializeComponent() 
   End Sub
#End Region 
#Region " ADX automatic code "
   'Required by Add-in Express - do not modify
   'the methods within this region 
   Public Overrides Function GetContainer() _
      As System.ComponentModel.IContainer
      If components Is Nothing Then
         components = New System.ComponentModel.Container
      End If
      GetContainer = components
   End Function
#End Region 
   Public Sub New(ByVal Application As Object)
      MyBase.New(Application)
      'This call is required by the Component Designer
      InitializeComponent()
      'Add any initialization after the InitializeComponent() call
   End Sub 
   Public Sub New()
      MyBase.New() 
      'This call is required by the Component Designer
      InitializeComponent() 
      'Add any initialization after the InitializeComponent() call
   End Sub 
   Public ReadOnly Property ExcelApp() As Excel._Application
      Get
         Return HostApplication
      End Get
   End Property
End Class 
Partial Public Class ThisAddIn 
   Protected Overrides Function RequestService(ByVal serviceGuid As Guid) _
      As Object
      If serviceGuid = GetType(Office.IRibbonExtensibility).GUID Then
         ADXModule1.Initialize(Me, _
            System.Type.GetType("ExcelAddIn1.ADXModule1"))
         Return ADXModule1.CurrentInstance
      End If 
      Return MyBase.RequestService(serviceGuid)
   End Function
End Class 

Please, pay attention to the ExcelApp property of the module. You can use it in your code to get access to Excel objects.

Step 3. Add-in Express designer

The designer of the add-in module allows setting the add-in properties and adding components to the module. To open the designer, right-click the AddinModule.vb (or AddinModule.cs) file in Solution Explorer and choose the View Designer popup menu item. Now, in the Properties window, you set the name and description of your add-in module.

To add an Add-in Express component to the module, you use an appropriate command in the Properties window, or right-click on the designer surface and choose the same command in the context menu.

The following commands add the following components to the module:

• Add CommandBar – adds a command bar to your add-in (see Command bars)
• Add Explorer CommandBar – adds an Outlook Explorer command bar to your add-in
• Add Inspector CommandBar – adds an Outlook Inspector command bar to your add-in
• Add Built-in Control Connector – adds a component that allows intercepting the action of a built-in control of the host application(s) (see Built-in Control Connector)
• Add Keyboard Shortcut– adds a component that allows intercepting application-level keyboard shortcuts (see Keyboard shortcut)
• Add Outlook Bar Shortcut Manager – adds a component that allows adding Outlook Bar shortcuts and shortcut groups (see Outlook Bar Shortcut Manager)
• Add Outlook Forms Manager – adds a component that allows embedding custom .NET forms into Outlook windows (see Outlook Forms Manager)
• Add Ribbon Tab – adds a Ribbon tab to your add-in (see Office 2007 Ribbon components)
• Add Ribbon Quick Access Toolbar – adds a component that allows customizing the Ribbon Quick Access Toolbar in your add-in
• Add Ribbon Office Menu – adds a component that allows customizing the Ribbon Office Menu in your add-in

Step 4. Adding a new command bar

To add a command bar to your add-in, use the Add CommandBar command that adds an ADXCommandBar component to the COM Add-in Module (see Command bars).

Select the command bar component and, in the Properties window, specify the command bar name using the CommandBarName property. In addition, you select its position in the Position property.

Excel 2003 and Excel 2007

In Excel 2003, this command bar will be positioned at the top of the Excel workbook window. In Excel 2007, this command bar will be shown in the Add-ins tab if the Visible property of the command bar is set to True and if the controls of the command bar are visible. The same rule applies to all Ribbon-enabled Office applications.

Step 5. Adding a new command bar button

To add a new button to the command bar, in the Properties window, you select the Controls property of an appropriate command bar component and click the property editor button (the button in the property value field). In the CommandBar Control Collection Editor, you select the command bar control type in the Add button (see also Command bar controls).

 
Specify the button's Caption property, set the Style property (default value = adxMsoButtonCaption), and close the collection editor. To handle the Click event of the button, select the added button in the topmost combo of the Properties window and add the Click event handler: The code of the event handler follows below (it's empty as you can see):

    Private Sub AdxCommandBarButton1_Click(ByVal sender As System.Object) _
           Handles AdxCommandBarButton1.Click
    
    End Sub

Step 6. Accessing host application objects

The Add-in module provides the HostApplication property that returns the Application object (of the Object type) of the host application the add-in is currently running in. For your convenience, the Add-in Express Project wizard adds host-related properties to the Add-in module. You use these properties to access host application objects. For instance, this sample add-in includes the following properties in the Add-in module:

    Public ReadOnly Property ExcelApp() As Excel._Application
        Get
            Return HostApplication
        End Get
    End Property

This allows us to write the following code to the Click event of the button just added.

   Private Sub AdxCommandBarButton1_Click(ByVal sender As System.Object) _
      Handles AdxCommandBarButton1.Click
      MsgBox("The current cell is " + _
         Me.ExcelApp.ActiveCell.AddressLocal(False, False)) 'relative address
   End Sub

Step 7. Handling host application events

You might see that the Click event handler in the previous step fires an exception when there are no opened workbooks. To prevent this, you may disable the button when a window deactivates and enable it when a window activates. The add-in module provides all events of the host application (it's Excel in this case) so you can write the following code:

   Private Sub ADXModule1_WindowActivate(ByVal sender As Object, _
      ByVal hostObj As Object, ByVal window As Object) _
      Handles Me.WindowActivate
      Me.AdxCommandBarButton1.Enabled = True
   End Sub
   Private Sub ADXModule1_WindowDeactivate(ByVal sender As Object, _
      ByVal hostObj As Object, ByVal window As Object) _
      Handles Me.WindowDeactivate
      Me.AdxCommandBarButton1.Enabled = False
   End Sub

Step 8. Handling Excel worksheet events

In the same way, you process worksheet-level events. In the code of the event class, you add the following code to the procedure that handles the BeforeRightClick event of the Worksheet class:

   Private Sub ADXModule1_SheetBeforeRightClick(ByVal sender As Object, _
      ByVal e As AddinExpress.VSTO.ADXExcelSheetBeforeEventArgs) _
      Handles Me.SheetBeforeRightClick
      Dim R As Excel.Range = CType(e.Range, Excel.Range)
      'Cancel right-clicks for the first column only
      If R.Address(False, False).IndexOf("A") = 0 Then
         MsgBox("Context menu will not be shown!")
         e.Cancel = True
      Else
         e.Cancel = False
      End If
   End Sub

Step 9. Customizing the Office 2007 Ribbon user interface

To add a new tab to the Ribbon, you use the Add Ribbon Tab command that adds an ADXRibbonTab component to the module.

In the Properties window, run the editor for the Controls collection of the tab. In the editor, use the toolbar buttons or context menu to add or delete the Add-in Express components that form the Ribbon interface of your add-in. First, you add a Ribbon tab and change its caption to My Ribbon Tab. Then, you select the tab component, add a Ribbon group, and change its caption to My Ribbon Group. Next, you select the group, and add a button group. Finally, you select the button group and add a button. Set the button caption to My Ribbon Button. Use the ImageList and Image properties to set the icon for the button.

Click OK, and, in the Properties window, find the newly added Ribbon button. Now add the event handler to the Click event of the button. Write the following code:

    Private Sub AdxRibbonButton1_OnClick(ByVal sender As System.Object, _
        ByVal control As AddinExpress.VSTO.IRibbonControl, _
        ByVal pressed As System.Boolean) Handles AdxRibbonButton1.OnClick
        AdxCommandBarButton1_Click(Nothing)
    End Sub

Remember, the ADXRibbonTab Controls editor performs the XML-schema validation automatically, so from time to time you will run into the situation when you cannot add a control to some Ribbon level. It is a restriction of the Ribbon XML-schema. See also Office 2007 Ribbon components.

Step 10. Adding custom task panes in Office 2007

Add a UserControl to the add-in project and add some controls to the UserControl. For the UserControl to become a custom task pane, you add an item to the TaskPanes collection of the Add-in Module and set the properties of the item: Title, ControlType, and OutlookWindows (optional). More about Excel and Outlook custom task panes.

Please see the code of this sample project to learn how you can use custom task panes with Add-in Express.

Step 11. Customizing main menu and context menus

Add-in Express provides two similar components: Main Menu and Context Menu. They are available via the appropriate commands of the add-in module. The algorithm of their use is as follows: 

• Add a component to the add-in module 
• In the CommandBarName property, specify the main/context menu you want to customize 
• In the visual designer of the Controls property, add and set up controls of your choice.

Some comments are required for the steps above. We are accustomed to Office applications providing a number of context menus. But the fact is that some applications have several main menus. For instance, Excel 2003 provides both Worksheet Menu Bar and Chart Menu Bar main menu. Naturally, Excel 2007 doesn't show these main menus replacing them with the Ribbon UI. Nevertheless, the main menus are still available in the Commandbars collection of the Application object.

Quite frequently, when customizing the main menu, you need to customize an existing top-level menu item. To achieve this, add a popup control to the main menu component. Then in the Id property of the popup control, specify the ID of the corresponding top-level menu item. To find the ID, use our free Built-in Control Scanner.

The only control types available for Office main and context menus are button and popup. The screenshot below shows how to set the properties of the popup control when customizing the File menu in any Office application: To position your controls in the popup, you use the BeforeId or AfterId properties of the controls.

Step 12. Running the add-in

Choose the Build <Add-in Project Name> item in the Build menu, then restart the host application (Excel), and find your command bars, ribbon tabs, and custom task panes.

You find your add-in in the COM Add-ins dialog:

Step 13. Debugging the add-in

To debug your Office add-in, just choose the Start Debugging item in the Debug menu of Visual Studio.

Step 13. Debugging your Excel add-in

See VSTO Deployment Support in Add-in Express.

Sample Excel addin in VSTO

Back to Add-in Express for VSTO homepage