Edit

Share via

Handlers <handlers>

  • Article

Overview

The <handlers> element defines the handlers registered for a specific file name extension or URL.

Handlers are Internet Information Services (IIS) components that are configured to process requests to specific content, typically to generate a response for the request resource. For example, an ASP.NET Web page is one type of handler. You can use handlers to process requests to any resource that needs to return information to users that is not a static file. IIS provides several different handler types to support static files, Common Gateway Interface (CGI) applications, FastCGI applications, and Internet Server API (ISAPI) extensions. ASP.NET also provides support for additional handler types through the HTTP handler interface.

Developers can create custom handlers to perform special handling that you can identify using file name extensions in your application. For example, if a developer created a handler that created RSS-formatted XML, you could bind the .rss file name extension in your application to the custom handler. Developers can also create handlers that map to a specific file and can implement these handlers as native modules or as implementations of the ASP.NET IHttpHandler interface.

Compatibility

Version Notes
IIS 10.0 The <handlers> element was not modified in IIS 10.0.
IIS 8.5 The <handlers> element was not modified in IIS 8.5.
IIS 8.0 The <handlers> element was not modified in IIS 8.0.
IIS 7.5 The <handlers> element was not modified in IIS 7.5.
IIS 7.0 The <handlers> element was introduced in IIS 7.0.
IIS 6.0 N/A

Setup

The <handlers> element is included in the default installation of IIS 7.

How To

How create a handler mapping for an ASP.NET handler in an IIS 7 application running in Integrated mode

  1. Open Internet Information Services (IIS) Manager:

    • If you are using Windows Server 2012 or Windows Server 2012 R2:

      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows 8 or Windows 8.1:

      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

    • If you are using Windows Server 2008 or Windows Server 2008 R2:

      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows Vista or Windows 7:

      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

  2. In the Connections pane, click the server connection that you want to add the native module to.

  3. In the Home pane, double-click Handler Mappings.
    Screenshot of Home pane with Handler Mappings feature selected.

  4. On the Actions pane, click Add Managed Handler...

  5. In the Add Managed Handler dialog box, specify the following:

    • Request Path. The file name or file name extension to map.

    • Type. The type (class) name of the managed handler. If the handler is defined in the app_code or bin folders of the application, its type name will appear in the drop-down list.

    • Name. A descriptive name.

      Screenshot shows Add Managed Handler dialog box with fields for Request Path, Type and Name.

  6. Click OK to close the Add Managed Handler dialog box.

How to create a FastCGI handler mapping

  1. Open Internet Information Services (IIS) Manager:

    • If you are using Windows Server 2012 or Windows Server 2012 R2:

      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows 8 or Windows 8.1:

      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

    • If you are using Windows Server 2008 or Windows Server 2008 R2:

      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows Vista or Windows 7:

      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

  2. In the Connections pane, click the server name for which you want to configure FastCGI handler mappings.

  3. In the Home pane, double-click Handler Mappings.
    Screenshot displays Server Home pane with Handler Mappings feature selected.

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

    Note

    For the next steps 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 the Microsoft Web site.

  5. Type the file name extension, such as.php in the Request path box, click FastCGIModule in the Module drop-down list, type the path to the scripting engine (in this example, PHP-CGI.exe) in the Executable box, and then click OK.
    Screenshot of Add Module Mapping dialog box with Fast C G I Module selected from the Module drop down list.

  6. On the Add Module Mapping dialog box, click Yes.
    Screenshot shows Add Module Mapping dialog box asking if you want to create a Fast C G I application for the executable.

Configuration

The <handlers> element contains a collection of <add> elements, each of which defines a handler mapping for the application. The <add> element contains the name of the handler, the file name extension or URL path mask that the handler is mapped to, and the module name or ASP.NET HTTP handler type that specifies the handler implementation, among other settings.

You configure the <handlers> element at the application level in the Web.config file.

Attributes

Attribute Description
accessPolicy Optional flags attribute.

Specifies the allowed access types for the entire handlers collection.

