Visual Basic Concepts
Debugging Out-of-Process Components
This topic describes debugging procedures for most objects provided by out-of-process components. ActiveX documents, however, cannot be debugged as described here. See "Building ActiveX Documents."
To debug an out-of-process component
Set breakpoints and watch expressions as needed in your class module code.
Run the component project by pressing CTRL+F5 or clicking Start With Full Compile on the Run menu.
The component will compile, but Sub Main will not run until the first object is created in response to a client request.
Start a second instance of Visual Basic, and open your test project. Set breakpoints and watch expressions as needed.
Run the test project. When a breakpoint is encountered in the component code, the component project receives focus.
Note When an out-of-process component enters break mode, focus may not immediately switch to the component project. If you click anywhere on the client, the Component Busy dialog box will be displayed. Click Switch To button to give the focus to the component project.
When you’re finished with the debugging session, close your test project before stopping the component.
Important If you stop the component project before closing your test project, all of the objects the component was providing will be destroyed. Your test project may get errors when you try to close it.
Start With Full Compile
Always start your out-of-process component project by pressing CTRL+F5, or by clicking Start With Full Compile on the Run menu, so that all compilation errors are resolved before your component begins supplying objects to your test application.
The default in Visual Basic is to compile code on demand. This means that there may be code in your component which is not compiled until the client calls it. Some compile errors cannot be fixed without returning to design mode, which means shutting down the component. In that case, the test program is left holding invalid object references.
Note To disable demand compilation, select Options from the Tools menu, select the General tab of the Options dialog box, and clear Compile On Demand. This affects the current session as well as future instances of Visual Basic.
Editing the Test Project
As you develop your component, you’ll frequently add new functionality between debugging sessions. Before editing your test project to add code to exercise the new features, be sure to put your component project in run mode.
When the component project is not in run mode, the test project doesn’t have access to its type library. If you’re using Project Compatibility, the test project will fall back on the type library in the compiled executable. If it’s been a while since you made the executable, the type library won’t contain information on the features you’ve added.
If you’re using the No Compatibility option of Version Compatibility, there will be no type library information at all.
Your component project should always be in run mode when you’re editing the test project.
Shutting Down an Out-of-Process Component
When you’re debugging objects that have Terminate event code, remember that the Terminate event is not executed if you stop your component project using the End button on the toolbar, or if you choose End or Restart from the Run menu.
Shutting down test projects will release all the objects your component is providing to those projects. As those objects close down, they should release all references to private objects within your component.
This allows your component to meet the four rules for component shutdown, as listed in "Starting and Ending a Component," in "General Principles of Component Design."
Unfortunately, even when all objects have been released by your test projects, and all four shutdown conditions have been met, an out-of-process component will not return to design mode. To return to design mode, you will have to use the End button.
If your component maintains internal references to objects, you can simulate normal shutdown by creating a Sub procedure that releases all such references. You can call this procedure from the Immediate window before stopping your component — or place an End statement in the Sub. However, there is no guarantee that the order in which private objects are terminated will be the same under actual shutdown conditions.
The only way to accurately test shutdown behavior is with the compiled component.
Tip Debugging causes artificial changes in focus that may prevent your code from behaving as you expect. For debugging situations that are sensitive to focus or activation, such as mouse and key events, use Debug.Print to log debugging information.
Debugging Components as Standalone Desktop Applications
If your out-of-process component can double as a standalone desktop application, like Microsoft Excel, you have two startup and shutdown modes to test.
Such applications typically have code like the following, to allow them to start up with or without a main window:
Sub Main
If App.StartMode = vbSModeAutomation Then
' ...code to start invisibly...
Else ' (App.StartMode = vbSModeStandalone)
' ...code to show main form...
End If
End Sub
StartMode is a read-only property of the App object which can be used at run time to determine whether your application was started in response to a request from a client application, or by the user, through the Start button on the Taskbar.
Note Do not place Sub Main in a class module. Placing Sub Main in a class module turns it into a method named Main, rather than a startup procedure. Your Sub Main procedure must be in a standard module.
While debugging, you can control the mode your component starts in using the settings in the Start Mode box, on the Component tab of the Project Properties dialog box. Use the Standalone setting to start your component as if the user had opened it using the Start button on Taskbar; use the ActiveX Component setting to compile your component so that Sub Main will run when the client (your test project) first creates an object.
Debugging with Multiple Clients
If you need to debug a problem that only occurs when multiple client applications are using objects from your component, you can start additional instances of Visual Basic, or compile your test project and run the .exe file to provide the extra instances. You can run as many client applications as you need.
Components can be debugged whether they’re being called from a different Visual Basic project or from a client written in another language. For example, if you’re designing a component specifically for Microsoft Excel users, you may want to use Microsoft Excel as the client when you’re debugging.
For More Information "Using Break on Error in Components" explains how to use the Error Trapping options with component projects. See "Testing and Debugging ActiveX Components" for a list of topics related to testing and debugging.