FastCGI <fastCgi>

Overview
Compatibility
Setup
How To
Configuration
Sample Code

Overview

The <fastCgi> element allows you to add application pool support for FastCGI applications. Internet Information Services (IIS) 7.0 includes the FastCGI component, which allows you to run to run the PHP application framework, as well as other Web application frameworks, with greater reliability and better performance on IIS 7.0.

The <fastCgi> element contains a collection of <application> elements, each of which creates a FastCGI application pool definition. The simplest configuration requires that you must include the fullPath attribute in the <application> element to define the binaries to use for the specific application framework. For the PHP framework, set the fullPath attribute to the directory and file name of the PHP binaries.

Other attributes are optional and allow you to configure a number of other parameters, including the maximum number of requests a FastCGI worker process can process before it is recycled, the maximum number of worker processes for an application pool, and the maximum amount of time a FastCGI request can take.

Note: In order to process requests by using FastCGI, you must first map the path and the specific file name extensions to the FastCGI module and specify the target FastCGI process as the script processor.

Compatibility

	IIS 7.0	IIS 6.0
Notes	The `<fastCgi>` element is new in IIS 7.0.	N/A

Setup

To use the FastCGI environment, you must first install the CGI role service. The installation process registers the Common Gateway Interface (CGI) role service in both the <globalModules> and <modules> element. You do not need to perform any other steps to install the FastCGI environment.

Windows Server 2008

On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
On the Select Role Services page of the Add Role Services Wizard, select CGI, and then click Next.

Close
On the Confirm Installation Selections page, click Install.
On the Results page, click Close.

Windows Vista

On the taskbar, click Start, and then click Control Panel.
In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
Expand Internet Information Services, then select CGI, and then click OK.

Close

How To

Note: Some of the steps in this section may require that you install the Microsoft Administration Pack for IIS 7.0, which includes a user interface for FastCGI settings. To install the Microsoft Administration Pack for IIS 7.0, see the following URL:

http://learn.iis.net/page.aspx/415/

How to create a global FastCGI handler mapping for PHP

Note: For the steps in this section to work, you must have already installed binaries that will execute the file path or file name extension that you specify. This example uses a PHP implementation available from www.php.net.

On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI handler mappings.
In the Home pane, double-click Handler Mappings.

Close
In the Actions pane, click Add Module Mapping...

Close
Enter the following information, and then click OK.
- Enter the file name extension in the Request path text box. For example, "*.php".
- Click FastCgiModule in the Module drop-down list.
- Enter the path to the scripting engine in the Executable box. For example, "C:\PHP\php-cgi.exe".
- Enter a unique name for the handler mapping in the Name box. For example, "PHP-FastCGI".
Close
If you are prompted to create a FastCGI application in the Add Module Mapping dialog box, click Yes.

Close

Note: This will automatically create a FastCGI application for the handler mapping that you just created. If you choose No, you can manually create a FastCGI application later.

How to create a FastCGI application for PHP

Note: Adding a FastCGI application does not automatically add a handler mapping. To do so, you would need to follow the steps in the How to create a FastCGI handler mapping for PHP section of this topic.

On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI settings.
In the Home pane, double-click FastCGI Settings.

Close
In the Actions pane, click Add Application...

Close
In the Add FastCGI Application dialog box, enter the following information:
- Enter the path to the scripting engine in the Full Path box. For example, "C:\PHP\php-cgi.exe".
- Enter the maximum number of requests for the FastCGI application.
  Note: For PHP, this number must be lower or equal to the maximum number of requests for PHP environment, which is configured by using the PHP_FCGI_MAX_REQUESTS environment variable.
Close
Click the ellipsis next to EnvironmentVariables to open the environment variables collection editor.
In the EnvironmentVariables Collection Editor dialog box, click Add.

Close
Enter the following information, and then click OK.
- Enter "PHP_FCGI_MAX_REQUESTS" for the Name.
- Enter "10000" for the Value.
Close
Click OK to close the Add FastCGI Application dialog box.

How add a FastCGI environment variable for PHP

On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI settings.
In the Home pane, double-click FastCGI Settings.

Close
Highlight the PHP application in the FastCGI Settings pane, then click Edit... in the Actions pane

Close
In the Edit FastCGI Application dialog box, click the ellipsis next to EnvironmentVariables to open the environment variables collection editor.

Close
In the EnvironmentVariables Collection Editor dialog box, click Add.

Close
Enter the following information, and then click OK.
- Enter "PHP_FCGI_MAX_REQUESTS" for the Name.
- Enter "10000" for the Value.
Close
Click OK to close the Add FastCGI Application dialog box.

Configuration

You can configure the <fastCgi> element at the server level in the ApplicationHost.config file or at the site level, at the application level, or at the directory level in a Web.config file.

Attributes

None.

Child Elements

Element	Description
`application`	Optional element. Adds a FastCGI process pool definition to the collection of FastCGI process pool definitions.

