How to Test and Debug a Migration DLL

Jason Roth
Microsoft Corporation

May 1998

Summary: A migration DLL allows an application installed on Microsoft Windows® 95 or Windows 98 to function correctly after a user has upgraded to Windows® 2000. (4 printed pages) This article covers two important aspects of creating a migration DLL:

  1. Testing to determine areas that need migrating

  2. Debugging a migration DLL during a Windows 2000 upgrade

Determining the Need for a Migration DLL

It is important to perform extensive testing to identify the areas in your application that do not work after upgrading to Windows 2000. This initial work makes writing the migration DLL more straightforward. It also provides a test suite for evaluating the success of a migration DLL once it is written.

First, install your application on Windows 2000 and run tests to ensure that it functions properly. A few areas to keep in mind are:

  1. Does your application handle multiple monitors correctly?

  2. Does installation write over any Windows 2000 system files with older ones?

  3. Does the application work with Windows 2000 printer drivers?

  4. Can your application communicate properly with NTFS drives?

  5. Are shortcut and menu items in the proper place?

  6. Are user settings being stored correctly?

If there are problems running the application on Windows 2000, you must decide whether it is possible to use the migration DLL to fix these problems. If not, you should place an incompatibility message that the user will see before choosing to upgrade the operating system. This can be accomplished by using the [Incompatible Messages] section of the Migrate.inf file. See the Win32 SDK "Migration Extension Interface Reference" for more details. (See the Platform SDK documentation in the MSDN™ Library.)

The next step tests how well your application migrates from Windows 95 or Windows 98. Install your application on Windows 95/98 and then upgrade to Windows 2000. Run all of the tests mentioned above, paying special attention to whether application and user settings migrated properly. In addition:

  1. Are there different binaries required for a Windows NT installation?

  2. Does the Windows NT installation require different or additional registry entries?

  3. Are there services that were not present on the Windows 95/98 installation that need to be installed for Windows NT?

Any areas that did not migrate properly should be fixed in a migration DLL. In addition to manual testing, you can use tools such as SysDiff.exe and RegEdit.exe to compare registry/file differences between a clean Windows NT installation of your product and an upgraded version. See the "Migration-Extension Interface" to find out more about SysDiff.exe as well as instructions on how to create the migration DLL.

Debugging a Migration DLL During the Windows NT5 Upgrade Process

There are two parts to debugging a migration DLL. Different techniques can be used to enable debugging during both the Windows 95/98 and Windows 2000 sides of Setup.

Debugging on Windows 95 and Windows 98

During the Windows 95/98 side of Setup, it is easiest to set breakpoints and step through the code using Visual C++®. Unfortunately, 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 will accidentally break into another migration DLL, causing Windows NT Setup to fail. The use of message boxes below avoids this problem. The following steps were created using Visual C++ version 5.0 but should be adaptable to other versions:

  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. Select Project and then Settings from the menu.

  3. Click the Debug tab in the Project Settings dialog box.

  4. Under Executable for Debug Session: enter the path to WinNT32.exe on the source for the Windows 2000 installation.

  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. Also check the Link tab of the Project Settings dialog box. Make sure that debug information is checked to be generated.

  7. In the Debug category of the Link tab, select Microsoft under Debug Info. This will be important during the Windows 2000 side of the debugging process.

  8. Select Build and then Start Debug and then Go from the menu or press F5.

  9. The upgrade will start, and the directory for the migration DLL can be specified during Setup when prompted for Upgrade Modules.

  10. When the migration DLL is processed, the message boxes will be 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.

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 the Web at the following address:

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

  1. In order to know when the migration DLL has been loaded by Setup.exe, you may want to place a message box in InitializeNT(). This will halt Setup and allow you to attach to the process and set breakpoints.

  2. When Setup reaches the message box, go to the command prompt and launch WinDbg.exe.

  3. It is critical that you first load the source code for the migration DLL before attaching to the process. Otherwise, Setup will hang.

  4. Select View and then Options from the menu.

  5. Under 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 contains debug information.

  6. Select Debug and then Attach to Process from the menu, and choose Setup.exe from the list of processes provided.

  7. Go to the source code that is open and use F9 or the menu to set breakpoints in the migration DLL.

  8. If the breakpoints are purple, WinDbg.exe cannot properly interpret the symbol information. Check over all of the steps above. Look at the Command window. It should give the directory that was typed into 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.

  9. Red breakpoints indicate success. When all breakpoints have been correctly set, you must restart the process that was temporarily halted by attaching to it. Select Debug and then Restart or use the toolbar. When Setup hits a breakpoint, you should be able to step through your code.

Warning   Do not close WinDbg.exe or stop debugging at any time during this process. It will automatically unload and close the process that it was debugging, in this case Setup.exe.

References

Downloads for migration DLLs can be found at:

http://msdn.microsoft.com/developer/windows2000/migration/default.asp.