HOW TO: Debug Common Gateway Interface Applications Running Under IIS by Using Visual Studio

This step-by-step article describes how to debug Common Gateway Interface (CGI) applications that are running under Internet Information Services (IIS) by using any version of Visual Studio.

Debug a Visual C CGI Application by Using Visual Studio

To debug a Visual C CGI application by using any version of Visual Studio, follow these steps:

1. The IIS Admin Service must interact with the desktop. To configure this, follow these steps:
   
   1. Open Control Panel and follow these steps:
      
      • For Windows NT: click Services.
      • For Windows 2000, Windows XP, and .NET Server: click Administrative Tools, and then click Services.
   2. Double-click IIS Admin Service.
   3. On the Log On tab, select the Allow Service to Interact with Desktop check box.
      
      Note This article assumes that the IIS Admin Service runs as a local system.
   4. Stop and restart the IIS Admin Service.
2. Before you include the Windows.h file, add the following code, and then build a debug version of the CGI:

   #define _WIN32_WINNT 0x0400
   

3. Paste the following code at the beginning of the CGI:

   #ifdef _DEBUG
   char szMessage [256];
   wsprintf (szMessage, "Please attach a debugger to the process 0x%X (%s) and click OK",
         GetCurrentProcessId(), argv[0]);
   MessageBox(NULL, szMessage, "CGI Debug Time!",
         MB_OK|MB_SERVICE_NOTIFICATION);
   #endif
   

4. Start the CGI application.
5. Attach a debugger (such as WinDBG or Visual C) to the CGI process while a message box is displayed.
6. When the debugger is attached, open the source file and set a break point, and then click OK.
   
   When the message box is closed, the CGI program resumes and the break point will be hit.

Using WinDBG

To debug a CGI application with WinDBG, although you do not have to change any code, you do have to be familiar with WinDBG and install the debugging tools. You can download the debugging tools from the following Microsoft Web site:

Set Service Options

Set the Image File Execution options so that when the service (or the CGI program) starts, it starts under the debugger. Make sure that the service can interact with the desktop, as instructed earlier in this article. Otherwise, when the CGI program starts, it loads the debugger and you will not see it.

1. Start Registry Editor (Regedt32.exe):
   
   Click Start, click Run, and then type regedt32.
2. Locate the following registry key:
   [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\]
3. Create a subkey with the name of your CGI executable file (for example, MyCGI.exe).
4. To this subkey, add the REG_SZ value named Debugger and the full path to the debugger, but omit the ".exe" extension. You can also add any commands for the debugger. The default location to install the WinDBG is the following:
   "Debugger"="C:\\Debuggers\\windbg.exe"
   
   Note The path that points to the WinDBG debugger must not contain any spaces or file extensions. For example, windbg, as shown in the following:
   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\yourCGI.exe "Debugger"="C:\windbg"
   
5. Close Registry Editor.
6. Stop and start the IISADMIN service, and then run the CGI program.
   
   Note For the debugger to appear on the default desktop, the IIS Admin service must run as Local System, and you must select the Allow Service to Interact with Desktop check box. To configure this, go to step 1 of the instructions earlier in this article.
7. The debugger will start when the image for the Service executable file is loaded into memory.

Note You may need to set the value of the CreateProcessAsUser property in the metabase to false in order to attach a debugger. This is because the account that the CGI application runs in may not inherit the Allow the Service to Interact with desktop setting for the IIS admin service when the CGI executable file is spawned. You can use the adsutil.vbs administrative script to set the Allow the Service to Interact with desktop setting. By default, the setting is true. For example, use the following command: