Debugging Your COM Add-In

When errors occur or your add-in doesn't work as expected, you need to debug your code. To debug a COM add-in for Office in Visual Basic version 6.0, you simply place breakpoints in your code, put your Visual Basic project in run mode, and start the appropriate Office application.

Using the COM Add-Ins Dialog Box

Visual Basic lets you set breakpoints and go through your code line-by-line to detect and correct errors. To debug your code using the COM Add-Ins dialog box, complete the steps below.

  1. In the Project Explorer, select the ConnectWord project and click the View Code button. Place the cursor in the line containing Private Sub AddinInstance_OnConnection and press F9 to add a breakpoint. Then press F5 or click Start on the Run menu to run your project. Click OK on the project Properties dialog box when it is displayed.

  2. Restart Word. Click COM Add-Ins to display the COM Add-Ins dialog box. Select the Microsoft Office Basic COM Add-In for Word check box, and then click OK.

NOTE
To learn how to find the COM Add-Ins command, see steps 2 and 3 in the section, "Test the COM Add-In."

    Office loads the BasicCOMAddIn add-in into Word and calls the OnConnection procedure. Note that the add-in is actually running in the background in Visual Basic rather than as a compiled .dll on your computer. The breakpoint that you put in the OnConnection procedure stops code execution at the first line. The line is highlighted in yellow, indicating that your project is in break mode.

NOTE
If nothing happens when you attempt to debug your add-in project, make sure you placed your project in run mode after you checked the add-in in the COM Add-Ins dialog box.

  1. Press F8 to step into the OnConnection procedure and debug your add-in.

NOTE
Adding breakpoints and stepping through each line of code to find errors is discussed in chapter 2, in the section, "Debugging Your Code." While debugging a COM add-in, the Visual Basic project is in break mode and Word is suspended (that is, the window appears "frozen"). To continue working in Word, you must take your project out of break mode, either by pressing F5 to put your Visual Basic project back in run mode or by stopping the Visual Basic project by clicking End from the Run menu.

  1. Press F5 to put your project back in run mode. The message box with the text "Add-in connected to: Microsoft Word" appears. Click OK to close the message box.

IMPORTANT
When the line of code with the MsgBox function executes, you'll notice that the "Add-in connected to: Microsoft Word" message box appears in front of the Visual Basic window. This is very important to be aware of, because if your COM add-in project displays a message box or custom dialog box while your add-in project is in run mode in Visual Basic, the Office application may appear "frozen" after it loads the COM add-in. You need to switch to the Visual Basic window to interact with the message box or dialog box. (If your Visual Basic project is compiled into an add-in (.dll) and the Office application loads that compiled .dll file, any message box or custom dialog box will appear in front of the Office application window.)

Changing Code While in Break Mode

Visual Basic lets you fix errors in your code while in break mode. If your changes, however, affect the compiled state of the project, Visual Basic will display a message box, as shown below, telling you that the action will reset your project, and asking if you want to proceed anyway.

If you click OK, Visual Basic stops your project, but the Office application in which the add-in is loaded is not notified by Visual Basic that the add-in is no longer available. (You'll see that if you return to the Office application and display the COM Add-Ins dialog box, the add-in is still selected.) To reload the add-in, you must follow these steps:

  1. Display the COM Add-Ins dialog box and clear the add-in check box. Click OK.

  2. Switch to Visual Basic and run the project again by clicking Start from the Run menu.

  3. Switch back to the Office application and display the COM Add-Ins dialog box.

  4. Select the add-in check box and click OK.

The COM add-in's OnConnection procedure is executed again. If the OnConnection procedure isn't executed, exit and start the Office application again.

If you click Cancel in the message box, Visual Basic discards your changes and returns the project to break mode.

Stop the Project to Edit Your Code

  1. Switch back to Word, click the COM Add-Ins command, and then clear the Microsoft Office Basic COM Add-In for Word item in the COM Add-Ins dialog box. Click OK.

  2. Click the COM Add-Ins command, and then select Microsoft Office Basic COM Add-In for Word in the COM Add-Ins dialog box. Click OK.

    3. The first line of the OnConnection procedure is highlighted in yellow, indicating that your project is in break mode. The following steps explain how to stop a project when you want to add or edit your code.

  3. Click and drag the yellow arrow in the margin of the code module next to the line where code execution halts. Drag the arrow to the end of the procedure until it is adjacent to the line that contains the text End Sub.

  4. Press F5 to put your project back in run mode.

  5. In Word, click the COM Add-Ins command and then clear the Microsoft Office Basic COM Add-In for Word option in the COM Add-Ins dialog box. Click OK. Switch to the Visual Basic window. The OnDisconnection procedure runs.

    6. If there are errors, repeat steps 1 through 3. If there aren't, the add-in will be unloaded from the Office application. You can now safely stop your project.

  6. In Visual Basic, click End on the Run menu.

    7. Your project is back in design mode, where you can edit your code to fix errors or add new code to continue your project. When you need to debug your add-in, put your project back in run mode, return to the Office application, and select the appropriate add-in check box in the COM Add-Ins dialog box.

NOTE
If you find that your add-in isn't loading after you've selected the add-in check box in the COM Add-Ins dialog box, a connection between Office and your Visual Basic project may have been lost. Return to the COM Add-Ins dialog box, clear the add-in check box, and restart the Office application. When you display the COM Add-Ins dialog box again and select your add-in check box, the add-in should load.