添加处理程序 <add>
概述
<handlers> 集合的 <add> 元素将处理程序添加到 Internet Information Services (IIS) 7 的 HTTP 处理程序列表中。
兼容性
| 版本 | 说明 |
|---|---|
| IIS 10.0 | <add> 元素在 IIS 10.0 中未进行修改。 |
| IIS 8.5 | <add> 元素在 IIS 8.5 中未进行修改。 |
| IIS 8.0 | <add> 元素在 IIS 8.0 中未进行修改。 |
| IIS 7.5 | <add> 元素在 IIS 7.5 中未进行修改。 |
| IIS 7.0 | IIS 7.0 中引入了 <handlers> 集合的 <add> 元素。 |
| IIS 6.0 | 空值 |
安装
在 IIS 7 的默认安装中包含 <handlers> 集合的 <add> 元素。
操作方式
如何为在集成模式下运行的 IIS 7 应用程序中的 ASP.NET 处理程序创建处理程序映射
打开 Internet Information Services (IIS) 管理器：
如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：
- 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows 8 或 Windows 8.1：
- 按住 Windows 键，按字母 X，然后单击“控制面板”。
- 单击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。
如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：
- 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows Vista 或 Windows 7：
- 在任务栏上，单击“开始”，然后单击“控制面板”。
- 双击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。
在“连接”窗格中，单击要向其添加本机模块的服务器连接。
在“开始”窗格中，双击“处理程序映射”。
在“操作”窗格中，单击“添加托管处理程序...”
在“添加托管处理程序”对话框中，指定以下内容：
请求路径。 要映射的文件名或文件扩展名。
类型。 托管处理程序的类型（类）名称。 如果处理程序是在应用程序的 app_code 或 bin 文件夹中定义的，则其类型名称将出现在下拉列表中。
名称. 描述性名称。
单击“确定”以关闭“添加托管处理程序”对话框。
如何创建 FastCGI 处理程序映射
打开 Internet Information Services (IIS) 管理器：
如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：
- 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows 8 或 Windows 8.1：
- 按住 Windows 键，按字母 X，然后单击“控制面板”。
- 单击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。
如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：
- 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows Vista 或 Windows 7：
- 在任务栏上，单击“开始”，然后单击“控制面板”。
- 双击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。
在“连接”窗格中，单击要为其配置 FastCGI 处理程序映射的服务器名称。
在“开始”窗格中，双击“处理程序映射”。
在“操作”窗格中，单击“添加模块映射...”
注意
要使后续步骤生效，您必须已经安装了将执行您指定的文件路径或文件扩展名的二进制文件。 此示例使用 Microsoft 网站中提供的 PHP 实现。
在“请求路径”框中键入文件扩展名（如 as.php），单击“模块”下拉列表中的 FastCGIModule，在“可执行文件”框中键入脚本引擎的路径（在本例中，PHP-CGI.exe），然后单击“确定”。
在“添加模块映射”对话框中，单击“是”。
配置
特性
| 属性 | 说明 | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
allowPathInfo |
可选布尔属性。 指定处理程序是否处理 URI 中的完整路径信息，例如 contoso/marketing/imageGallery.aspx。 如果值为 true，处理程序将处理完整路径 contoso/marketing/imageGallery。 如果值为 false，则处理程序仅处理路径 /imageGallery 的最后一节。 默认值为 false。 |
||||||||||||||
modules |
可选的字符串属性。 指定要将文件名或文件扩展名映射到的模块或模块的名称。 如果指定多个值，请使用逗号分隔值 (,)。 默认值为 ManagedPipelineHandler。 |
||||||||||||||
name |
必需的字符串属性。 指定处理程序映射的唯一名称。 |
||||||||||||||
path |
必需的字符串属性。 指定创作规则适用的文件名或文件扩展名。 |
||||||||||||||
preCondition |
可选的字符串属性。 指定处理程序将在哪些条件下运行。 preCondition 属性的值可以是下列其中一个。 如果指定多个值，请使用逗号分隔值 (,)。
|
||||||||||||||
requireAccess |
可选的枚举属性。 指定处理程序对资源所需的访问类型。 requireAccess 属性可以是以下一个或多个可能的值。 如果指定多个值，请使用逗号分隔值 (,)。 默认值为 Script。
|
||||||||||||||
resourceType |
可选的字符串属性。 指明处理程序映射应用到的资源的类型。 resourceType 属性可以是下列可能值之一。 默认值为 Unspecified。
|
||||||||||||||
responseBufferLimit |
可选 uint 属性。 指定请求处理程序的响应缓冲区的最大大小（以字节为单位）。 默认值为 4194304 字节。 |
||||||||||||||
scriptProcessor |
可选的字符串属性。 指定处理请求的 ISAPI 扩展 .dll 文件或通用网关接口(CGI) .exe 文件的物理路径。 仅脚本映射处理程序映射需要 scriptProcessor 属性。 将处理程序映射到 ISAPI 扩展时，必须为模块属性指定 ISAPIModule。 将处理程序映射到 CGI 文件时，必须为模块属性指定 CGIModule。 |
||||||||||||||
type |
可选的字符串属性。 指定托管处理程序的命名空间路径。 仅托管处理程序需要 type 属性。 |
||||||||||||||
verb |
必需的字符串属性。 指定处理程序映射适用的 HTTP 谓词。 |
子元素
无。
配置示例
以下示例包含两个 <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()