ISAPI开发介绍

引言

 

         主要介绍ISAPI的作用、ISAPI在IIS7上的配置、开发ISAPI的基本内容及使用VS 2008配置ISAPI DLL开发项目。

 

一、ISAPI介绍

 

缩写词=Internet Server Application Programming Interface为Microsoft所提的Internet server的API 。

ISAPI分为两种：ISAPI extension （ISAPI扩展）和 ISAPI filter （ISAPI筛选器）。

1、ISAPI 服务器扩展是可以被 HTTP 服务器加载和调用的 DLL。ISAPI扩展（extension）也称为 Internet 服务器应用程序 (ISA)，用于增强符合 Internet 服务器 API (ISAPI) 的服务器的功能。ISAPI扩展（extension）通过浏览器应用程序调用，并且将相似的功能提供给通用网关接口 (CGI) 应用程序。

2、ISAPI 筛选器是在启用 ISAPI 的 HTTP 服务器上运行的 DLL，用以筛选与服务器之间来回传送的数据。该筛选器注册事件的通知，例如登录或 URL 映射。当发生选定事件时，筛选器被调用，并且您可以监视及更改数据（在数据从服务器传输到客户端或相反的过程中）。可以使用 ISAPI 筛选器提供增强的 HTTP 请求记录（例如，跟踪登录到服务器的用户）、自定义加密、自定义压缩或其他身份验证方法。

 

二、ISAPI导出函数

 

1.    ISAPI扩展(ISAPI extension)导出函数：

1、BOOL WINAPI GetExtensionVersion( HSE_VERSION_INFO  *pVer);
该函数是扩展DLL文件第一次被加载到站点处理进程时被调用。

2、DWORD WINAPI HttpExtensionProc( LPEXTENSION_CONTROL_BLOCK  lpECB);
该函数是IIS服务每次触发ISAPI扩展时所调用的函数。也就是IIS服务增强服务时具体的实现内容通过本函数的调用。

3、BOOL WINAPI TerminateExtension( DWORD  dwFlags);
该函数是ISAPI扩展DLL文件从进程中被载时调用一次。

2.    ISAPI 筛选器(ISAPI filter)导出函数

1、BOOL WINAPI GetFilterVersion( PHTTP_FILTER_VERSION pVer);
该函数是DLL筛选器第一次被加载到站点处理进程时被调用。

2、DWORD WINAPI HttpFilterProc(PHTTP_FILTER_CONTEXT pfc,DWORD notificationType,LPVOID pvNotification);
该函数用于响应注册在 GetFilterVersion 的形参PHTTP_FILTER_VERSION 中的dwFlags通知事件。根据所注册的通知事件进行相应的筛选处理。

3、BOOL WINAPI TerminateFilter(DWORD dwFlags);
该函数是DLL筛选器被站点处理进程卸载时时所调用的处理。

 

三、使用Visual Studio创建ISAPI项目

 

在Visual Studio 2008的版本及以后版本中，Visual C++的创建项目类别中，不再有关于ISAPI扩展和ISAPI筛选器的直接项目相关的创建选项。因此在VS2008中的Visual C++创建项目类别中，选择“Win32项目”的项目类别，然后根据“添加新项目”向导中的应用程序类别下的“DLL”并选择“空项目”复选框来创建一个空白的dll项目，并且由此配置成ISAPI扩展和ISAPI筛选器的dll项目。

1.       创建空白的DLL项目步骤

1）打开“Visual Studio2008”，选择VS界面主菜单上的“文件(F)”菜单项，选择“新建(N)”菜单项下的“项目(P)”菜单，打开“新建项目”对话框。

2）选择“新建项目”对话框中的项目类型中的“Visual C++”树节点下的“Win32”节点；

3）在右边的“模板”框中，选择”Win32项目”，然后填写相关的名称、位置、解决方案名称等信息后“确认”，打开“Win32应用程序向导”对话框；

4）点击打开的“Win32应用程序向导”对话框中的下一步，选择应用程序类别“DLL”，选择附加选项“空项目”，“确定”完成新项目创建。

 

2.       配置空白DLL项目生成ISAPI扩展(ISAPI Extension) DLL。

步骤1：右击项目，使用“添加”菜单下的“新建项…”菜单项，使用“添加新项”添加C++文件；

步骤 2：在新建的cpp文件中，#include 并实现三个导出函的定义；

步骤 3：右击项目，使用“添加”菜单下的“新建项…”菜单项添加模块定义文件，这时，模块定义文件会自动被配置到“DLL项目”属性下的“链接器”—“输入”配置项中的模块定义文件下；

步骤 4：在定义模块文件中，编写导出函数定义；如：

LIBRARY    "MyISAPIExtension"

EXPORTS

           GetExtensionVersion       @1

           HttpExtensionProc           @2

                    TerminateExtension         @3