The accessPolicy attribute can be one of the following possible values. The default is Read.
Value Description
Execute Enables handlers in the handlers collection that require execute rights in directories and files.
None Disables all handlers in the handlers collection that require access to directories or files.
NoRemoteExecute Prevents handlers in the handlers collection from running executables when a handler receives a remote request.
NoRemoteRead Prevents handlers in the handlers collection from reading files when a handler receives a remote request.
NoRemoteScript Prevents handlers in the handlers collection from running scripts when a handler receives a remote request.
NoRemoteWrite Prevents handlers in the handlers collection from creating or changing files when a handler receives a remote request.
Read Enables handlers in the handlers collection that require read access to directories and files.
Script Enables handlers in the handlers collection that require script rights to directories or files.
Source Enables handlers in the handlers collection that require read access to source code (together with the Read flag) or write access to source code (together with the Write flag).
Write Enables handlers in the handlers collection that require write access to directories and files.

Child Elements

Element Description
add Optional element.

Adds a handler to the collection of handlers.
clear Optional element.

Removes all references to handlers from the handlers collection.
remove Optional element.

Removes a reference to a handler from the handlers collection.

Configuration Sample

The following example contains two <add> elements that define handler mappings. The first <add> element defines a SampleHandler handler for a Web application running in IIS 7 Integrated mode. If you add the handler assembly to the app_code directory for the Web application, you do not need to include the assembly name in the value for the type attribute. The second <add> element defines a mapping for PHP requests that use the FastCGI module.

<handlers>
   <add name="SampleHandler" verb="*" 
      path="SampleHandler.new" 
      type="SampleHandler, SampleHandlerAssembly" 
      resourceType="Unspecified" />
   <add name="PHP-FastCGI" verb="*" 
      path="*.php" 
      modules="FastCgiModule"
      scriptProcessor="c:\php\php-cgi.exe" 
      resourceType="Either" />
</handlers>

Sample Code

The following examples add a FastCGI mapping for a PHP module, then add a handler on the Contoso Web site that will process PHP requests.

AppCmd.exe

appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='c:\php\php-cgi.exe']" /commit:apphost

appcmd.exe set config "Contoso" -section:system.webServer/handlers /+"[name='PHP-FastCGI',path='*.php',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='c:\php\php-cgi.exe',resourceType='Either']"

Note

This second example shows how to add a new ASP.NET handler mapping named SampleHandler.new for a specific URL to a Web application.

appcmd.exe set config /section:system.webServer/handlers /+[name=SampleHandler',path='SampleHandler.new',verb='*',type='SampleHandler']

C#

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

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration appHostConfig = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection fastCgiSection = appHostConfig.GetSection("system.webServer/fastCgi");
         ConfigurationElementCollection fastCgiCollection = fastCgiSection.GetCollection();
         ConfigurationElement applicationElement = fastCgiCollection.CreateElement("application");
         applicationElement["fullPath"] = @"c:\php\php-cgi.exe";
         fastCgiCollection.Add(applicationElement);

         Configuration webConfig = serverManager.GetWebConfiguration("Contoso");
         ConfigurationSection handlersSection = webConfig.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"] = @"Either";
         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 appHostConfig As Configuration = serverManager.GetApplicationHostConfiguration
      Dim fastCgiSection As ConfigurationSection = appHostConfig.GetSection("system.webServer/fastCgi")
      Dim fastCgiCollection As ConfigurationElementCollection = fastCgiSection.GetCollection
      Dim applicationElement As ConfigurationElement = fastCgiCollection.CreateElement("application")
      applicationElement("fullPath") = "c:\php\php-cgi.exe"
      fastCgiCollection.Add(applicationElement)

      Dim webConfig As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim handlersSection As ConfigurationSection = webConfig.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") = "Either"
      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";
fastCgiCollection.AddElement(applicationElement);
adminManager.CommitChanges();

adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";
var handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST/Contoso");
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 = "Either";
handlersCollection.AddElement(addElement, 0);
adminManager.CommitChanges();

VBScript

Set adminManager = 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"
fastCgiCollection.AddElement applicationElement
adminManager.CommitChanges()

adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"
Set handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST/Contoso")
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 = "Either"
handlersCollection.AddElement addElement, 0
adminManager.CommitChanges()