ISAPI Deployment

Last Updated: 9/22/2008

Sections above here:
Home » Deployment

Sections below here:

Topics in this section:
Deployment Overview
External Files
Permissions
ISAPI Deployment
ISAPI Notes
ISAPI Utilities
ISAPI Hosting
ISAPI Common Issues
Standalone Deployment
Apache
Service Deployment
Launching Applications
Converting between application types
Application Ports

Deploying in IIS

Although an IW ISAPI application is the same as a standard ISAPI application, the steps to deploy an IW ISAPI will be explained step by step. However, due to the number of existing servers that support ISAPI's, this section is restricted to deployment on Microsoft's Internet Information Server. This is one of the most common servers to deploy ISAPI's on.

Before deploying the application, the first step is to configure IIS to allow ISAPI's to run. In IIS 5.0 which is the version included in Windows 2000 and Windows XP, the first step is to create the website and under this one create a virtual folder that has execute permissions to run ISAPI applications. IMPORTANT: Please see note at the end of the page regarding IIS version 6.

Once the website is created (or on an existing website), right click with the mouse button and choose New -> Virtual Directory

Click Next on the Wizard Introduction screen. The next step is to select an alias for this virtual directory. Normally, the standard is to use "scripts", however whatever alias desired can be used. This defines how the application will be called via the URL:

http://xxx.xxxx.xxx.xxx/{alias}/xxxxxxxxxx

The next step is to choose the actual physical directory where the files are going to reside and where the alias defined in the previous step will point to. Again, by default this would be something like c:\inetpub\scripts. This of course depends on where IIS was installed and where the directory for the current website resides.

The last step is to choose what permissions the virtual directory is going to have. Normally, it is not a good idea to mix directories that have executables with directories that have files to be accessed for reading/writing. Actually, it is not recommendable to have any directories with write-access via IIS. In this case, the best option is to remove all permissions except the Execute (such as ISAPI applications or CGI).

These are the steps required to configure IIS to run ISAPI's. However, before being able to run the application, there are a few more issues required. If the system is using NTFS, it is necessary to make sure that the physical directory that was entered in step 2 of the wizard and where the virtual alias points to, has execute permissions. Permissions for IIS are based on two factors, the ones assigned in IIS itself and those of the underlying file system, prevailing the latter over the former. Of course, if running FAT (highly an-recommended) there are no file level permissions.

The last step remaining is to copy the ISAPI into the appropriate physical directory that was setup, make sure that the ISAPI has execute permissions and copy any necessary files (such as Files and Templates folders) under the physical directory.

Once all these steps have been accomplished the application can be called using the URL:

http://xxx.xxx.xxx.xxx/{alias}/{application_name.dll}/{start_command}

Optionally if a different port than the default 80 has been configured in IIS, this value will need to be appended to the URL.

Example:

If the application runs on default of IIS, the URL will look like this:

http://yourwebserver/virtualdirectory/YourDLLName/start

If you have setup your application to use a port the URL would look like:

http://yourwebserver:port/virtualdirectory/YourDLLName/start

There is an important issue to remember when deploying ISAPI's under IIS (or for that matter under any other ISAPI compliant server), and that is that the ISAPI runs under certain security restrictions. In particular it runs under the context of a specific user, which in the case of IIS is IUSR_MACHINENAME, where MACHINENAME is substituted with the name of the server. This user has very restrictive security permissions and this has to be taken into consideration when certain calls require a higher level of security (such as communicating with COM objects, connecting to certain databases that require file access, etc).

As with any other ISAPI application, IW ISAPI's are DLLs and as such remain in memory after the first call. IIS allows them to be unloaded by configuring an application "area". To do this, right-click on the newly created virtual directory (in the figure below this is named scripts) and click on properties.

Once the property screen appears, click on the Virtual Directory tab to gain access to the Application Settings.

Enter a value for the Application Name (such as Scripts or IW Applications) and click on the Create button. Set the Application Level to the required isolation. Normally Medium (Pooled) is sufficient. For more information on isolation levels, consult the online help for IIS. When the application is accessed, the Unload button will be enabled and by accessing the properties and clicking on the Unload button, ALL ISAPI's located under the virtual directory will be removed from memory. Therefore, this only needs to be done ONCE per virtual directory.

Note: IIS 6 has increased security by default. To enable ISAPI's to run, you need to click on the new entry "Web Service Extensions" in MMC and on the "All Unknown ISAPI extensions" change the status from "Prohibited".