The Simplest ISAPI Extension That Could Possibly Work

The Simplest ISAPI Extension That Could Possibly Work^[1]

^[1] With apologies to Kent Beck.

Let's take a look at a simple "Hello, World" ISAPI extension. The result looks like Figure 13.1.

Figure 13.1. Hello World, ISAPI style

[View full size image]

Writing the Extension

Starting with a Win32 DLL project (not an ATL DLL project) named HelloISAPI, including the HttpExt.h system header file in stdafx.h brings in the ISAPI extension types, which enables us to implement the GetExtensionVersion function:

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer) {
  pVer->dwExtensionVersion = HSE_VERSION;
  strncpy_s( pVer->lpszExtensionDesc,
    HSE_MAX_EXT_DLL_NAME_LEN,
    "Hello ISAPI Extension", _TRUNCATE );
  return TRUE;
}

All I did here was set the ISAPI version number (HSE_VERSION is a constant defined in HttpExt.h) and fill in the description field for use by IIS. We use the HSE_VERSION constant because we're reporting the version of the ISAPI API that we're using, not the version number of our extension DLL. This way, as IIS and ISAPI changes, IIS can maintain backward-compatibility with older extensions.

The meat of the extension is the HttpExtensionProc function:

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB) {
  char *header =
    "<html>"
      "<head>"
        "<title>Hello from ISAPI</title>"
      "</head>"
      "<body>"
        "<h1>Hello from an ISAPI Extension</h1>";

DWORD size = static_cast< DWORD >( strlen( header ) );
pECB->WriteClient( pECB->ConnID, header, &size, 0 );

char *intro = "<p>Your name is: ";
size = static_cast< DWORD >( strlen( intro ) );
pECB->WriteClient( pECB->ConnID, intro, &size, 0 );
  size = static_cast< DWORD >(
    strlen( pECB->lpszQueryString ) );
  pECB->WriteClient( pECB->ConnID, pECB->lpszQueryString,
    &size, 0 );

  char *footer =
        "</p>"
      "</body>"
    "</html>";

  size = static_cast< DWORD >( strlen( footer ) );
  pECB->WriteClient( pECB->ConnID, footer, &size, 0 );

  return HSE_STATUS_SUCCESS;
}

This method simply builds up a series of strings and then sends them out to the browser via the pECB->WriteClient() method. We also grab the query string (the stuff in the URL after the ?) by using the lpszQueryString field in the EXTENSION_CONTROL_BLOCK.

In this case, the TerminateExtension method doesn't need to do anything and, thus, is technically optional, but adding a minimal stub for completeness looks like this:

BOOL WINAPI TerminateExtension(DWORD dwFlags) {
  return TRUE;
}

Returning trUE tells IIS that it can unload this extension. If we had loaded anything that needed to be cleaned up, the call to TerminateExtension would be the place to do it.

There's one more thing we need to add to the project before we can deploy it: We have to export the ISAPI entry points. Normal practice is to add the __declspec(dllexport) declaration to each of the ISAPI functions; this tells the compiler that we want the suitably decorated function to be exported from the DLL. Unfortunately, when you do this with an ISAPI extension, you get this:

c:\helloisapi\helloisapi.cpp(24)  : error C2375: 'GetExtensionVersion' :
redefinition; different linkage
        c:\program files\microsoft visual studio
8\vc\platformsdk\include\httpext.h(526) : see declaration of
'GetExtensionVersion'
c:\helloisapi\helloisapi.cpp(33)  : error C2375: 'HttpExtensionProc' :
redefinition; different linkage
        c:\program files\microsoft visual studio
8\vc\platformsdk\include\httpext.h(527) : see declaration of
'HttpExtensionProc'
c:\helloisapi\helloisapi.cpp(65)  : error C2375: 'TerminateExtension' :
redefinition; different linkage
        c:\program files\microsoft visual studio
8\vc\platformsdk\include\httpext.h(528) : see declaration of
'TerminateExtension'

If we look inside HttpExt.h on lines 526528, we see the problem:

/************************************************************     
*    Function Prototypes                                          
*    o  for functions exported from the ISAPI Application DLL     
************************************************************/     
                                                                  
                                                                  
BOOL  WINAPI   GetExtensionVersion( HSE_VERSION_INFO *pVer );     
DWORD WINAPI   HttpExtensionProc( EXTENSION_CONTROL_BLOCK *pECB );
BOOL  WINAPI   TerminateExtension( DWORD dwFlags );

