Compartir a través de


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

  1. 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).
  2. En el panel Conexiones, haga clic en la conexión de servidor a la que desea agregar el módulo nativo.

  3. En el panel Inicio, haga doble clic en Asignaciones de controlador.
    Screenshot of Home pane with Handler Mappings feature selected.

  4. En el panel Acciones, haga clic en Agregar controlador administrado...

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

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

  6. Haga clic en Aceptar para cerrar el cuadro de diálogo Agregar controlador administrado.

Creación de una asignación de controladores de FastCGI

  1. 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).
  2. En el panel Conexiones, haga clic en el nombre del servidor para el que desea configurar asignaciones de controladores de FastCGI.

  3. En el panel Inicio, haga doble clic en Asignaciones de controlador.
    Screenshot displays Server Home pane with Handler Mappings feature selected.

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

  5. 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.
    Screenshot of Add Module Mapping dialog box with Fast C G I Module selected from the Module drop down list.

  6. En el cuadro de diálogo Agregar asignación de módulos, haga clic en .
    Screenshot shows Add Module Mapping dialog box asking if you want to create a Fast C G I application for the executable.

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.
Valor Descripción
Execute Habilita controladores de la colección de controladores que requieren derechos de ejecución en directorios y archivos.
None Deshabilita todos los controladores de la colección de controladores que requieren acceso a directorios o archivos.
NoRemoteExecute Impide que los controladores de la colección de controladores ejecuten ejecutables cuando un controlador recibe una solicitud remota.
NoRemoteRead Impide que los controladores de la colección de controladores lean archivos cuando un controlador recibe una solicitud remota.
NoRemoteScript Impide que los controladores de la colección de controladores ejecuten scripts cuando un controlador recibe una solicitud remota.
NoRemoteWrite Impide que los controladores de la colección de controladores creen o cambien archivos cuando un controlador recibe una solicitud remota.
Read Habilita los controladores de la colección de controladores que requieren acceso de lectura a directorios y archivos.
Script Habilita los controladores de la colección de controladores que requieren derechos de script para directorios o archivos.
Source Habilita los controladores de la colección de controladores que requieren acceso de lectura al código fuente (junto con la marca Read) o acceso de escritura al código fuente (junto con la marca Write).
Write Habilita los controladores de la colección de controladores que requieren acceso de escritura a directorios y archivos.

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