Configuration Sample

The following configuration sample adds an FastCGI application for PHP, sets the instanceMaxRequests attribute to "10000", and sets the PHP_FCGI_MAX_REQUESTS environment variable to "10000".

<fastCgi>
   <application fullPath="C:\PHP\php-cgi.exe"
         arguments=""
         maxInstances="4"
         idleTimeout="300"
         activityTimeout="30"
         requestTimeout="90"
         instanceMaxRequests="10000"
         protocol="NamedPipe"
         flushNamedPipe="false">
      <environmentVariables>
         <environmentVariable
            name="PHP_FCGI_MAX_REQUESTS"
            value="10000" />
      </environmentVariables>
   </application>
</fastCgi>

Note: For PHP, the value of the PHP_FCGI_MAX_REQUESTS environment variable must be lower or equal to the value specified by the instanceMaxRequests attribute of the FastCGI <application> element.

The following configuration sample adds a global FastCGI handler mapping for PHP files to IIS and specifies the full path to a FastCGI executable file.

<configuration>
   <location path="" overrideMode="Allow">
      <system.webServer>
         <handlers>
            <add name="PHP-FastCGI"
                path="*.php"
                verb="GET,HEAD,POST"
                modules="FastCgiModule"
                scriptProcessor="C:\PHP\php-cgi.exe"
                resourceType="Unspecified"
                requireAccess="Script" />
         </handlers>
      </system.webServer>
   </location>
</configuration>

Sample Code

The following code samples add an FastCGI application for PHP, set the instanceMaxRequests attribute to "10000", and set the PHP_FCGI_MAX_REQUESTS environment variable to "10000". Each sample also adds a global FastCGI handler mapping for PHP files to IIS and specifies the full path to a FastCGI executable file.

AppCmd.exe

appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='C:\PHP\php-cgi.exe',arguments='',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='10000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost

appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='C:\PHP\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']" /commit:apphost

