处理程序 <handlers>

  • 项目

概述

<handlers> 元素定义为特定文件扩展名或 URL 注册的处理程序。

处理程序是 Internet Information Services （IIS） 组件，这些组件配置为处理对特定内容的请求，通常是为了针对请求资源生成响应。 例如，ASP.NET 网页是一种类型的处理程序。 可以使用处理程序来处理需要将非静态文件的信息返回给用户的任何资源的请求。 IIS 提供了多种不同的处理程序类型来支持静态文件、通用网关接口 (CGI) 应用程序、FastCGI 应用程序和 Internet 服务器 API (ISAPI) 扩展。 ASP.NET 还通过 HTTP 处理程序接口为其他处理程序类型提供支持。

开发人员可以创建自定义处理程序来执行特殊处理，可以在应用程序中使用文件扩展名进行标识。 例如，如果开发人员创建了一个处理程序，而它创建了 RSS 格式的 XML，则可以将应用程序中的 .rss 文件扩展名绑定到自定义处理程序。 开发人员还可以创建映射到特定文件的处理程序，并且可以将这些处理程序实现为本机模块或 ASP.NET IHttpHandler 接口的实现。

兼容性

版本 说明
IIS 10.0 <handlers> 元素在 IIS 10.0 中未进行修改。
IIS 8.5 <handlers> 元素在 IIS 8.5 中未进行修改。
IIS 8.0 <handlers> 元素在 IIS 8.0 中未进行修改。
IIS 7.5 <handlers> 元素在 IIS 7.5 中未进行修改。
IIS 7.0 <handlers> 元素是在 IIS 7.0 中引入的。
IIS 6.0 空值

安装

<handlers> 元素包含在 IIS 7 的默认安装中。

操作方式

如何为在集成模式下运行的 IIS 7 应用程序中的 ASP.NET 处理程序创建处理程序映射

  1. 打开 Internet Information Services (IIS) 管理器：

    • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

      • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS) 管理器”。

    • 如果使用的是 Windows 8 或 Windows 8.1：

      • 按住 Windows 键，按字母 X，然后单击“控制面板”。
      • 单击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

    • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

      • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS) 管理器”。

    • 如果使用 Windows Vista 或 Windows 7：

      • 在任务栏上，单击“开始”，然后单击“控制面板”。
      • 双击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

  2. 在“连接”窗格中，单击要向其添加本机模块的服务器连接。

  3. 在“开始”窗格中，双击“处理程序映射”。
    Screenshot of Home pane with Handler Mappings feature selected.

  4. 在“操作”窗格中，单击“添加托管处理程序...”

  5. 在“添加托管处理程序”对话框中，指定以下内容：

    • 请求路径。 要映射的文件名或文件扩展名。

    • 类型。 托管处理程序的类型（类）名称。 如果处理程序是在应用程序的 app_code 或 bin 文件夹中定义的，则其类型名称将出现在下拉列表中。

    • 名称. 描述性名称。

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

  6. 单击“确定”以关闭“添加托管处理程序”对话框。

如何创建 FastCGI 处理程序映射

  1. 打开 Internet Information Services (IIS) 管理器：

    • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

      • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS) 管理器”。

    • 如果使用的是 Windows 8 或 Windows 8.1：

      • 按住 Windows 键，按字母 X，然后单击“控制面板”。
      • 单击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

    • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

      • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS) 管理器”。

    • 如果使用 Windows Vista 或 Windows 7：

      • 在任务栏上，单击“开始”，然后单击“控制面板”。
      • 双击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

  2. 在“连接”窗格中，单击要为其配置 FastCGI 处理程序映射的服务器名称。

  3. 在“开始”窗格中，双击“处理程序映射”。
    Screenshot displays Server Home pane with Handler Mappings feature selected.

  4. 在“操作”窗格中，单击“添加模块映射...”

    注意

    要使后续步骤生效，您必须已经安装了将执行您指定的文件路径或文件扩展名的二进制文件。 此示例使用 Microsoft 网站中提供的 PHP 实现。

  5. 在“请求路径”框中键入文件扩展名（如 as.php），单击“模块”下拉列表中的 FastCGIModule，在“可执行文件”框中键入脚本引擎的路径（在本例中，PHP-CGI.exe），然后单击“确定”。
    Screenshot of Add Module Mapping dialog box with Fast C G I Module selected from the Module drop down list.

  6. 在“添加模块映射”对话框中，单击“是”。
    Screenshot shows Add Module Mapping dialog box asking if you want to create a Fast C G I application for the executable.

配置

<handlers> 元素包含一组 <add> 元素，每个元素都为应用程序定义一个处理程序映射。 <add> 元素包含处理程序的名称、处理程序映射到的文件扩展名或 URL 路径掩码，以及指定处理程序实现以及其他设置的模块名称或 ASP.NET HTTP 处理程序类型。

可以在 Web.config 文件中的应用程序级别配置 <handlers> 元素。

特性

属性 说明
accessPolicy 可选 flags 属性。

指定整个处理程序集合的允许访问类型。

accessPolicy 属性可以是下列可能值之一。 默认为 Read。
值 说明
Execute 在处理程序集合中启用需要目录和文件执行权限的处理程序。
None 在处理程序集合中禁用需要访问目录或文件的所有处理程序。
NoRemoteExecute 当处理程序收到远程请求时，阻止处理程序集合中的处理程序运行可执行文件。
NoRemoteRead 当处理程序收到远程请求时，阻止处理程序集合中的处理程序读取文件。
NoRemoteScript 当处理程序收到远程请求时，阻止处理程序集合中的处理程序运行脚本。
NoRemoteWrite 当处理程序收到远程请求时，阻止处理程序集合中的处理程序创建或更改文件。
Read 在处理程序集合中启用需要目录和文件读取访问权限的处理程序。
Script 在处理程序集合中启用需要目录或文件的脚本权限的处理程序。
Source 启用处理程序集合中需要源代码读取访问权限（以及 Read 标志）或写入访问权限（以及 Write 标志）的处理程序。
Write 在处理程序集合中启用需要目录和文件写入访问权限的处理程序。

子元素

元素 说明
add 可选元素。

将处理程序添加到处理程序集合。
clear 可选元素。

从处理程序集合中移除对处理程序的所有引用。
remove 可选元素。

从处理程序集合中移除对处理程序的引用。

配置示例

以下示例包含两个 <add> 元素，它们定义处理程序映射。 第一个 <add> 元素为 IIS 7 集成模式下运行的 Web 应用程序定义 SampleHandler 处理程序。 如果将处理程序的程序集添加到 Web 应用程序的 app_code 目录中，则不需要在 type 属性的值中包含程序集名称。 第二个 <add> 元素定义使用 FastCGI 模块的 PHP 请求的映射。

<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>

代码示例

以下示例为 PHP 模块添加 FastCGI 映射，然后在 Contoso 网站上添加一个将处理 PHP 请求的处理程序。

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']"

注意

第二个示例演示如何为 Web 应用程序的特定 URL 添加名为 SampleHandler.new 的新 ASP.NET 处理程序映射。

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()