（备注：三个导出函数被导出的时候不能被VC++编译器导出后函数名发生改变，所以使用定义模块文件对三个文件进行导出。或许可以使用extern “C” l加__declspec(dllexport)对三个导出函数进行导出操作；）

 

3.       配置空白DLL项目生成ISAPI筛选器(ISAPI Filter) DLL。

（同配置生成ISAPI 扩展一样，只是将ISAPI扩展的包含的头文件及三个筛选器导出函数配置替换成ISAPI筛选器的头文件httpfilt.h及三个筛选器导出函数的配置。）

 

四、在IIS7上ISAPI 的应用设置

1、  ISAPI扩展(ISAPI extension)的使用配置。

        预先配置：

        需要在IIS7的” Internet信息服务(IIS)管理器”上的全局配置中的“ISAPI和CGI限制”添加设置允许ISAPI模块文件路径；或设置“ISAPI和CGI限制”配置页面上右上角的“编辑功能设置”，选择“允许未指定的ISAPI模块”以确保要添加的ISAPI模块不会被禁用。

（1）       文件扩展名映射处理配置

1)         打开IIS7的” Internet信息服务(IIS)管理器”，点击所要配置的站点；

2)         在打开的站点配置主页的IIS组中选择“处理程序映射”，打开处理程序映射的配置页;

3)         在管理器窗口的右上角有个“操作”栏，选择“添加模块映射”。（该站点必须是绑定集成管道的应用程序池）；

4)         在“添加模块映射”窗口的模块中选择“IsapiModule”，然后选择dll文件，并填写相应的配置信息；

5)         点击“请求限制…”按钮，选择“请求限制”对话框中的“访问”选项卡下的“执行”单选项，然后确定；

6)         最后“确认”添加映射模块。

（2）       URL调用ISAPI扩展(ISAPI extension)方式设置，
调用如，在浏览器中直接输入: http://www.bizcn.com/MyIsapiExt.dll 进行isapi扩展的调用

如果按照“预选配置”的内容配置完”ISAPI和CGI限制”的配置内容之后，按以下步骤进行操作：

1)       打开IIS7的” Internet信息服务(IIS)管理器”，点击所要配置的站点；

2)       选择站点配置主页下的IIS配置组中的“处理程序映射”，打开站点的“处理程序映射”页;

3)       选择站点的“处理程序映射”配置页的右边“操作”栏中的“编辑功能权限”，打开“编辑功能权限”对话框；

4)       在“编辑功能权限”对话框中，选择“脚本”和“执行”两个复选框。

2、  ISAPI筛选器(ISAPI filter)的使用配置

        选择要添加筛选器的站点，在站点的配置主页，选择“IIS”分组中的“ISAPI筛选器”。然后，在“ISAPI筛选器”的配置页面中右边的“操作”栏中点“添加…”；选择要配置的筛选器的DLL文件，填写相关的配置信息，然后确认添加。

 (需要非常注意的一点是：你需要非常注意你的IIS的应用程序池帐户是否有对于ISAPI所在路径及ISAPI所要使用到的资源的各种权限。)

五、调试ISAPI  

1、       调试操作步骤 

        因为ISAPI是一个dll文件，而且ISAPI是由IIS应用程序池进程调用的。

        在IIS6及IIS7的应用程序池的进程名称都是w3wp.exe；我们需要在单个应用程序池的机子上部署环境进行调试。避免调试时，多个应用程序池的一样的w3wp.exe进程名称，导至不必要的调试麻烦。以下是进行ISAPI进行调试的操作步骤（ISAPI扩展和ISAPI 筛选器的调试方式一样）：

步骤1 ：根据isapi的应用设置设置好要测试的isapi的dll；

步骤2 ：在浏览器的地址栏中输入配置测试isapi dll的站点的URL，然后过行一次访问，以便站点响应处理进程加载isapi dll文件。（如果是URL的方式访问isapi扩展的话，就要输入完整的isapi扩展dll访问的url）；

步骤 3 ：打开要测试的ISAPI的dll项目；

步骤 4 ：选择主菜单的“工具”菜单下的“附加到进程…”的菜单项，弹出“附加到进程”对话框；

步骤 5 ：选择“附加到进程”对话框下边的“显示所有会话中的进程”复选框，然后按“刷新”按刷；

步骤 6 ： 在“可用进程”的列表中选择进程为：w3wp.exe的进程，最后按“附加”，将w3wp.exe进程附加到项目调试中；

步骤 7 ：然要测试的ISAPI dll的函数HttpExtensionProc（或HttpFilterProc）内打上断点，再次刷新刚才在浏览器地址栏中输入的URL地址；这时程序就会停在打上断点的地方。

 

2、不能调试的可能情况：

a)         如果所编写的ISAPI中出现异常错误；可能直接导致应用程序停止进行。

b)         导出函数不是按原来的函数名导出，可能是编译的时候被VC++编译器改变函数名了。

c)         导出函数没有被正常导出。可以使用查看的dll导出函数工具进行查看导出的函数。

         ……