This article describes the details of debugging Shell extensions written with Borland Delphi or C++ Builder.

Introduction

Nowadays the integrated programming environments - Borland Delphi and Borland C++ Builder represent rather convenient means for developing Windows Shell extensions (further on: Shell extensions).

In contrast to the Microsoft development environment, where all of the Shell extension code is embedded in the template, generated with the help of , Delphi and C++ Builder provides you with the opportunity to use similar Template Wizards, it also provides a faster and simple visual approach for Shell extensions developing, for example the components package (www.shellplus.com).

In any case the important question is the debugging of your Shell extensions. This article was written to assist the programmers, who use Borland Delphi (C++ Builder) for developing Shell extensions. It will be equally useful to both those who use the visual approach, and those, who write Shell extensions "from scratch".

As for any other DLL debugging you should specify the Host Application for your Shell extension. Your Shell extension will be loaded into the address space of this application. In our case such an application is represented by Windows Explorer. Go to the menu Run | Parameters..., press the Browse button and choose the Explorer.exe file from the Windows directory. Do not hasten to start debugging though, there are a lot of significant nuances ahead.

You should include all the necessary debugging information into your project. For this purpose open the window (using the menu Project | Options...), proceed to the tab and in the group check the item. It should activate generation the special data for remote debugging, which are also necessary for debugging COM-applications. When you are done with the debugging of your Shell extension do not forget to switch this option off, as it considerably increases the size of the module and creates an even greater-sized file with the extension *.rsm, which stores all the symbols for the remote debugging. For the convenience of debugging it's also recommended to check in the tab of the dialogue. It will allow you to keep track of the internal work of the modules, which were not included into the list of your project modules.

You should also keep in mind the availability of the source code of your Shell extension for the Delphi debugger. They should be located in the current Delphi directory or the path to them should be registered in the Project | Options | Directories/Conditionals, item - .

On completion of all  adjustments to the  project's properties you should rebuild the entire project (through the menu item Project | Build...).





Debugging Shell extensions under Windows XP and Delphi

If you use Windows XP, you should have difficulties with debugging DLL-libraries. They are as follows - the Delphi debugger does not load the debugging information symbols from the library.

This mistake has already been corrected for Delphi 7, but if you work with the earlier versions, you may find the following advice useful: do all the preparations for debugging as described above, then start debugging. Once the main application has been started, switch to Delphi and press the Ctrl + Alt + M combination of keys. In the opened list of the loaded modules find your module, right-click on it and choose Reload Symbol Table. Enter the complete path to your DLL in the window, which will appear, and press OK. The remote debugging symbols table should be reloaded and you will get the opportunity to set up the breakpoints and track your Shell extension work.




Preparing MS Windows

The carrier of the Shell functionality is the Windows Explorer application. On the computer screen you can see such objects as Desktop, Taskbar, and contents of the folders. All these objects are supported by the Windows Explorer application, and you can see his process in the Task Manager.

The bound to it process is referred to as Explorer.exe. You can also see there, that sometimes several copies of this process are running. Do not be surprised -- it depends on the Windows properties, as will be shown later.

Windows Shell automatically  unloads a dynamic library when its internal counter is equal to zero, but it occurs only at the expiration of a certain period of time. It is done to accelerate the work of the environment, but it is not always convenient while writing or debugging Shell extensions within the limits of one operational system - at compilation of an already registered Shell extension its file may appear blocked for writing. For the operational systems of versions earlier than Windows 2000 you can reduce this period by feeding the following information into the register:

HKLM
      Software
              Microsoft
                      Windows
                              CurrentVersion
                                          Explorer
                                              AlwaysUnloadDll  

When you are done with the debugging of your Shell extension do not forget to switch this option off, as it has a bad effect on Windows productivity.

In any operational system it is possible to apply the following method to start Windows Shell under debugging:

Load the project for debugging into Delphi.
Choose " End of work " from the "START-UP" menu.
Press the buttons CTRL + ALT + DEL simultaneously and click "No" in the " End of work with Windows " dialogue. In Windows 2000 click "Cancel". As a result Shell should be unloaded from the memory of the computer (Task Bar, icons from the Desktop and open windows with the contents of folders and disks will disappear), but all other applications will be running, including Delphi with your project.
Adjust all the properties necessary for the Shell extensions debugging and start the debugger. Shell should start normally, but now it will be working under the debugger''s control.
Debugging Shell extensions under Windows NT/2000/XP you can setup the start of several copies of Windows Explorer (separate copies for Task Bar, for each window with the contents of folders or disks, etc.). As a result you will be able to debug your Shell extensions without unloading Task Bar and Desktop, which is much more convenient. To setup this opportunity you should add the following information to the register:

HKEY_CURRENT_USER\
              Software\
                       Microsoft\
                              Windows\
                                       CurrentVersion\
                                                    Explorer\
                                                           DesktopProcess(REG_DWORD) = 1  

To make the feature take effect you should Log off and then Log on. When you are done with the debugging of your Shell extension do not forget to switch this option off, as it slows down Windows considerably.





Shell Extensions Debugging

After all the preparations have been done you can press Run (F9) and start debugging your Shell extension.  Set up the interruption points in the appropriate places, use the buttons "Program Pause" and "Program Reset" if necessary. There are no other differences between debugging Shell extensions and debugging regular Delphi applications. Also, do not be surprised, if breaking the project debugging through will cause an automatic Windows Explorer loading. It is the standard reaction of Windows to errors while quitting an Explorer process. To end up the debugging process successfully you can take advantage of the way described above (through Start | End of work).

Windows Explorer is a multi-thread application. For every Shell extension in use it creates a separate thread, in which it works with it further. Therefore do not be surprised, if during the step-by-step debugging you will suddenly be thrown to some other code area, where you have debugged recently, and then returned to the initial spot. You can keep track of your travels through the threads in the window Thread status, which can be opened through the menu View | Debug Windows | Threads.

As you can see, Shell extension debugging is not complicated. We wish you good luck in developing useful and successful Shell extensions.