Debugging DLL Projects

Article
11/03/2006

Several Visual Studio project templates create DLLs, which are debugged differently from stand-alone applications. Debugging DLLs is very similar to debugging stand-alone applications.

The following templates create DLLs:

(C++): MFC ActiveX Control

ActiveX controls are controls that can be downloaded over the Internet onto a client machine, and displayed and activated on Web pages.

Debugging them is similar to debugging other kinds of controls in that they cannot be run as stand-alone, but must be embedded in an HTML Web page. For more information, see How to: Debug an ActiveX Control.
(C++): MFC DLL

For more information, see MFC Debugging Techniques.
(C++): MFC ISAPI Extension DLL
(C++): ATL Project

For more information, see ATL Debugging Techniques.
(C++): Class Library
(C++): Windows Control Library

Debugging a Windows Control Library is similar to debugging a Class Library project. In most cases, you will call the Windows control from another project. When you debug the calling project, you can step into the code of your Windows control, set breakpoints, and perform other debugging operations. For more information, see Windows Forms Controls.
(C#, J#, and Visual Basic): Class Library
(C#, J#, and Visual Basic): Windows Control Library
(C#, J#, and Visual Basic): Web Control Library

For more information, see Web Control Library (Managed Code).

This section also contains information about the following topics:

This topic contains the following sections, which provide considerations on preparing to debug class libraries:

Building a Debug Version
Mixed-Mode Debugging
Changing Default Configurations
Ways to Debug the DLL
The Calling Application
Controls on a Web Page
The Immediate Window

Building a Debug Version

No matter how you start debugging, make sure you build the Debug version of the DLL first and make sure the Debug version is in the location where the application expects to find it. This may seem obvious, but if you forget this step, the application may find a different version of the DLL and load it. The program will then continue to run, while you wonder why your breakpoint was never hit. When you are debugging, you can check which DLLs your program has loaded by opening the debugger's Modules window. The Modules window lists each DLL or EXE loaded in the process you are debugging. For more information, see How to: Use the Modules Window.

For the debugger to attach to code written in C++, the code needs to emit DebuggableAttribute. You can add this to your code automatically by linking with the /ASSEMBLYDEBUG linker option.

Mixed-Mode Debugging

The calling application that calls your DLL can be written in managed code or native code. If your managed DLL is called by native code and you need to debug both, managed and native debuggers must both be enabled. You can check this in the <Project> Property Pages dialog box or window. How you do this depends on whether you start debugging from the DLL project or the calling application project. For more information, see How to: Debug in Mixed Mode.

Changing Default Configurations

When you create a console application project with the project template, Visual Studio automatically creates required settings for the Debug and Release configurations. If necessary, you can change those settings. For more information, see Project Settings for a C++ Debug Configuration, Project Settings for C# and J# Debug Configurations, Project Settings for a Visual Basic Debug Configuration, and How to: Set Debug and Release Configurations.

Ways to Debug the DLL

Each of the projects in this section creates a DLL. You cannot run a DLL directly; it must be called by an application (usually an EXE). For more information, see Creating and Managing Visual C++ Projects. The calling application may:

Be built in another project in the same Visual Studio solution that contains the class library.
Be an existing program already deployed on a test or production machine.
Be located on the Web and accessed through a URL.
Be a Web application that contains a Web page which embeds the DLL.

Debugging the Calling Application

To debug a DLL, start by debugging the calling application, typically either an EXE or a Web application. There are several ways to debug it.

If you have a project for the calling application, you can open that project and start execution from the Debug menu. For more information, see How to: Start Execution.
If the calling application is an existing program already deployed on a test or production machine and is already running you can attach to it. Use this method if the DLL is a control hosted by Internet Explorer, or a control on a Web page. For more information, see How to: Attach to a Running Process.
You can debug it from the DLL project. For more information, see How to: Debug from a DLL Project.
You can debug it from the Visual Studio Immediate window: in this case the Immediate window plays the role of the application.

Before you start debugging the calling application, you will usually want to set a breakpoint in the class library. For more information, see Breakpoints and Tracepoints. When the breakpoint is hit, you can step through the code, observing the action at each line, until you isolate the problem. For more information, see Code Stepping Overview.

Controls on a Web Page

To debug a Web page control, create an ASP.NET page that embeds it if such a page doesn't already exist. You then place breakpoints in the web page code as well as the control code. You then invoke the Web page from Visual Studio.

Before you start debugging the calling application, you will usually want to set a breakpoint in the DLL. When the breakpoint is hit, you can step through the code, observing the action at each line, until you isolate the problem. For more information, see Breakpoints and Tracepoints and Code Stepping Overview.

The Immediate Window

You can evaluate functions or methods in the DLL without having a calling application by doing design-time debugging using the Immediate window. To debug this way, do the following while the DLL project is open:

Open the Debugger Immediate window.
To test a method named Test in class Class1, instantiate an object of type Class1 by typing the following C# code in the Immediate window, this procedure works for other managed languages (VB, J#, C++) with appropriate syntax changes):
```
    Class1 obj = new Class1();
```
In C#, all names must be fully qualified. In addition, any methods or variables must be in the current scope and context of the debugging session.
Assuming that Test takes one int parameter, evaluate Test using the Immediate window:
```
   ?obj.Test(10)
```
The result will be printed in the Immediate window.
You can continue to debug Test by placing a breakpoint inside it and then evaluating the function again:
```
   ?obj.Test(10);
```
The breakpoint will be hit and you will be able to step through Test. After execution has left Test, the Debugger will be back in Design mode.

Debugging DLL Projects

Building a Debug Version

Mixed-Mode Debugging

Changing Default Configurations

Ways to Debug the DLL

Debugging the Calling Application

Controls on a Web Page

The Immediate Window

See Also

Reference

Concepts

Other Resources

Additional resources