Compartilhar via


Manipuladores <manipuladores>

Visão geral

O elemento <handlers> define os manipuladores registrados para uma extensão ou URL de nome de arquivo específico.

Os manipuladores são componentes do IIS (Serviços de Informações da Internet) configurados para processar solicitações para conteúdo específico, normalmente para gerar uma resposta para o recurso de solicitação. Por exemplo, uma página da Web ASP.NET é um tipo de manipulador. Você pode usar manipuladores para processar solicitações para qualquer recurso que precise retornar informações aos usuários que não são um arquivo estático. O IIS fornece vários tipos de manipulador diferentes para dar suporte a arquivos estáticos, aplicativos CGI (Common Gateway Interface), aplicativos FastCGI e extensões de ISAPI (API do Servidor da Internet). ASP.NET também oferece suporte para tipos de manipulador adicionais por meio da interface do manipulador HTTP.

Os desenvolvedores podem criar manipuladores personalizados para executar uma manipulação especial que você pode identificar usando extensões de nome de arquivo em seu aplicativo. Por exemplo, se um desenvolvedor criou um manipulador que criou XML formatado pelo RSS, você poderá associar a extensão de nome de arquivo .rss em seu aplicativo ao manipulador personalizado. Os desenvolvedores também podem criar manipuladores mapeados para um arquivo específico e podem implementar esses manipuladores como módulos nativos ou como implementações da interface IHttpHandler ASP.NET.

Compatibilidade

Versão Observações
IIS 10.0 O elemento <handlers> não foi modificado no IIS 10.0.
IIS 8.5 O elemento <handlers> não foi modificado no IIS 8.5.
IIS 8.0 O elemento <handlers> não foi modificado no IIS 8.0.
IIS 7.5 O elemento <handlers> não foi modificado no IIS 7.5.
IIS 7.0 O elemento <handlers> foi introduzido no IIS 7.0.
IIS 6,0 N/D

Instalação

O elemento <handlers> está incluído na instalação padrão do IIS 7.

Instruções

Como criar um mapeamento de manipulador para um manipulador do ASP.NET em um aplicativo dos IIS 7 em execução no modo integrado

  1. Abra o Gerenciador dos Serviços de Informações da Internet (IIS):

    • Caso você esteja usando o Windows Server 2012 ou o Windows Server 2012 R2:

      • Na barra de tarefas, clique em Gerenciador do Servidor, em Ferramentas e em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Se você estiver usando o Windows 8 ou Windows 8.1:

      • Mantenha pressionada a tecla Windows, pressione a letra X e clique em Painel de Controle.
      • Clique em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Caso você esteja usando o Windows Server 2008 ou o Windows Server 2008 R2:

      • Na barra de tarefas, clique em Iniciar, vá para Ferramentas Administrativas e clique em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Se você estiver usando o Windows Vista ou Windows 7:

      • Na barra de tarefas, clique em Iniciar e, depois, em Painel de Controle.
      • Clique duas vezes em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
  2. No painel Conexões, selecione a conexão do servidor que você deseja adicionar ao módulo nativo.

  3. No painel Página Inicial, clique duas vezes em Mapeamentos de Manipulador.
    Screenshot of Home pane with Handler Mappings feature selected.

  4. No painel Ações, clique em Adicionar Manipulador Gerenciado...

  5. Na caixa de diálogo Adicionar Manipulador Gerenciado, especifique o seguinte:

    • Caminho de solicitação. O nome do arquivo ou a extensão de nome de arquivo a ser mapeada.

    • Tipo. O nome do tipo (classe) do manipulador gerenciado. Se o manipulador for definido nas pastas app_code ou bin do aplicativo, seu nome de tipo aparecerá na lista suspensa.

    • Nome.. Um nome descritivo.

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

  6. Clique em OK para fechar a caixa de diálogo Adicionar Manipulador Gerenciado.

