Creating an Add-in Using the Add-in Wizard

---

To create the add-in, the Add-in Wizard guides you through a series of steps in which you're prompted to choose from several options. These options determine some of the features that the wizard puts in the add-in's code. First, you must select an add-in project type, which causes the Add-in Wizard to be executed. Once you've completed all of the steps in the wizard, the add-in project is automatically created and saved, and is ready for testing.

When you first open a new instance of Visual Studio .NET, you'll see the start page. You have three options here. First, you can select a project from the recent projects list, assuming that you've worked on one or more projects before. Second, you can click the Open Project button to browse for a project. Third, you can click the New Project button to create a new project.

Selecting the Project Type

To create an add-in, click the New Project button. The New Project dialog box appears, as shown in Figure 2-1. The New Project dialog box offers you a choice of languages in which you can create a project. At present, these languages are limited to Visual Basic, C#, and C++, but Microsoft has intimated that there may be many others. Under the Other Projects folder are several types of projects, including extensibility projects.

Figure 2-1: Selecting the project

Click the Extensibility Projects folder under the Other Projects folder. At this point, it might seem natural to double-click the add-in icon in the Templates window of the New Projects dialog box. Don't be tempted to do that here. If you do, the wizard will automatically give the add-in a default name and store the project files in a default directory. If you don't already know where Visual Studio stores projects by default, you'll then have to search for the project. Instead of double-clicking the add-in icon, change the name of the project from the default MyAddin1 to something more meaningful. Also, use the Browse button to select the directory in which you want the add-in files stored.

Once you've selected the name and directory, click the OK button to start the Add-in Wizard. At this point, the wizard's welcome window appears, as shown in Figure 2-2.

Figure 2-2: The Add-in Wizard's welcome window

Selecting the Add-in's Base Language

Click the Next button in the welcome window to proceed to Step 1 of the wizard (see Figure 2-3). Here, you select the Visual Studio language the code of the add-in will be generated in, and in which you will write the code. Because most of the code in this book will be in Visual Basic, select the "Create an Add-in using Visual Basic" option.

Figure 2-3: Selecting the base language

If you were to select Visual C# or C++, the code for the basic add-in Connect class would be created in that language. I encourage you to try this on your own, just to see the code generation for the different languages. This is especially helpful if you are adept at programming in multiple languages. Actually, you will do just that in Chapter 10, which covers handling multiple languages in an add-in. Now that you have selected the language for the add-in, click the Next button to proceed to Step 2.

Selecting the Application Host

Step 2 of the wizard (see Figure 2-4) contains a list of all available host applications, such as Microsoft Visual Studio .NET, that can host the add-in. To select or clear a host, click its check box. You can select more than one host if more than one is listed. Changing the host changes how the deployment project's resulting .msi file registers the add-in.

Figure 2-4: Selecting a host application

For this add-in, check the Microsoft Visual Studio .NET option and deselect any other hosting options. This will allow the add-in to be used only in the Visual Studio .NET IDE. Click the Next button to proceed to Step 3 of the wizard, where you will enter the name and description of your add-in.

Entering a Name and Description

You may think you already entered a name for your add-in in the New Projects dialog box shown in Figure 2-1. You're right—but that was the internal name for the add-in. The name you enter in Step 3 is different. This name, often referred to as the friendly name in the Visual Studio .NET documentation, is the name by which the user will know the add-in.

Step 3 allows you to enter a friendly name and description for your new add-in. This name appears in the Add-in Manager dialog box's Available Add-ins list and gives the user a short description of what the add-in does.

Two questions are asked in this step's dialog box, as shown in Figure 2-5. Give thought to what you enter into the two text boxes, as the text you input will appear from now on in the Add-in Manager dialog box.

1. What is the name of your Add-in? Enter the name that you want the add-in to display in the Add-in Manager dialog box's Available Add-ins list. This is generally referred to as the friendly name of the add-in. This is also the external name by which the add-in will be known.

2. What is the description for your Add-in? This brief description appears next to the Name box in the Description box of the Add-in Manager dialog box. If you make this description longer than the space provided, it probably won't display in its entirety in the Description box.

Figure 2-5: The Enter a Name and Description dialog box

Click the Next button to proceed to the next step, where you will be prompted to customize your add-in.

Choosing Add-in Options

Step 4 of the Add-in Wizard (see Figure 2-6) presents you with several options for customizing the add-in. Here, you can elect to have the wizard create a user interface (UI) for you. Please note that this will be a very simple, one-menu-item user interface. However, the code will demonstrate how to add a menu to the IDE for your add-ins. Also, you will be able to select when the add-in loads and who is able to use the add-in.

Figure 2-6: Customizing the add-in

Creating a User Interface

Selecting the "Would you like to create UI for the user to interact with your Add-in?" option causes the wizard to create a toolbar button and accompanying menu item automatically. The way in which you modify the Connect class generated by the wizard determines the way that the button or menu item reacts.

If your add-in is loaded, when the button is clicked it will perform the action specified by the code in the Click event handler. If your add-in is not set up to load when the IDE loads, and you do not remove the toolbar button in your disconnect code, then clicking the toolbar button will launch your add-in and transfer control to the Click event handler.

If you do not select this option, you will have to create the code manually to place the UI buttons and/or menu items on the appropriate toolbar. This is probably what you will do as you develop more complex add-ins. For now, let the wizard create the button for you. Please note that although the wizard will create a Click event handler for the button, it will not place any code in the handler to give a visible response that you have clicked the button. I discuss how to do that later in this chapter, once the Connect class has been generated.

Determining When the Add-in Loads

Step 4 also allows you to fine-tune when your add-in loads; this prompt indicates that you tell the wizard about the operation of your add-in. The "You can fine tune when your Add-in loads" option prompts you to select one of two options. These options describe how you plan for your add-in to behave with respect to displaying modal UI and add-in start-up.

Selecting the first check box specifies that your add-in will never display a modal dialog box. For most complex add-ins, this isn't practical. What this means is that your add-in can run from the command line, and it will never stop execution to prompt a user for input. In the documentation, this type of add-in is called command line safe. Generally, I don't foresee personally writing this kind of add-in. Any add-in that I've ever written has had many, many modal dialog boxes forcing interaction with the user. In my opinion, a macro, which can operate without user intervention, is better suited for a command line–safe operation. Even for your simple wizard test, you won't select this option, because you'll display a modal message box.

Selecting the second check box specifies that the add-in will be loaded when the IDE is started. You can also program your add-in to behave either way, depending on how it's loaded. When the IDE loads an add-in, it tells the add-in what the connection mode is. Your add-in could launch its UI in its OnConnection method when it's loaded normally, or it could avoid that UI when it's loaded for a command line build operation.

Setting Up Access Privileges

Selecting the "Setting up access privileges" check box specifies who can use the add-in. It can be shared with all users of the computer on which it is installed, or you can limit its use to only the person that originally installed the add-in.

---