appcmd.exe set config -section:system.webServer/handlers /+"[name='PHP-FastCGI',path='*.php',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='C:\PHP\php-cgi.exe',resourceType='Unspecified',requireAccess='Script']" /commit:apphost

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();

         ConfigurationSection fastCgiSection = config.GetSection("system.webServer/fastCgi");
         ConfigurationElementCollection fastCgiCollection = fastCgiSection.GetCollection();
         ConfigurationElement applicationElement = fastCgiCollection.CreateElement("application");
         applicationElement["fullPath"] = @"C:\PHP\php-cgi.exe";
         applicationElement["arguments"] = @"";
         applicationElement["maxInstances"] = 4;
         applicationElement["idleTimeout"] = 300;
         applicationElement["activityTimeout"] = 30;
         applicationElement["requestTimeout"] = 90;
         applicationElement["instanceMaxRequests"] = 10000;
         applicationElement["protocol"] = @"NamedPipe";
         applicationElement["flushNamedPipe"] = false;

         ConfigurationElementCollection environmentVariablesCollection = applicationElement.GetCollection("environmentVariables");
         ConfigurationElement environmentVariableElement = environmentVariablesCollection.CreateElement("environmentVariable");
         environmentVariableElement["name"] = @"PHP_FCGI_MAX_REQUESTS";
         environmentVariableElement["value"] = @"10000";
         environmentVariablesCollection.Add(environmentVariableElement);
         fastCgiCollection.Add(applicationElement);

         ConfigurationSection handlersSection = config.GetSection("system.webServer/handlers");
         ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();
         ConfigurationElement addElement = handlersCollection.CreateElement("add");
         addElement["name"] = @"PHP-FastCGI";
         addElement["path"] = @"*.php";
         addElement["verb"] = @"GET,HEAD,POST";
         addElement["modules"] = @"FastCgiModule";
         addElement["scriptProcessor"] = @"C:\PHP\php-cgi.exe";
         addElement["resourceType"] = @"Unspecified";
         addElement["requireAccess"] = @"Script";
         handlersCollection.AddAt(0, addElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample

   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration

      Dim fastCgiSection As ConfigurationSection = config.GetSection("system.webServer/fastCgi")
      Dim fastCgiCollection As ConfigurationElementCollection = fastCgiSection.GetCollection
      Dim applicationElement As ConfigurationElement = fastCgiCollection.CreateElement("application")
      applicationElement("fullPath") = "C:\PHP\php-cgi.exe"
      applicationElement("arguments") = ""
      applicationElement("maxInstances") = 4
      applicationElement("idleTimeout") = 300
      applicationElement("activityTimeout") = 30
      applicationElement("requestTimeout") = 90
      applicationElement("instanceMaxRequests") = 10000
      applicationElement("protocol") = "NamedPipe"
      applicationElement("flushNamedPipe") = False

      Dim environmentVariablesCollection As ConfigurationElementCollection = applicationElement.GetCollection("environmentVariables")
      Dim environmentVariableElement As ConfigurationElement = environmentVariablesCollection.CreateElement("environmentVariable")
      environmentVariableElement("name") = "PHP_FCGI_MAX_REQUESTS"
      environmentVariableElement("value") = "10000"
      environmentVariablesCollection.Add(environmentVariableElement)
      fastCgiCollection.Add(applicationElement)

      Dim handlersSection As ConfigurationSection = config.GetSection("system.webServer/handlers")
      Dim handlersCollection As ConfigurationElementCollection = handlersSection.GetCollection
      Dim addElement As ConfigurationElement = handlersCollection.CreateElement("add")
      addElement("name") = "PHP-FastCGI"
      addElement("path") = "*.php"
      addElement("verb") = "GET,HEAD,POST"
      addElement("modules") = "FastCgiModule"
      addElement("scriptProcessor") = "C:\PHP\php-cgi.exe"
      addElement("resourceType") = "Unspecified"
      addElement("requireAccess") = "Script"
      handlersCollection.AddAt(0, addElement)

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST");
var fastCgiCollection = fastCgiSection.Collection;
var applicationElement = fastCgiCollection.CreateNewElement("application");
applicationElement.Properties.Item("fullPath").Value = "C:\\PHP\\php-cgi.exe";
applicationElement.Properties.Item("arguments").Value = "";
applicationElement.Properties.Item("maxInstances").Value = 4;
applicationElement.Properties.Item("idleTimeout").Value = 300;
applicationElement.Properties.Item("activityTimeout").Value = 30;
applicationElement.Properties.Item("requestTimeout").Value = 90;
applicationElement.Properties.Item("instanceMaxRequests").Value = 10000;
applicationElement.Properties.Item("protocol").Value = "NamedPipe";
applicationElement.Properties.Item("queueLength").Value = 1000;
applicationElement.Properties.Item("flushNamedPipe").Value = false;
applicationElement.Properties.Item("rapidFailsPerMinute").Value = 10;

var environmentVariablesCollection = applicationElement.ChildElements.Item("environmentVariables").Collection;
var environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement.Properties.Item("name").Value = "PHP_FCGI_MAX_REQUESTS";
environmentVariableElement.Properties.Item("value").Value = "10000";
environmentVariablesCollection.AddElement(environmentVariableElement);
fastCgiCollection.AddElement(applicationElement);

var handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST");
var handlersCollection = handlersSection.Collection;
var addElement = handlersCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "PHP-FastCGI";
addElement.Properties.Item("path").Value = "*.php";
addElement.Properties.Item("verb").Value = "GET,HEAD,POST";
addElement.Properties.Item("modules").Value = "FastCgiModule";
addElement.Properties.Item("scriptProcessor").Value = "C:\\PHP\\php-cgi.exe";
addElement.Properties.Item("resourceType").Value = "Unspecified";
addElement.Properties.Item("requireAccess").Value = "Script";
handlersCollection.AddElement(addElement, 0);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST")
Set fastCgiCollection = fastCgiSection.Collection
Set applicationElement = fastCgiCollection.CreateNewElement("application")
applicationElement.Properties.Item("fullPath").Value = "C:\PHP\php-cgi.exe"
applicationElement.Properties.Item("arguments").Value = ""
applicationElement.Properties.Item("maxInstances").Value = 4
applicationElement.Properties.Item("idleTimeout").Value = 300
applicationElement.Properties.Item("activityTimeout").Value = 30
applicationElement.Properties.Item("requestTimeout").Value = 90
applicationElement.Properties.Item("instanceMaxRequests").Value = 10000
applicationElement.Properties.Item("protocol").Value = "NamedPipe"
applicationElement.Properties.Item("queueLength").Value = 1000
applicationElement.Properties.Item("flushNamedPipe").Value = false
applicationElement.Properties.Item("rapidFailsPerMinute").Value = 10

Set environmentVariablesCollection = applicationElement.ChildElements.Item("environmentVariables").Collection
Set environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable")
environmentVariableElement.Properties.Item("name").Value = "PHP_FCGI_MAX_REQUESTS"
environmentVariableElement.Properties.Item("value").Value = "10000"
environmentVariablesCollection.AddElement(environmentVariableElement)
Call fastCgiCollection.AddElement(applicationElement)

Set handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST")
Set handlersCollection = handlersSection.Collection
Set addElement = handlersCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "PHP-FastCGI"
addElement.Properties.Item("path").Value = "*.php"
addElement.Properties.Item("verb").Value = "GET,HEAD,POST"
addElement.Properties.Item("modules").Value = "FastCgiModule"
addElement.Properties.Item("scriptProcessor").Value = "C:\PHP\php-cgi.exe"
addElement.Properties.Item("resourceType").Value = "Unspecified"
addElement.Properties.Item("requireAccess").Value = "Script"
Call handlersCollection.AddElement(addElement, 0)

adminManager.CommitChanges()

Configuration Settings

advertise here