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
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).
No painel Conexões, selecione a conexão do servidor que você deseja adicionar ao módulo nativo.
No painel Página Inicial, clique duas vezes em Mapeamentos de Manipulador.
No painel Ações, clique em Adicionar Manipulador Gerenciado...
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.
Clique em OK para fechar a caixa de diálogo Adicionar Manipulador Gerenciado.
Como criar um mapeamento do manipulador FastCGI
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).
No painel Conexões, clique no nome do servidor para o qual você deseja configurar mapeamentos do manipulador FastCGI.
No painel Página Inicial, clique duas vezes em Mapeamentos de Manipulador.
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.
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.
Na caixa de diálogo Adicionar Mapeamento de Módulo, clique em Sim.
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.
|
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()