Establishing a Debugging Environment

There are several ways to establish an environment for debugging your server components and ISAPI extensions. If you are using a debugging tool capable of attaching to a Windows NT process, you can use this functionality to debug your component or extension. For example, if you are debugging an ISAPI extension with Microsoft Visual Studio™ you should take the following steps.

  1. Start the iisadmin process. This can be done from the command line with the command net start iisadmin. You can also use the Services dialog box from the Control Panel to start the IIS Admin Service, which will start iisadmin.
  2. Launch Visual Studio and select the Attach to Process command from the Start Debug sub-menu of the Build menu.
  3. Click the Show System Process check box.
  4. Select the inetinfo process from the list and click OK.
  5. Start the w3svc service. This can be done from the command line with the command net start w3svc. You may also use the Services dialog box in the Control Panel to start the World Wide Web Publishing Service.

If the debugging tool you are using is not capable of attaching to a Windows NT process, you should take the following steps to establish an appropriate debugging environment.

  1. Open the Services dialog box in the Control Panel.
  2. Select the IIS Admin service and click the Startup button.
  3. Select the Allow Service to Interact with Desktop check box and click OK.
  4. Repeat steps 2 and 3 for all processes that run under the IIS Admin process, for example World Wide Web Publishing Service, and FTP Publishing Service.
  5. Use the Registry Editor (REGEDIT) to add a subkey named Inetinfo.Exe to the HKEY_LOCAL_MACHINE/Software/Microsoft/WindowsNT/CurrentVersion/Image File Execution Options key.
  6. Add the following entry to this new key:
    Debugger = <DebuggerExeName> where DebuggerExeName is the full path to the debugger you are using.

When the World Wide Web Publishing Service is started, your debugger will also be launched. You can now set appropriate break points in your ISAPI extension.

You won't be able to set breakpoints in a component's source code until the component has been loaded into memory. First, you will need to start Internet Explorer and view the .ASP page containing the object. As soon as the page is loaded, you should be able to set breakpoints in your component. Select Refresh to view the page again, and trigger the breakpoints you selected. If the component cannot be loaded even once (for instance, if the fault occurs in component startup code) you will need to load the component DLL prior to starting the debugging session. (See step 11 below.)

In some cases, you may not be able to use either of the two procedures outlined above. If you have difficulty using either of these strategies, there is a third approach, which has been described in previous releases of IIS. This third approach requires the establishing of NT security privileges as well as making changes to the registry. It will also disable your ability to run IIS as a service. This approach should only be attempted if the previous two strategies have failed.

  1. Use the User Manager for Domains administration tool (USRMGR) to add the Log on as Service, Act as part of the operating system and Generate security audits rights on the local computer to the NT account you will use when debugging the ISAPI extension.
  2. Use the Distributed COM Configuration utility (DCOMCNFG) to change the identity of the IIS Admin Service to the user account you will use for debugging.
  3. Use the Registry Editor (REGEDIT) to remove the LocalService keyword from all IISADMIN-related subkeys under HKEY_CLASSES_ROOT/AppID. This keyword may be found in the following subkeys:
    {61738644-F196-11D0-9953-00C04FD919C1} // IIS WAMREG admin Service
    {9F0BD3A0-EC01-11D0-A6A0-00A0C922E752} // IIS Admin Crypto Extension
    {A9E69610-B80D-11D0-B9B9-00A0C922E750} // IISADMIN Service
    The LocalService keyword may be found in additional subkeys of AppID.
  4. Add LocalServer32 subkeys to all IISADMIN related subkeys under the CLSID node of the registry. This will include subkeys corresponding to all of the subkeys you removed in the previous step. Set the default value of these new keys to <path>\inetinfo.exe -e w3svc. (<path> is normally "c:\winnt\system32\inetsrv".)
  5. Stop the WWW and FTP services from the Microsoft Management Console, or from the Services dialog box in the Control Panel.
  6. Start Visual Studio and select the Debug tab in Project Settings window.
  7. Enter C:\WINNT\System32\Inetsrv\inetinfo.exe in the Executable for debug session field.
  8. Enter "-e w3svc" in the Program Arguments field.
  9. Select the Link tab in the Visual Studio Project Settings Window.
  10. Enter the name and path of the ISAPI extension you are debugging in the Output file name field.
  11. Optionally, add your component DLL to the list of Additional DLLs that are loaded before the application starts. This will allow you to set breakpoints in component startup code.
  12. Click the Go button to start the debugging session.

Note  After you have completed the debugging session, you must reverse steps five through one to restore the previous settings and allow IIS to be run as a service.