The HttpExt.h file includes prototypes for the ISAPI entry points, but alas, the prototypes don't include __declspec(dllexport). When the compiler sees the prototype without the export directive and the actual implementation with the directive, it gives the error I just showed you.

To work around this, we need to do exports the old-fashioned way: Add a .def file to the project. This is a separate file that explicitly lists the functions we want exported from our DLL. As the number of exports grows, a .def file gets difficult to maintain, but we've got only three exports here, and they're the same for every ISAPI extension, so it's not too much of a burden.

The .def file looks like this:

;HelloISAPI.def  : Declares the module parameters for the DLL.
LIBRARY    "HelloISAPI"

EXPORTS
   HttpExtensionProc
   GetExtensionVersion
   TerminateExtension

Configuring the Server

Next, we need to get the extension onto the server. Luckily, Visual Studio has some web-deployment tools built in to help, but when you're starting from scratch, they're not set up yet.

First things first: We need an IIS Virtual Directory. I recommend creating a directory that's separate from your build directory for this (you'll see why in a moment). The Internet Services Manager is a nice place to create virtual directories; the sample is called HelloISAPI.^[2]

^[2] To create a virtual directory, first create a directory via Windows Explorer. It's easiest to create it under C:\inetpub\wwwroot because permissions will be set correctly. Next, open the Internet Services Manager. Expand the treeview on the left until you see Default Web Site. Right-click this and choose New, Virtual Directory. Follow the wizard to name the virtual directory, and then choose the directory you just created. Click Next and then Finish.

Next, we need to configure permissions on the directory so that the ISAPI extension will be executed and, more important, so we can debug it. In Internet Services Manager, right-clicking the HelloISAPI virtual directory and choosing Properties yields Figure 13.2.

Figure 13.2. Virtual directory properties

We need to make sure two settings are correct in this dialog box. The first is the Execute Permissions drop-down list, which must be set to Scripts and Executables. (It defaults to Scripts Only.) Without this setting, instead of loading the extension and executing it, IIS attempts to download the DLL to your browser.

The second setting is the Application Protection drop-down list. For easy debugging, you want this set to Low. This causes IIS to load an extension directly into the IIS process. This is generally a bad thing to do on a production server because misbehaving extensions can take the IIS process down with it, but for debugging, it just makes things easier. Do this only on a development server, not on your production boxes!^[3]

^[3] Some recommend that you debug in IIS out-of-process mode. Although I can see the appeal, setting that up involves mucking around with COM+ settings, which is often very complicated to get right. If you want to give it a try, take a look at http://www.west-wind.com/presentations/iis5Debug.htm (http://tinysells.com/53).

Configuring the Project

With a virtual directory created and configured to receive our ISAPI extension code, we want to configure Visual Studio to deploy the code on a successful build. In the project's property pages, there's an entry called Web Deployment (see Figure 13.3).

Figure 13.3. Web Deployment settings

[View full size image]

By default, the Excluded From Build property is set to Yes, which means that web deployment won't happen. Changing it to No enables web deployment, which, by default, uses the name of the project at the IIS virtual directory name that will receive the result of a successful buildin this example, our HelloISAPI.DLL file.

At this point, compiling the project and surfing to http://localhost/HelloISAPI/HelloISAPI.dll?SomeName should get back a result that looks like Figure 13.1. If you make changes to the project and rebuild, VS is smart enough to tell ISAPI to unload our DLL so that it can be replaced. This is also the reason that we wanted a separate build directory from our virtual directory. If we compile straight into the virtual directory, IIS typically has the DLL locked. You would need to use a prebuild step to shut down IIS so that Visual Studio could regenerate the .dll file after it compiles. By using web deployment, you don't need to pay the compile-time speed hit for resetting IIS until the compile succeeds.

If you click F5 to start a debugging session, by default, you get the helpful Executable for Debug Session dialog box. We want to configure Visual Studio to automatically attach to IIS when debugging. To do this, navigate to the Debugging page of the project properties and set the options to match those shown in Figure 13.4.

Figure 13.4. Debugging settings

[View full size image]

You need to change these two fields:

Command. Set this to inetinfo.exe, which is the name of the IIS process.
Attach. Set this to Yes. If it is set to No, the debugger attempts to start a second copy of inetinfo.exe. Yes means "Attach to already running copy."

Now, to debug your extension, set your breakpoints wherever you want and click F5 to start the debugger. Visual Studio crunches for a while after it attaches to IIS and then looks like it's doing nothing. At this point, start a browser and point it at your extension's URL; your breakpoints should fire.