HOWTO: Compile and Use my ISAPI Code Samples

Since I get this following question on how to compile/use my ISAPI code examples quite a bit, I wager I should just have a blog post that answers it once and for all.

But, come on you guys... I already did the hard part in providing the full compiling sample source code illustrating the solution to your problem(s). Why can't you figure out the simpler task of compiling that source code into an ISAPI DLL? ;-) I mean, it's not rocket science. It's just compilers and linkers.

Dare I say it... do I have to spoon-feed it to you like a child? hehe, ok, never mind... ;-) Here goes...

Anyways... I still use Visual C++ 6.0 to compile/link my ISAPI code samples (in fact, I usually test them out on IIS 5 as well as IIS 6, too). I am not bought into the .Net fever... at least not as far as ISAPI and IIS modifications are concerned. Don't get me wrong, .Net is great for end users to accomplish what they need at the higher, business-logic levels... but I am not convinced that .Net is useful at the lower-levels that ISAPI runs at. In particular, the memory overhead and native/managed code transitions alone kill performance, not to mention the SxS issues of multiple CLR versions in the same memory space. Native ISAPI code simply does not have such problems.

Anyhow, getting off that sidetrack... here are step-by-step instructions on how to compile/link my ISAPI code samples for both Visual C++ 6.0 and Visual C++ 2005 Express Edition.

Visual C++ 6.0

  1. File... New... -> Projects... Win32 Dynamic-Link Library

    • Give the project a name, a folder to store the project, and create a workspace (if that's what you want)
    • Create "an empty DLL project" and click OK to finish
  2. Project... Add to Project... New... -> C++ Source File

    • Give the source file a name and folder to store the file (preferably with the project you just created)
    • Copy/Paste the source code from my blog entry into the source file you just created
  3. Project... Add to Project... New... -> Text File

    • Give the text file a name (I usually use the same as the source file), extension of .DEF, and a folder to store the file (preferably with the C++ source file you just created)

    • Enter content into this file as directed by this blog entry for error data 0x7F. It is either

       LIBRARY Your_ISAPI_Extension_Name
      EXPORTS
          GetExtensionVersion
          HttpExtensionProc
      

      or

       LIBRARY Your_ISAPI_Filter_Name
      EXPORTS
          GetFilterVersion
          HttpFilterProc
      
  4. Everything should compile and link properly and be immediately usable on IIS.

    If you have compilation errors, then it is probably because you are compiling against older ISAPI headers. To fix this, you need to download and install the latest Microsoft Platform SDK, configure Visual C++ to use the include and library files from the SDK instead of the older ones from Visual C++ (this is under Tools...Options...Directories tab, insert the full path for include and library directories from the SDK to the top of their respective lists), and then compile/link.

    It should work at this point, and if not... you need to be on your own to figure it out because it has nothing to do with IIS/ISAPI at this point. :-)

Visual C++ 2005 Express Edition

  1. File... New... Project... -> Empty Project

    • Give the project a name, a folder to store the project, and create a workspace (if that's what you want)
  2. Project... Add New Item -> Code... C++ File (.cpp)

    • Give the source file a name and folder to store the file (preferably with the project you just created)
    • Copy/Paste the source code from my blog entry into the source file you just created
  3. Use notepad and create the .DEF file in a folder (preferably with the C++ source file you just created) with contents as directed by this blog entry for error data 0x7F. It is either:

     LIBRARY Your_ISAPI_Extension_Name
    EXPORTS
        GetExtensionVersion
        HttpExtensionProc
    

    or

     LIBRARY Your_ISAPI_Filter_Name
    EXPORTS
        GetFilterVersion
        HttpFilterProc
    
  4. Because the Express Edition does not give Win32 DLL Project as an option, we simply customize the empty project into what is necessary. Open up  Project... Properties (Alt-F7) -> Configuration Properties... and modify the following properties:

    • General... Configuration Type -> Change to "Dynamic Library (.dll)"
      [Why: Compile DLL instead of EXE]
    • General... Character Set -> Make sure it is "Not set"
      [Why: ISAPI is not Unicode]
    • C/C++... General -> Debug Information Format to "Program Database (/Zi)"
      [Why: Create PDB for debugging]
    • Linker... Debugging -> Generate Debug Info to "Yes (/DEBUG)"
      [Why: Create PDB for debugging]
    • Linker... Input -> Module Definition File. Give the full filepath to the .DEF file you just created
      [Why: Export the necessary signatures of ISAPI for IIS to LoadLibrary()]
  5. Everything should compile and link properly and be immediately usable on IIS.

    If you have compilation errors, then it is probably because you are compiling against older ISAPI headers. To fix this, you need to download and install the latest Microsoft Platform SDK, configure Visual C++ to use the include and library files from the SDK instead of the older ones from Visual C++ (this is under Tools...Options...Projects and Solutions...VC++ Directories -> insert the full path for include and library directories from the SDK to the top of their respective lists), and then compile/link.

    It should work at this point, and if not... you need to be on your own to figure it out because it has nothing to do with IIS/ISAPI at this point. :-)

Yes, I went and walked through both sets directions using the LoadBalancedIP sample code and loaded the resulting DLL on IIS5 to verify that everything functioned as intended. I am happy to say that it all worked for me the first time. :-) The Client-IP in my log file changed to whatever X-Client-IP request header stated.

So... if this does not work for you... then I really do not know what else to do. Maybe you should chuck this ISAPI thing out the window and wait for IIS7 modules. :-P

//David