Project

General

Profile

ISAPI on Microsoft IIS » History » Version 9

Wim Dumon, 08/09/2010 03:40 PM

1 1 Wim Dumon
h1. ISAPI on Microsoft IIS
2
3
This page is work in progress. The ISAPI interface is not yet fully released - it will be in the upcoming Wt 3.1.4.
4
5
From Wt 3.1.4 onward, Wt is delivered with an ISAPI connector for easy integration with Microsoft IIS. ISAPI was preferred above FCGI on Windows because existing FCGI implementations (client libraries and servers) turned out to result in suboptimal solutions. Note that Wt does not support FCGI on Windows.
6
7 2 Wim Dumon
Wt beautifully integrates with IIS's asynchronous architecture, and even specialized features such as server push, the internal path API, ... work perfectly scalable with IIS. The Wt ISAPI connector is fully asynchronous, and therefore causes no scalability problems for IIS's internal architecture.
8 1 Wim Dumon
9
h2. Using the connector
10
11 3 Wim Dumon
h3. Building the connector
12 2 Wim Dumon
13
When configuring Wt with CMake, set @CONNECTOR_ISAPI@ to true. If you want to compile all examples with the ISAPI connector, set @EXAMPLES_CONNECTOR@ to @wtisapi@.
14
15 1 Wim Dumon
h3. Building the application - General
16
17
To use the connector, the following steps are required:
18
* Configure to build a DLL
19
* Link to @wtisapi.lib@, in addition to @wt.lib@ and other Wt libraries such as dbo.
20
* Export the ISAPI symbols (HttpExtensionProc, GetExtensionVersion, TerminateExtension) through a .def file or linker options
21
* Write a @main()@ function just like you would in a normal Wt application. The connector will invoke @main()@ and @argv[0]@ contains the path of the DLL.
22
* Optionally, write a @DllMain()@ function
23
24
The source code needs no changes to use the ISAPI connector.
25
26
h3. Using CMake to build your application
27
28
We suggest the use of the following CMake function to quickly switch between the httpd and the isapi connector.
29
<pre>
30
FUNCTION(WT_ADD_APPLICATION name)
31
  IF(${WT_CONNECTOR} STREQUAL "wtisapi")
32
    LIST(INSERT ARGV 1 "SHARED")
33
    ADD_LIBRARY(${ARGV})
34
    SET_TARGET_PROPERTIES(${name}
35
      PROPERTIES
36
        LINK_FLAGS
37
         "/EXPORT:HttpExtensionProc /EXPORT:GetExtensionVersion /EXPORT:TerminateExtension"
38
    )
39
  ELSE(${WT_CONNECTOR} STREQUAL "wtisapi")
40
    ADD_EXECUTABLE(${ARGV})
41
  ENDIF(${WT_CONNECTOR} STREQUAL "wtisapi")
42
  TARGET_LINK_LIBRARIES(${name} wt ${WT_CONNECTOR})
43
ENDFUNCTION(WT_ADD_APPLICATION)
44
</pre>
45
46
Wt applications can then be defined as follows:
47
<pre>
48
SET(WT_CONNECTOR
49
#  "wthttp" # uncomment if you want to use the standalone connector instead
50
  "wtisapi"
51
)
52
WT_ADD_APPLICATION(MyApp src1.C src2.C src3.C)
53
</pre>
54
55 4 Wim Dumon
An alternative approach is to always build both the http and isapi versions of your application:
56
<pre>
57
ADD_LIBRARY(MyAppAsLib STATIC src1.C src2.C src3.C)
58
59
ADD_LIBRARY(MyAppIsapi SHARED main.C MyApp.def) # Using a .def file for exported symbols instead of linker options
60
TARGET_LINK_LIBRARIES(MyAppIsapi wt wtisapi MyAppAsLib)
61
62
ADD_EXECUTABLE(MyAppHttp main.C) # Could we build apps without a single .C file?
63
TARGET_LINK_LIBRARIES(MyAppHttp wt wthttp MyAppAsLib)
64
</pre>
65
66 1 Wim Dumon
h3. Debugging your WtIsapi program
67
68
Generally, it is recommended to debug your Wt application using the http connector. This is very natural (just run it in MSVC) and easy to interact with. Your development cycle will be shorter than when you take IIS in the picture. Remember, it is easy to switch between the http and isapi connector: just link to a different library.
69
70
For some problems, you may need to debug your application in the same way as it is deployed in IIS. A google search will yield many options to debug an ISAPI application. In essence, the easiest way to debug an ISAPI extension is to attach your debugger to a running process (MSVC: Debug->Attach to process. Note that this feature is available in MSVC Express Editions version 2005 and 2008, but was removed from the 2010 version).
71
72
The big question is of course: what process should I attach to? This depends on your IIS version and deployment configuration. You can look this up in the manual of your IIS, and still gamble between processes with identical names, or you could let your application tell you what the correct process ID is. I particularly liked the following code snippet for this purpose:
73
<pre>
74
  std::stringstream ss;
