Add-In Essentials

See Also

All add-ins, regardless of what they do, require that you reference the items discussed in this topic. When you begin an add-in project, selecting the add-in template that comes with Visual Basic will provide a project containing code for all of the items listed in this topic. The template is described in this topic.

All add-ins you create with Visual Basic require the following:

• Root Object   The top-most, or "root" object in the extensibility model is the VBE object. The VBE object represents the Visual Basic environment. It hosts all of the extensibility objects and collections, which in turn have a number of properties, methods, and events which expose its functionality.

For More Information   See "Visual Basic Instance Variable" in this chapter for information on using the VBE object.

• lDTExtensibility Interface   An interface named IDTExtensibility is provided to give you quick access to necessary events in the extensibility model. These interface methods are meant to be contained in a class module in your add-in. To expose the interface's methods, use the Implements statement in a class module's Declaration section. The syntax is:

  Implements IDTExtensibility
  

  The IDTExtensibility interface contains four methods for handling add-in events:

  • OnConnection
    
    
  • OnDisconnection
    
    
  • OnStartupComplete
    
    
  • OnAddInsUpdate

  Although these are methods to the IDTExtensibility interface, to you as a programmer, they act exactly like events, triggering when an event occurs.

  The IDTExtensibility interface speeds up the process of creating these four essential procedures and eliminates problems with add-ins due to entry errors in the parameter list, or other procedure syntax errors.

  When you click the Objects drop down box in the code window for the class module, you'll see IDTExtensibility. When you select IDTExtensibility, the four required add-in event procedures appear in the Procedures drop down box. Simply click the name of each procedure to add it to the class module.

  Since add-ins require that all members of an interface be implemented, the class module must contain all four procedures. You can add as many other procedures to the class module that you want, but you must have those four at a minimum for your add-in to work.

  Note   One important caveat is that each of the four procedures must contain at least one line of code, such as a statement, procedure call, comment, and so on. If the procedure is empty, it will be removed by the compiler. If you don’t have any particular code you want to put in these procedures, just insert a comment.

For More Information   Add-in events are also covered in Chapter 4, "Connecting and Exposing Add-Ins" in the section "Connecting or Disconnecting Add-Ins." Other events that you'll want to handle are covered in this chapter under the section "Responding to Events."

• Visual Basic Instance Variable   Each collection and object in the extensibility model requires a variable to store and reference the current instance of Visual Basic. An instance is a dynamic identification variable for the current session of Visual Basic. Since you can conceivably have more than one session of the Visual Basic IDE running at any given time, the instance variable differentiates one Visual Basic session from another.

  To declare a Visual Basic instance variable in the declarations section of a module or class module, you might enter:

  ' The variable VBInst is set to the current instance ' of Visual Basic.
  Global gVBInst As VBIDE.VBE
  

For More Information   "Creating a Basic Add-In," in Chapter 1, "Add-Ins Overview," steps you through creating a simple add-in and provides a brief illustration of the items presented here at work together.

Add-In Template

Visual Basic's add-in template contains the basic, necessary code that all add-ins require. To use the add-in template to create a new add-in project, choose Add-In in the New Project dialog box. This template contains the essentials:

• A basic module which declares global variables, such as a Visual Basic instance variable.
  
  
• A class module with pre-created IDTExtensibility interface procedures
  
  
• An Add-In designer.

The template also includes these other useful features:

• A CommandBar event handler
  
  
• Rudimentary error-handling code
  
  
• Code to access the add-in as a button on the Standard toolbar

The add-in template is a great starting point for your add-in projects.