Debugging DLL Projects

Article
11/15/2016

Note

This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The following templates create DLLs:

(C++, C#, and Visual Basic) Class Library
(C++, C#, and Visual Basic): Windows Forms 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# and Visual Basic): Web Control Library

For more information, see Web Control Library (Managed Code).
(C++): MFC ActiveX Control and MFC Smart Device ActiveX Control

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

Debugging ActiveX controls is similar to debugging other kinds of controls because 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 Smart Device DLL

For more information, see MFC Debugging Techniques.

This section also contains information about the following topics:
How to: Debug from a DLL Project
How to: Debug in Mixed Mode

This topic contains the following sections, which provide considerations about how to prepare 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 that you build the Debug version of the DLL first and make sure that 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 might 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 verify 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 must 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 want to debug both, managed and native debuggers must both be enabled. You can select 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# 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 might fit any one of the following criteria:

An application built in another project in the same Visual Studio solution that contains the class library.
An existing application already deployed on a test or production computer.
Located on the Web and accessed through a URL.
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 computer 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 does not 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.

The Immediate Window

You can evaluate functions or methods in the DLL without having a calling application. You do design-time debugging and you use the Immediate window. To debug in this manner, do the follow these steps 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 managed code works for Visual Basic and 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.