Debugging Protocol Handlers
Integral to testing and debugging your protocol handler implementations is understanding how protocol handlers are launched.
This topic is organized as follows:
The SearchIndexer process (searchindexer.exe) launches one copy of the SearchProtocolHost process (SearchProtocolHost.exe) in the system context and another copy in the user context. Then, the protocol handlers are loaded in the SearchProtocolHost process as needed. They are not unloaded until the search service is stopped. The same instance of a protocol handler is reused any number of times while the service is running.
The SearchIndexer and SearchProtocolHost processes communicate frequently during indexing. If you pause or stop the SearchProtocolHost process to debug, the SearchIndexer will launch a new SearchProtocolHost process, invalidating your debugging session. Also, if you attach your debugger directly to the SearchProtocolHost process, you can break handle-inheritance from searchindexer.exe to searchprotocolhost.exe, and the two processes will be unable to communicate.
To avoid these problems, you need to notify the search service that you are debugging, and you need to attach the debugger to the SearchIndexer process with instructions to debug child processes, as described next.
Follow these steps to set up debugging for your protocol handler.
- Notify the search service that you are debugging by setting the DebugFilters value to 1 in the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft Windows Search Gathering Manager DebugFilters = 1
- Attach a debugger using the Image File Execution Options registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion Image File Execution Options SearchIndexer.exe Debugger = <path to debugger> <debugger options>
The options for a sample debugger are described in the following table.
Example using the ntsd debugger
Debugger = C:\debuggers\ntsd.exe -odGx -c: "sxe ld mydll.dll;g"
Option Description -o Tells ntsd.exe to debug child prcoesses. -d Pipes ntsd.exe through the kernel debugger to ensure the debugger is lauched on the right desktop (system context). -g Tells ntsd.exe to exit immediately when the child terminates. -x Disables first-chance break on access violation exceptions. The second occurrence of an access violation will break into the debugger. -c Sets the order of commands passed ntsd.exe.
- Restart searchindexer.exe under the debugger using compmgmt.msc, services.msc, or a command window with commands similar to the following:
net stop wsearch <copy new DLLs for debugging> net start wsearch
To distinguish between a SearchProtocolHost process running in the system context and one running in the user context, you can review the environment strings. With ntsd.exe, for example, you can use extension command !peb to display a formatted view of the information in the process environment block (PEB).
- For information on creating handlers, see Registering Shell Extensions.
- Developing Protocol Handlers
- Understanding Protocol Handlers
- Notifying the Index of Changes
- Adding Icons and Context Menus
- Code Sample: Shell Extensions for Protocol Handlers
- Creating a Search Connector for a Protocol Handler
- Installing and Registering Protocol Handlers