ISAPI Project Template Wizard

If you want to produce an ISAPI extension using more of the support that is afforded in MFC, the ISAPI Project Template Wizard should be used. The wizard will set up the project with the necessary support for ISAPI libraries and make a class that inherits from CHttpServer. The following MFC classes are provided for ISAPI:

• CHttpArgList Class containing functions and structures for parsing a URL.

• CHtmlStream Class useful for managing memory of data that is intended for writing to the client.

• CHttpFilter Class that extends the interface of IIS to produce an ISAPI filter. Filters are a type of ISAPI application that is called on each request to IIS, so they respond to events inside IIS.

• CHttpFilterContext Class provided as a parameter in the functions that are provided by CHttpFilter to process the content of a given HTTP event. CHttpFilterContext provides member functions, which are primarily designed to process data related to a given HTTP event passing through the filter.

• CHttpServer Class that extends the interface of IIS for a given HTTP request event.

• CHttpServerContext Class provided with the CHttpServer class that provides member functions useful for manipulating data related to a given HTTP event.

The classes provided in MFC offer a nice layer of abstraction to the raw interaction with ISAPI structures and functions shown previously. MFC allows the developer to have access to the raw ISAPI, but some classes are provided that make it easier to parse the headers and HTTP data that was being performed manually in the SEUX ISAPI extension. The wizard will produce a class that is named using the following schema: C<<ProjectName>>Extension. A function called Default acts as the main entry point for the ISAPI DLL and has the following prototype:

void Default(CHttpServerContext* pCtxt);

Function Default will take the place the of the HttpExtensionProc function that was used in the SEUX ISAPI extension for the main entry point. The pointer to the CHttpServerContext class that is passed into Default provides functionality and serves the need of the developer to manipulate data and the HTTP transaction that the ECB served in the SEUX ISAPI extension.

Creating an ISAPI Extension in Visual Studio .NET

To create an ISAPI extension using the Visual Studio .NET project template, open Visual Studio .NET and choose File | New | Project. The New Project dialog box will open, as shown in Figure 17-13. Choose the MFC ISAPI Extension DLL project template, enter a name for the project, and click the OK button.

Figure 17-13: Choosing an MFC ISAPI Extension DLL project template in Visual Studio .NET

Note 

The New Project dialog box shown in Figure 17-13 shows icons that are much different from the New Project dialog box shown in Figure 17-2. The versions of Visual Studio .NET used in each figure are exactly the same. In Figure 17-2, the Large Icons button in the upper-right corner was selected. In Figure 17-13, the Small Icons button was selected. The Large Icons and the Small Icons buttons are mutually exclusive choices, and they affect the project template icons that are displayed in the right pane of the New Project dialog box.

Much like the ATL Server Project Wizard discussed in Chapter 16, the ISAPI Extension Wizard is a one-step wizard that can be completed immediately by clicking the Finish button, as shown in Figure 17-14. The wizard summarizes the project settings in the Overview section. The default project type created is an ISAPI extension DLL with MFC in a shared DLL. Most ISAPI projects will conform to these specifications. These options may be changed in the Object Settings section.

Figure 17-14: ISAPI Extension Wizard Overview with a default ISAPI project

The Object Settings section provides for a means for changing the class names that are generated by the wizard, and it provides options to allow the ISAPI extension to link to MFC statically or dynamically. By choosing the Use MFC In A Shared DLL option, as shown in Figure 17-15, MFC will be linked dynamically in the ISAPI DLL that is generated at compile time. This option assumes that MFC will exist in the intended deployment environment by not including the content of MFC in the ISAPI DLL. If Use MFC In A Static Library is selected, the components of MFC that are needed by the ISAPI DLL are compiled into the DLL and linked statically. This option assumes that MFC does not exist in the deployment environment. The size of the DLL under static linking is much larger than in dynamic linking. In most cases, MFC should exist in the target environment since it is a Windows server. In the case of WS03, dynamic linking can be assumed to be adequate since MFC will exist on the server.

Figure 17-15: ISAPI Extension Wizard Object Settings section with a default ISAPI project

You can also generate a filter object by checking the Generate A Filter Object checkbox. Filters may be loaded into IIS to respond to every request that is handled by IIS. Filters function in much the same way as an ISAPI extension would function if it were mapped to every file that exists in the web root. A filter and an extension are not mutually exclusive options, either. A single DLL can host an extension and a filter, thereby allowing state to be shared by each through global variables.

ISAPI filters are difficult to produce and test, however. Because filters are invoked with each request to IIS, great care must be taken to ensure that they are efficient and built properly. They can easily utilize resource in a way that greatly diminishes from server efficiency as well as crash the server in the event that a problem occurs with the way the filter uses memory.

After you click the Finish button and the wizard completes the process of generating the files, the project may be compiled and run as soon as the DLL is deployed to the server. If it runs correctly, the following message should be displayed in the browser, with the class name that is consistent with the chosen name for the class:

This default message was produced by the Internet Server DLL Wizard. Edit your CMFCISAPIExtension::Default() implementation to change it.