Como criar um mapeamento do manipulador FastCGI

  1. Abra o Gerenciador dos Serviços de Informações da Internet (IIS):

    • Caso você esteja usando o Windows Server 2012 ou o Windows Server 2012 R2:

      • Na barra de tarefas, clique em Gerenciador do Servidor, em Ferramentas e em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Se você estiver usando o Windows 8 ou Windows 8.1:

      • Mantenha pressionada a tecla Windows, pressione a letra X e clique em Painel de Controle.
      • Clique em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Caso você esteja usando o Windows Server 2008 ou o Windows Server 2008 R2:

      • Na barra de tarefas, clique em Iniciar, vá para Ferramentas Administrativas e clique em Gerenciador dos Serviços de Informações da Internet (IIS).
    • Se você estiver usando o Windows Vista ou Windows 7:

      • Na barra de tarefas, clique em Iniciar e, depois, em Painel de Controle.
      • Clique duas vezes em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
  2. No painel Conexões, clique no nome do servidor para o qual você deseja configurar mapeamentos do manipulador FastCGI.

  3. No painel Página Inicial, clique duas vezes em Mapeamentos de Manipulador.
    Screenshot displays Server Home pane with Handler Mappings feature selected.

  4. No painel Ações, clique em Adicionar Mapeamento de Módulo...

    Observação

    Para que as próximas etapas funcionem, você já deve ter instalado binários que executarão o caminho do arquivo ou a extensão de nome de arquivo que você especificar. Este exemplo usa uma implementação PHP disponível no site da Microsoft.

  5. Digite a extensão de nome de arquivo, como as.php, na caixa Solicitar caminho, clique em FastCGIModule na lista suspensa Módulo, digite o caminho ao mecanismo de script (neste exemplo, PHP-CGI.exe) na caixa Executável e, em seguida, clique em OK.
    Screenshot of Add Module Mapping dialog box with Fast C G I Module selected from the Module drop down list.

  6. Na caixa de diálogo Adicionar Mapeamento de Módulo, clique em Sim.
    Screenshot shows Add Module Mapping dialog box asking if you want to create a Fast C G I application for the executable.

Configuração

O elemento <handlers> contém uma coleção de elementos <add>, cada um deles define um mapeamento de manipulador para o aplicativo. O elemento <add> contém o nome do manipulador, a extensão de nome do arquivo ou a máscara de caminho de URL para a qual o manipulador está mapeado e o nome do módulo ou ASP.NET tipo de manipulador HTTP que especifica a implementação do manipulador, entre outras configurações.

Configure o elemento <handlers> no nível do aplicativo no arquivo Web.config.

Atributos

Atributo Descrição
accessPolicy Atributo de sinalizadores opcionais.

Especifica os tipos de acesso permitidos para toda a coleção de manipuladores.

O atributo accessPolicy pode ser um dos valores possíveis a seguir. O padrão é Read.
Valor Descrição
Execute Habilita manipuladores na coleção de manipuladores que exigem direitos de execução em diretórios e arquivos.
None Desabilita todos os manipuladores na coleção de manipuladores que exigem acesso a diretórios ou arquivos.
NoRemoteExecute Impede que manipuladores na coleção de manipuladores executem executáveis quando um manipulador recebe uma solicitação remota.
NoRemoteRead Impede que manipuladores na coleção de manipuladores leiam arquivos quando um manipulador recebe uma solicitação remota.
NoRemoteScript Impede que os manipuladores na coleção de manipuladores executem scripts quando um manipulador recebe uma solicitação remota.
NoRemoteWrite Impede que manipuladores na coleção de manipuladores criem ou alterem arquivos quando um manipulador recebe uma solicitação remota.
Read Habilita manipuladores na coleção de manipuladores que exigem acesso de leitura para diretórios e arquivos.
Script Habilita manipuladores na coleção de manipuladores que exigem direitos de script para diretórios ou arquivos.
Source Habilita manipuladores na coleção de manipuladores que exigem acesso de leitura ao código-fonte (juntamente com o sinalizador de leitura) ou o acesso de gravação ao código-fonte (juntamente com o sinalizador de Gravação).
Write Habilita manipuladores na coleção de manipuladores que exigem acesso de gravação para diretórios e arquivos.

Elementos filho

Elemento Descrição
add Elemento opcional.

Adiciona um manipulador à coleção de manipuladores.
clear Elemento opcional.

Remove todas as referências aos manipuladores da coleção de manipuladores.
remove Elemento opcional.

Remove uma referência a um manipulador da coleção de manipuladores.

Exemplo de configuração

O exemplo a seguir contém dois elementos <add> que definem mapeamentos de manipulador. O primeiro elemento <add> define um manipulador SampleHandler para um aplicativo Web em execução no modo integrado dos IIS 7. Se você adicionar o assembly do manipulador ao diretório app_code para o aplicativo Web, não precisará incluir o nome do assembly no valor do atributo type. O segundo elemento <add> define um mapeamento para solicitações PHP que usam o 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>

Exemplo de código

Os exemplos a seguir adicionam um mapeamento FastCGI para um módulo PHP e, em seguida, adicionam um manipulador no site da Contoso que processará solicitações 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']"

Observação

Este segundo exemplo mostra como adicionar um novo mapeamento de manipulador do ASP.NET chamado SampleHandler.new a uma URL específica para um aplicativo 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()