75
  ss << "Please attach a debugger to the process " << GetCurrentProcessId() << " and click OK" << std::endl;
76
  MessageBox(NULL, ss.str().c_str(), "Wt/ISAPI Debug Time!", MB_OK|MB_SERVICE_NOTIFICATION);
77
</pre>
78
You can add this to your @main()@ function, but if it is added to @GetExtensionVersion()@ in @src/isapi/Isapi.C@ (you'll have to recompile Wt then), this even waits for you to connect at the moment that your DLL is first loaded.
79
80
On Vista and Windows 7, this will send the message to the event log rather than a dialog on the screen. You may have more success using @WTSSendMessage()@ on those systems.
81
82
h2. Architecture overview
83
84
IIS expects a DLL to run the web application, whereas Wt's other connectors (httpd, fcgi) result in an executable. This means that there are a few important points to take into account when using this connector (e.g. build a DLL instead of an EXE). On the other hand, we made sure that the connectors can still be interchanged, meaning that you're not required to make any changes to your Wt application in order to use the new connector.
85
86
In Wt's architecture, the connector is a library that is separate from the rest of the system. The same is true for ISAPI: the connector library is @wtisapi.lib@. This is a static library which provides the entry functions for ISAPI (@GetExtensionVersion()@, @TerminateExtension()@, @HttpExtensionProc()@). IIS will search for these functions in your DLL so you must make sure that your DLL exports them. That is also one of the reasons why wtisapi is only available as a static library: the symbols must be embedded in your DLL.
87
88
Upon initialization, IIS calls @GetExtensionVersion()@. The connector starts a thread, which invokes the @main()@ function of your Wt application. During this invocation, argc will be 1 and argv[0] contains the path of the ISAPI DLL. This thread keeps running until the server is terminated and main() returns. 
89
When IIS is shut down, IIS calls @TerminateExtention()@ and the Wt server will be terminated. This means that all applications will be properly destroyed when IIS shuts down in a normal way.
90
91 5 Wim Dumon
The Wt ISAPI application runs inside a server process. Whereas it is unimportant whether the extension runs inside the servers process or in a separate process, it is important to ensure that all HTTP requests for a single application will be served by the same process. It is therefore mandatory to properly configure IIS6/7 to avoid the use of a so-called Web Garden for the Wt application. If you do use a Web Garden, requests will end up in processes that did not initiate the session, causing failing (restarting) web applications. This is not a problem, as a stable Wt application has no benefit from a web garden. If you want a Wt application to benefit from multi-core servers, modify the number of worker threads, which is by default 10 (FIXME: configuration file not yet implemented).
92 1 Wim Dumon
93
IIS does not foresee a method to unload an ISAPI extension: once loaded, it is loaded until the server shuts down.
94
95 2 Wim Dumon
h2. Configuring Microsoft Internet Information Services
96 1 Wim Dumon
97 9 Wim Dumon
General remarks:
98
* As an ISAPI extension is loaded inside the IIS process, it is impossible to specify the CWD (current work directory) of your application. Make sure that all files you access from within your application use absolute paths (e.g. by using WApplication::approot() consistently throughout your application) if you want to deploy them as ISAPI applications.
99
* The IIS runs with other privileges than normal user. This means that it may be impossible for IIS to access certain files on your system. Especially those examples requiring access to SQLite databases in Wt will not be able to create/modify a database unless you modify the access rights to the example's directory.
100
101 7 Wim Dumon
102 1 Wim Dumon
h3. IIS 7.5 (Windows 7)
103 7 Wim Dumon
104
h4. Configuring the Application Pool
105
106
While the default configuration of application pools on IIS 7.5 is pretty decent for Wt, we recommend to make a few changes (select your application pool, right-click on it, and select 'Advanced Settings...'). Verify the following settings (in order of importance):
107
* Set 'Maximum Worker Processes' (maxProcesses) to 1 (=default). This is mandatory for Wt.
108
* Set 'Regular Time Interval (minutes)' (time) to 0. By default, this is not set to 0, so your Wt application will be killed and restarted every so often.
109
* Also set 'Private Memory Limit (KB)' (privateMemory), 'Request Limit' (requests) and 'Virtual Memory Limit (KB)' (memory) to 0 (the default). If not, you risk that your Wt application will be killed from time to time.
110
* Consider to set 'Disable Overlapped Recycle' (disallowOverlappingRotation) to true (default is false). This depends on your application: if it does not mind being started before an older instance exits, you can keep this to false.
111
* Set all 'Generate Recycle Event Log Entry' to true to ease debugging.
112
113
h4. Running the examples
114
115
Wt examples are best executed from within their source directory. Therefore, we recommend to copy the .dll files to the source example folders after building. Using cygwin, you can do this with this command, executed from within the build directory:
116
<pre>
117
for i in `find . -name \*dll`; do cp $i ../wt/`echo $i | sed s/Debug//`; done
118
</pre>
119
120
Most examples require files from the 'resources' directory to run correctly. Simply copy the @wt-x.y.z/resources@ folder to every example directory. You can do this with many mouse clicks, or with a single line in a cygwin shell:
121
<pre>
122
for i in `find examples -type d`; do cp -r resources $i; done
123
</pre>
124
125
Some examples need extra dependencies: ExtJS (widgetgallery, extkitchen) and tinyMCE (widgetgallery). These are not delivered with Wt; download them from the appropriate place and have a look in the FAQ on this wiki.
126
127
Next, add a virtual directory to your server that points to all the examples. In the Internet Information Services Manager, right-click on your web site (e.g. Default Web Site), select 'Add Virtual Directory', choose an alias (e.g. examples), and point the 'Physical Path' to the wt examples source directory (wt-x.y.z/examples).
128
129
It is easier to browse through the examples if you enable directory browsing: click on your virtual folder ('examples'), double-click the 'Directory Browsing' icon, and click 'Enable' in the right column.
130
131
Now you can browse the examples folder (surf to http://localhost/examples), but you will get a 404.2 error when you click a DLL. Every ISAPI DLL must be explicitly granted execute permissions in IIS. Click on your IIS machine (toplevel icon in the tree on the left), double-click the 'ISAPI and CGI Restrictions' icon. A cautious system administrator adds every single DLL to this list, but a brave (or lazy) one clicks 'Edit Feature Settings...' in the right column and selects 'Allow Unspecified ISAPI Modules'.
132 1 Wim Dumon
133
h3. IIS 7 (Vista)
134
135
h3. IIS 5.1 (Windows XP)
136
137 8 Wim Dumon
h4. Configuring the Application Pool
138
139
IIS 5.1 does not have application pools like the newer versions. But you can define an 'Application Protection' level, which can be set to one of three choices:
140
* Low - IIS Process: Select this if you want your Wt application to run in the same address space (application) as IIS. This is the fastest choice, but if your application crashes, it will take the IIS server down with it. IIS will restart automatically when this happens.
141
* Medium - Pooled: Select this if you want all ISAPI extensions (including your Wt applications) to run in a child process of IIS. Any crashing ISAPI extension will cause all other ISAPI extensions to terminate as well. The cost of this setting is that the HTTP traffic needs to be transfered to the child application by means of an IPC mechanism.
142
* High - Isolated: With this option, every ISAPI extension runs in its own process. A crash in one ISAPI extension does not affect the other extensions. The extra overhead compared to the 'Pooled' setting is that you need slightly more memory.
143
144
A Wt ISAPI extension will run correctly with any of the three settings. We recommend to use the 'High' setting until you have thoroughly tested your application.
145
146
h4. Running the examples
147
148
This is similar to the description above for IIS 7.5: copy the DLLs from the build directory to the examples src directory, create a virtual directory that points to the examples directory, and allow execution of ISAPI. Make sure to enable the 'Execute' rights on the Virtual Directory when you create it (Right-click on 'Default Web Site', New -> Virtual Directory). As described for IIS 7.5, some examples require extra dependencies (ext, tinymce), which should be copied to the src directory or the examples will not work.
149
150
Allow 'Directory Browsing' in the virtual directory (right-click the virtual directory -> Properties -> Virtual Directory -> check Directory Browsing) to allow to browse through the examples.
151
152 1 Wim Dumon
h2. Compatibility with other web servers
153
154
The connector was not designed to work with other web servers. @wtisapi.lib@ will not work with Apache due to how Apache handles processes and threads.