Enabling Debugging for IIS

Applies To: Windows Server 2003, Windows Server 2003 with SP1

By default, when a worker process is determined to be unhealthy, the WWW service terminates it and starts a new worker process to serve new or queued client requests. Optionally, you can allow an application pool to keep the worker process running, but release, or orphan, the worker process from the application pool for purposes of debugging while at the same time initializing a new worker process to handle incoming client requests. An orphaned worker process ceases to take new requests from HTTP.sys.

If you enable debugging on an application pool, the WWW service allows an unhealthy worker process to keep running when the WWW service releases the worker process from serving an application pool. When enabling debugging, you can also configure the WWW service to start an executable application or script for a released worker process. For example, the WWW service might start an application that sends you an e-mail notifying you of the failure.

To enable debugging, set the OrphanWorkerProcess property to true. Use the OrphanActionExe and OrphanActionParams properties to configure the application that will run when the worker process is orphaned. For example, to use Adplus.vbs to obtain a memory dump, you could set the properties as follows:

OrphanActionExe: %SystemRoot%\System32\CScript.exe

OrphanActionParams: C:\debuggers\adplus.vbs -quiet -hang -p %1%

Be sure to closely monitor any worker process that is released from its application pool but continues to run. The worker process can terminate because the WWW service leaves it running but no longer monitors it, which effectively tells the worker process to shut down without forcing it to do so. If the worker process recovers from its unhealthy state, it detects that it has no relationship to the WWW service and self-terminates. When an orphaned worker process self-terminates, you might find an event log entry stating that a worker process was released, but find no evidence of the worker process ever having run.

If you enable debugging on unhealthy worker processes, be sure to monitor these released worker processes, because IIS does not remove them from memory. If you do not correctly handle worker processes that you keep alive for debugging purposes, you can have many failed worker processes running on your computer. These worker processes can tie up resources needed by other processes. In such a case, you might need to terminate those worker processes quickly to free those resources. In some cases, these worker processes can block metabase access and cause problems with other worker processes or with the WWW service itself.

The OrphanActionExe and OrphanActionParams property settings shown above will leave an orphaned worker process running after obtaining a dump file. As an alternative, you can use CDB directly from a .cmd script file. For example, paste the following text into a new text file and save the file as LocalDrive\debuggers\action.cmd:

@if "%_echo%"=="" echo off
setlocal

set WORKINGDIR=c:\debuggers
set FILENAME=%WORKINGDIR%\crash.dmp
set LOG=%WORKINGDIR%\log.txt
set COMMAND=c:\debuggers\cdb.exe -c ".dump /o /mhf /u %FILENAME%;q" -p %1

echo %COMMAND% > %LOG%
%COMMAND%

Endlocal

Then you can set the orphaning properties as follows:

OrphanActionExe: C:\Debuggers\action.cmd

OrphanActionParams: %%1%%

Using the .dump command combined with the q command with the CDB debugger will capture the dump file and terminate the worker process.