Microsoft KB Archive/301056

= HOW TO: Debug a Migration DLL During a Windows 2000 Upgrade by Using Visual C++ =

Article ID: 301056

Article Last Modified on 10/27/2002

-

APPLIES TO


 * Microsoft Visual C++ 6.0 Professional Edition

-



This article was previously published under Q301056





IN THIS TASK
SUMMARY Requirements Debugging a Migration DLL
 * Debugging on Windows 95 and Windows 98
 * Debugging on Windows 2000

Troubleshooting REFERENCES



SUMMARY
A migration dynamic-link library (DLL) allows an application that is installed on Microsoft Windows 95 or Microsoft Windows 98 to function correctly after a user has upgraded to Microsoft Windows 2000. This article covers how to debug a migration DLL during a Windows 2000 upgrade.

back to the top

Requirements
The following items describe the recommended hardware, software, network infrastructure, skills and knowledge, and service packs you need:
 * Windows 95 or Windows 98
 * Windows 2000
 * Microsoft Visual C++

back to the top

Debugging a Migration DLL
There are two parts to debugging a migration DLL:
 * 1) Debugging on Windows 95 and Windows 98
 * 2) Debugging on Windows 2000

Different techniques can be used to enable debugging during both the Windows 95 or Windows 98 and Windows 2000 sides of Setup.

back to the top

Debugging on Windows 95 and Windows 98
On the Windows 95 and Windows 98 side of Setup, it is easiest to set breakpoints and step through the code using by Microsoft Visual C++. This process is complicated by the fact that there are other system migration DLLs with the same name, Migrate.dll, and the same exported functions. At times the Visual C++ debugger accidentally breaks into another migration DLL, causing Windows NT Setup to fail. The use of message boxes below prevents this problem.

The following steps were created using Visual C++ version 5.0, but are adaptable to other versions.

To debug on Windows 95 or Windows 98 by using message boxes, follow these steps:
 * 1) Determine what migration DLL code you need to break into and step through. At those places, add code to display message boxes. Do not set breakpoints in the integrated development environment (IDE).
 * 2) On the Project menu, click Settings.
 * 3) In the Project Settings dialog box, click the Debug tab.
 * 4) Under Executable for Debug Session, on the source for the Windows 2000 installation, type the path to Winnt32.exe.
 * 5) Under Program Arguments, type /#u:testdlls . This is very important, because it causes Windows 2000 Setup to run in the same process space as the migration DLL, making debugging possible.
 * 6) In the Project Settings dialog box, click the Link tab. Make sure that Generate debug information is selected.
 * 7) In the Debug category of the Link tab, select Microsoft under Debug Info. This is important for the Windows 2000 side of the debugging process.
 * 8) On the Build menu, click Start Debug and then click Go (or press F5).
 * 9) The upgrade starts, and you can specify the folder for the migration DLL when the Upgrade Modules dialog box appears during Setup.
 * 10) When the migration DLL is processed, the message boxes are displayed. Return to the Visual C++ IDE and set breakpoints in the code following the message box. Only set breakpoints in the current function.
 * 11) Before continuing Setup, unset any breakpoints to avoid Visual C++ inadvertently breaking into other migration DLLs.

back to the top

Debugging on Windows 2000
During the Windows 2000 side of the debugging process, Visual C++ can no longer be used as the debugger. Instead, Windbg.exe can be used to attach to the Setup process. It is possible to maximize a command window that is at the bottom of Windows NT GUI-Mode Setup. From the command prompt, run Windbg.exe and attach to Setup.exe. Windbg.exe can be installed from following Microsoft Developer Network (MSDN) Web site:

http://msdn.microsoft.com/developer/sdk/platform.htm

To debug on Windows 2000, follow these steps:
 * 1) To know when Setup.exe has loaded the migration DLL, you may want to place a message box in InitializeNT. This halts Setup and allows you to attach to the process and set breakpoints.
 * 2) When Setup reaches the message box, type Windbg.exe at the command prompt.NOTE: It is critical that you load the source code for the migration DLL before you attach to the process. Otherwise, Setup stops responding (hangs).


 * 1) On the View menu, click Options.
 * 2) On the Symbols tab, type in the full path to the location of the .pdb file. This is the program database that Visual C++ creates, and it contains debug information.
 * 3) On the Debug menu, click Attach to Process, and then select Setup.exe.
 * 4) Go to the source code that is open and use F9 or the menu to set breakpoints in the migration DLL.
 * 5) * If the breakpoints are purple, Windbg.exe cannot properly interpret the symbol information. Check over all of the above steps. Look at the Command window. It should list the folder that you typed in the Symbols tab, and it should say (Symbols Loaded). If it indicates that symbols cannot be loaded, make sure that you are pointing to the correct path of the .pdb file.
 * 6) * Red breakpoints indicate success. When all breakpoints have been correctly set, you must restart the process that was temporarily halted by attaching to it. Click Debug and then click Restart, or use the toolbar. When Setup hits a breakpoint, you can step through your code.

back to the top

Troubleshooting
When you debug on Windows 2000, do not close Windbg.exe or stop debugging at any time during the process. Windbg.exe automatically unloads and closes the process that it was debugging (in this case, Setup.exe).

back to the top

