Controladores <handlers>
Información general
El elemento <handlers> define los controladores registrados para una extensión o dirección URL de nombre de archivo específicas.
Los controladores son componentes de Internet Information Services (IIS) que están configurados para procesar solicitudes a contenido específico, normalmente para generar una respuesta para el recurso de solicitud. Por ejemplo, una página web ASP.NET es un tipo de controlador. Puede usar controladores para procesar solicitudes a cualquier recurso que necesite devolver información a los usuarios y que no sea un archivo estático. IIS proporciona varios tipos de controlador diferentes para admitir archivos estáticos, aplicaciones de interfaz CGI, aplicaciones FastCGI y extensiones de Internet Server API (ISAPI). ASP.NET también proporciona compatibilidad con tipos de controladores adicionales mediante la interfaz de controladores HTTP.
Los desarrolladores pueden crear controladores personalizados para realizar un control especial que puede identificar mediante extensiones de nombre de archivo en la aplicación. Por ejemplo, si un desarrollador creó un controlador que creó XML con formato RSS, podría enlazar la extensión de nombre de archivo .rss de la aplicación al controlador personalizado. Los desarrolladores también pueden crear controladores que se asignen a un archivo específico y pueden implementar estos controladores como módulos nativos o como implementaciones de la interfaz IHttpHandler de ASP.NET.
Compatibilidad
| Versión | Notas |
|---|---|
| IIS 10.0 | El elemento <handlers> no se modificó en IIS 10.0. |
| IIS 8.5 | El elemento <handlers> no se modificó en IIS 8.5. |
| IIS 8.0 | El elemento <handlers> no se modificó en IIS 8.0. |
| IIS 7.5 | El elemento <handlers> no se modificó en IIS 7.5. |
| IIS 7.0 | El elemento <handlers> se introdujo en IIS 7.0. |
| IIS 6,0 | N/D |
Configuración
El elemento <handlers> se incluye en la instalación predeterminada de IIS 7.
Procedimientos
Creación de una asignación de controladores para un controlador de ASP.NET en una aplicación de IIS que se ejecuta en modo integrado
Abra el Administrador de Internet Information Services (IIS):
Si usa Windows Server 2012 o Windows Server 2012 R2:
- En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
Si usa Windows 8 o Windows 8.1:
- Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
- En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
Si usa Windows Server 2008 o Windows Server 2008 R2:
- En la barra de tareas, haga clic en Inicio, seleccione Herramientas administrativas y, a continuación, haga clic en Administrador de Internet Information Services (IIS).
Si usa Windows Vista o Windows 7:
- En la barra de tareas, haga clic en Inicio y, luego, haga clic en Panel de control.
- Haga doble clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
En el panel Conexiones, haga clic en la conexión de servidor a la que desea agregar el módulo nativo.
En el panel Inicio, haga doble clic en Asignaciones de controlador.
En el panel Acciones, haga clic en Agregar controlador administrado...
En el cuadro de diálogo Agregar controlador administrado, especifique lo siguiente:
Ruta de acceso de solicitud Nombre de archivo o extensión de nombre de archivo que se va a asignar.
Tipo. Nombre de tipo (clase) del controlador administrado. Si el controlador se define en las carpetas app_code o bin de la aplicación, su nombre de tipo aparecerá en la lista desplegable.
Nombre. Nombre descriptivo.
Haga clic en Aceptar para cerrar el cuadro de diálogo Agregar controlador administrado.
Creación de una asignación de controladores de FastCGI
Abra el Administrador de Internet Information Services (IIS):
Si usa Windows Server 2012 o Windows Server 2012 R2:
- En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
Si usa Windows 8 o Windows 8.1:
- Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
- En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
Si usa Windows Server 2008 o Windows Server 2008 R2:
- En la barra de tareas, haga clic en Inicio, seleccione Herramientas administrativas y, a continuación, haga clic en Administrador de Internet Information Services (IIS).
Si usa Windows Vista o Windows 7:
- En la barra de tareas, haga clic en Inicio y, luego, haga clic en Panel de control.
- Haga doble clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
En el panel Conexiones, haga clic en el nombre del servidor para el que desea configurar asignaciones de controladores de FastCGI.
En el panel Inicio, haga doble clic en Asignaciones de controlador.
En el panel Acciones, haga clic en Agregar asignación de módulos...
Nota:
Para que los pasos siguientes funcionen, debe haber instalado archivos binarios que ejecutarán la ruta de acceso del archivo o la extensión de nombre de archivo que especifique. En este ejemplo se usa una implementación de PHP disponible en el sitio web de Microsoft.
Escriba la extensión de nombre de archivo, como as.php, en el cuadro Ruta de acceso de solicitud, haga clic en FastCGIModule en la lista desplegable Módulo, escriba la ruta de acceso al motor de scripting (en este ejemplo, PHP-CGI.exe) en el cuadro Ejecutable y, a continuación, haga clic en Aceptar.
En el cuadro de diálogo Agregar asignación de módulos, haga clic en Sí.
Configuración
El elemento <handlers> contiene una colección de elementos <add>, cada uno de los cuales define una asignación de controlador para la aplicación. El elemento <add> contiene, entre otras opciones, el nombre del controlador, la extensión de nombre de archivo o la máscara de ruta de acceso de dirección URL a la que se asigna el controlador y el nombre del módulo o el tipo de controlador HTTP de ASP.NET que especifica la implementación del controlador.
El elemento <handlers> se configura a nivel de aplicación en el archivo Web.config.
Atributos
| Atributo | Descripción | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accessPolicy |
Atributo flags opcional. Especifica los tipos de acceso permitidos para toda la colección de controladores. El atributo accessPolicy puede tener uno de los siguientes valores posibles. El valor predeterminado es Read.
|
Elementos secundarios
| Elemento | Descripción |
|---|---|
add |
Elemento opcional. Agrega un controlador a la colección de controladores. |
clear |
Elemento opcional. Quita todas las referencias a controladores de la colección de controladores. |
remove |
Elemento opcional. Quita una referencia a un controlador de la colección de controladores. |
Ejemplo de configuración
En el ejemplo siguiente se incluyen dos elementos <add> que definen asignaciones de controladores. El primer elemento <add> define un controlador SampleHandler para una aplicación web que se ejecuta en modo integrado de IIS 7. Si agrega el ensamblado de controlador al directorio app_code de la aplicación web, no es necesario incluir el nombre del ensamblado en el valor del atributo type. El segundo elemento <add> define una asignación para las solicitudes PHP que usan el módulo FastCGI.
<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>
Código de ejemplo
En los ejemplos siguientes se agrega una asignación FastCGI para un módulo PHP y, a continuación, se agrega un controlador en el sitio web Contoso que procesará las solicitudes 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']"
Nota:
En este segundo ejemplo se muestra cómo agregar una nueva asignación de controladores ASP.NET denominada SampleHandler.new para una dirección URL específica a una aplicación web.
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()