Deploy as Microsoft IIS module

FIRST DRAFT

This is a step by step instruction for the deployment of an ISAPI DLL on Microsoft IIS Server. It is applicable and tested with IIS version 7.5 and 8.5.

• Install IIS
  • Open Server Manager - Server Roles - Add Server Role - Web Server (IIS) - Select Role Service at least "ISAPI Extensions" and "ISAPI Filters"
  • See also: https://www.iis.net/learn/install/installing-iis-85/installing-iis-85-on-windows-server-2012-r2 and https://www.iis.net/learn/install/installing-iis-7/installing-iis-7-and-above-on-windows-server-2008-or-windows-server-2008-r2
• Open the IIS Manager
• Create a new web site or use the "Default Web Site"
• Copy your ISAPI DLL to a folder on the web server (e.g. "C:\Inetpub\DMVC_ISAPI")
• Create an application pool
  • Select "Application Pool" node on the left
  • Click "Add Application Pool ..."
  • Type in a name e.g. "my_domain_dmvc_isapi"
  • Set ".Net Framework version" to "No Managed Code"
  • Click OK
  • Right click on the created application pool "Advanced Settings..."
  • If you have a 64 Bit IIS/Windows and a 32 Bit ISAPI DLL you have to "Enable 32-Bit Applications"
• Add an application to your site
  • Select your web site node on the left (e.g. "Default Web Site")
  • Right click -> "Add Application..."
  • Type in an "Alias" (e.g. "api"); This is the url path to your ISAPI. e.g. "http://www.mydomain.com/api"
  • Select previously created application pool "my_domain_dmvc_isapi"
  • Select the physical path to your ISAPI DLL (e.g. "C:\Inetpub\DMVC_ISAPI")
• Allow dll execution on your web site.
  • Select the previously created application node ("api")
  • Double click "Handler Mappings"
  • Click "Edit Feature Permissions"
  • Enable "Execute" check box.
• Allow your specific dll on IIS.
  • Select the "Server" node
  • Double click "ISAPI and CGI Restrictions"
  • Click "Add..."
  • Select your dll from "C:\Inetpub\DMVC_ISAPI" and check "Allow extension path to execute"
• Set Authentication.
  • Select the application node ("api")
  • Double click "Authentication"
  • Right click "Anonymous Authentication"
  • Click "edit"
  • Check "Application pool identity"
• Set write permissions to IUSR
  • The DMVC Server create and write log files in a sub directory of the ISAPI DLL. The directory is named like the dll file + '.log' (e.G. "C:\Inetpub\DMVC_ISAPI\MyISAPI.log")
  • To enable the IIS respectively the application pool to write to the directory you have to grant the user IUSR write access to the dll directory.
  • See also: https://www.iis.net/learn/get-started/planning-for-security/understanding-built-in-user-and-group-accounts-in-iis

Now you can call your ISAPI DLL by entering the following url: http://www.mydomain.com/api/MyISAPI.dll/controller/methode/params

Debugging

This steps describe how to debug an ISAPI DLL within the IIS:

• First check if you have done all the steps above.
• The IIS debug mode always takes the first application pool in the IIS. This means your ISAPI DLL must use the first application pool.
• If You want to debug your dll as 32 Bit and 64 Bit version you have to change the Bit depth of the first application pool according to the Bit depth of your current debug session.
• Start Delphi as "Administrator"
• Open the project options and add w3wp.exe as host application "C:\Windows\SysWOW64\inetsrv\w3wp.exe" (32 Bit) or "C:\Windows\System32\inetsrv\w3wp.exe" (64 Bit).
• Add the start parameter "-debug".
• Shutdown the IIS service.
• Press F9 (run) in your Delphi project. A console window opens and you can use a client (WebBrowser) to call an url. After calling your dll the first time you will get all Delphi breakpoints active because now your dll is loaded.
• Shut down the IIS be pressing "Q" in the console window.

Tips and Tricks

If you have problems to get your ISAPI DLL running than you can try one of the next points to get it running:

• First check if you have done all the steps above.
• Is your dll 32 or 64 Bit? Check application pool settings.
• Did You install all necessary dependencies? (Database client library, OpenSSL or other third party components) You can check the Delphi event log which dll's are loaded.
• Did the necessary dependencies has the correct Bit depth?
• Try to change the application pool identity to "LocalSystem" (advanced settings). With this identity your ISAPI DLL acts as administrator with full access to "everything". If your dll works now you have a permission problem. Check if you write something to a file or if you call external dependencies which needs a higher access level.
• Check the Windows event log.
• Do you use "ExtractFilePath(Application.ExeName)" to get the path of the dll? An ISAPI is a DLL which needs a host application. Application.ExeName of an ISAPI DLL is w3wp.exe. ExtractFilePath is Windows System directory where w3wp.exe is located.
• Recommendation: If you are planning to deploy your server as ISAPI please develop an ISAPI from the beginning. Deploy as an ISAPI and Debug within the IIS from the first line of code you write. Sure it is possible to convert an "exe - Server" to an ISAPI but an ISAPI behaves differently.