Web Connection 5.0 is ready for operation under Windows Vista and Windows Longhorn Server and when installed will automatically configure itself for operation under these OSs. There are also tools that provide configuration for new projects and existing installations.

Windows Components required for IIS

In order to get Web Connection to run the Web server on Vista needs to be explicitly installed and correctly configured as IIS on Vista is installed with very limited feature functionality.

Note:
It's crucially important that you have these components installed before you start installing Web Connection!

Here are the required components for Web Connection:

The figure above highlights the critical components that are used by Web Connection and are absolutely required. THere are a few additional checks in the above that will be useful in the future which is ASP.NET and .NET Extensibility.

The most important settings are:

• IIS Metabase and IIS 6 Configuration compatibility
  
• ISAPI Extensions Support
  

The ISAPI extension support enables the Web Connection ISAPI extension to run - without this setting nothing will work. IIS Metabase support ensures that the COM based configuration of the Web Server can be performed through the Web Connection Management Console for the New Project and Server Configuration Wizards.

I'd also recommend installing ASP.NET support as there will be more integration between ASP.NET and Web Connection in future versions.

Automatic Configuration

Once the base components have been installed you can use Web Connection's automatic configuration to install Web Connection, run the New Project Wizard to create new projects or run the Server Configuration Wizard to configure an existing site.

In all cases you should use the IIS 7 server setting from the server type drop down.

From there forward all the configuration options will work as any other of the Wizards for virtual directory configuration etc. This should be the easiest way to configure a Web application quickly as all of these mechanisms allow creationg of a virtual directory, configuring script maps and adding the Web Connection ISAPI extension into the allow application server application list.

Programmatic Tools

In addition to the fully automatic configuration tools you can also use programmatic tools to create a virtual and script maps. You can also use these programmatic tools:

Create Virtuals:

*** Using the Console - last parameter is the IIS Admin path under which virtual is created
DO Console WITH "Virtual", "WebDemo","c:\westwind\webdemo",.F.,"IIS7","IIS://localhost/W3SVC/1/ROOT"

*** Interactive
DO Console WITH "Virtual","UI"

Create Scriptmaps:

*** Using the Console
DO Console WITH "ScriptMap", ".wxx","c:\westwind\webdemo\bin\wc.dll",.F.,"IIS7","IIS://localhost/W3SVC/1/ROOT/WebDemo"

*** Interactive
DO Console WITH "ScriptMap", "UI"

Note scriptmap creation will also register the ISAPI extension with the ISAPI restriction list.

Manual Configuration

If you think you don't want any stinking tools configure your application for you, or you really want to understand what settings are required to run your application, the following topics below take you through manual configuration for each of the configuration settings.

Create an Application Pool

Any virtual directory in IIS is hosted in what is known as an Application Pool. An Application pool is the host process for one or more Web applications (or virtual directories) and you can typically see this process running as w3wp.exe on your machine. There maybe multiple of these processes - one for each active Application Pool. Application Pools allow physical separation of one or more applications from another.

Although a separate Web Connection Application Pool is not required it is recommended. The main reason is that Web Connection should be run in the System security context rather than the default Network Service security context and this setting is configured at the Application Pool level. This setting isn't required but if you don't run in System Context additional configuration may be required to ensure that Network Serivce (or whatever account you choose) has rights in several locations (Temp File directory, DCOM permissions for COM operation etc.).

To create an Application Pool in IIS 7:

• Go to the Application Pools section in the Connections Tree
  
• Right click and select Add Application Pool
  
• Create with the name of your choice (West Wind Web Connection)
  
• Choose .NET Framework 2.0 and Integrated Pipeline Mode
  

Once you've created the Application Pool select it in the list and click on Advanced Settings. In the property sheet that appears set the Identity for the Application Pool to LocalSystem.

You can also configure various other settings such as the process recycling, idle timeout and various other flags. Note that if you are running on a 64 Bit machine you should also set the Enable 32 Bit applications flag to True to enable the Web Connection ISAPI DLL which is a 32 bit application.

Virtual Directory Configuration

In order to run a Web Connection application you will need to create a virtual directory. The virtual can be configured in the IIS Servies Manager. To create a new virtual directory:

• In the Connections tree go to YourMachine | WebSites | YourWebSite and click Add Application
  
• Enter the name of the virtual directory (WebDemo) and the path to the Web directory
  
• Select the West Wind Web Connection Application Pool if it exists
  

Once the virtual has been created select the Authentication option in the virtual's configuration.

Enable:

• Anonymous Authentication
  
• Basic Authentication
  
• Windows Authentication
  

Setting the ISAPI Restrictions for each copy of wc.dll

Due to the security settings in IIS 6 and 7 generic ISAPI and CGI extensions (and ASP and ASP.NET even) are not allowed to execute. Without this setting any direct access or access through scriptmaps (MyPage.wcsx) to the dll will generate a 404.1 (File not found) error.

The extension needs to be explicitly enabled:

• Go to the Machine Root in the Connections tree
  
• Select ISAPI and CGI Restrictions (IIS Settings)
  
• Click and add your mapping to wc.dll in your Web path
  

Changed behavior: BIN/wc.dll execution is not allowed

IIS 7 does not allow direct URL access to any code in a BIN directory. For Web Connection this means that URLs that point at something like this:

http://www.west-wind.com/wconnect/bin/wc.dll?wwDemo~TestPage

are not allowed. This can be a problem for backwards compatibility if you use the bin path directly.

There are relatively easy workarounds for this problem:

• Move wc.dll
  You can move wc.dll to a different directory and fix all of your links to point at the new location of wc.dll. Although this works I wouldn't recommend this approach.

• Use Scriptmaps
  Effectively there's no need to EVER call wc.dll directly. Instead it's best to use a scriptmap that points to wc.dll instead. Web Connection always expects and installs the .wc extension so any URL to wc.dll can be easily rewritten using wc.wc?wwDemo~TestPage for example.
  

Creating Script Mappings

You'll also want to configure various script maps for your Web Connection application and you do this by creating mappings between certain extensions (like .wc, .wcsx, or .yourmap) to the ISAPI wc.dll extension. This allows you to serve pages like MyRequest.wc which automatically can route to a MyRequest process method in Web Connection.

Script maps can be configured in the service manager as follows:

• Go to the Connections Tree and find your Virtual Directory created earlier
  
• Select Handler Mappings
  
• Enter your extension as *.wp where wp is the extension
  
• Enter the path to the Web Connection wc.dll
  
• Click on Request Restrictions
  
• Uncheck Invoke handler only if file exists
  
• Select Allow All Verbs (or GET/POST at minimum) on the Verbs page
  

Web.Config Configuration

Note that all Virtual directory specific configuration settings are written to the web.config file in the Web application's Web root path by IIS, and you can also make setting changes in this configuration file.

Here's what a Web.config for the WebDemo project looks like:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
... omitted
    <system.webServer>
        <handlers>
            <add name="WebDemo-wcsx" path="*.wcsx" verb="GET,POST" modules="IsapiModule" scriptProcessor="c:\westwind\webdemo\bin\wc.dll" resourceType="Unspecified" requireAccess="Script" responseBufferLimit="0" />
            <add name="WebDemo-wp" path="*.wp" verb="GET,POST" modules="IsapiModule" scriptProcessor="c:\westwind\webdemo\bin\wc.dll" resourceType="Unspecified" requireAccess="Script" responseBufferLimit="0" />
            <add name="WebDemo-wc" path="*.wc" verb="GET,POST" modules="IsapiModule" scriptProcessor="c:\westwind\webdemo\bin\wc.dll" resourceType="Unspecified" requireAccess="Script" responseBufferLimit="0" />
            <add name="WebDemo-wwsoap" path="*.wwsoap" verb="GET,POST" modules="IsapiModule" scriptProcessor="c:\westwind\webdemo\bin\wc.dll" resourceType="Unspecified" requireAccess="Script" responseBufferLimit="0" />
        </handlers>
    </system.webServer>
</configuration>

This can be especially useful for copying script map entries if you need to service a bunch of different script map extensions and it's much quicker to cut and paste these entries than adding them individually in the Service Manager.