Elemento Modules <modules element>

Visão geral

O elemento <modules> define os módulos de código nativo e os módulos de código gerenciado registrados para um aplicativo. Como parte do processamento de pipeline de solicitação do IIS (Serviços de Informações da Internet), o IIS chama cada módulo listado no elemento <modules> em cada solicitação. Normalmente, você usa módulos para implementar funcionalidades personalizadas, como segurança, estatísticas e log, ou processamento de conteúdo personalizado, como adicionar cabeçalhos ou rodapés personalizados.

O elemento <modules> contém uma coleção de elementos <add>. Cada elemento define um módulo habilitado para o aplicativo. Ao habilitar um módulo, você permite que ele forneça seu serviço para um aplicativo específico.

Se você deseja habilitar um módulo nativo, você deve primeiro instalá-lo no servidor. Para obter mais informações, consulte o elemento <globalModules>.

Não é necessário instalar um módulo gerenciado; você pode habilitá-lo diretamente para cada aplicativo. Isso permite que os aplicativos incluam seus módulos gerenciados diretamente no aplicativo registrando-os no arquivo Web.config do aplicativo e fornecendo a implementação nos diretórios /BIN ou /App_Code.

Compatibilidade

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

Instalação

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

Instruções

Como adicionar um módulo gerenciado ao aplicativo

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, expanda o nome do servidor, expanda Sites e acesse o site ou aplicativo ao qual deseja adicionar um módulo gerenciado.

3. No painel Página Inicial, clique duas vezes em Módulos.
   

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

5. Na caixa de diálogo Adicionar Módulo Gerenciado, insira o nome do módulo gerenciado na caixa Nome e, em seguida, insira ou selecione o tipo totalmente qualificado do .NET Framework do módulo na caixa Tipo.

6. Selecione a opção Invocar somente para solicitações para aplicativos ASP.NET ou manipuladores gerenciados se quiser que o módulo responda apenas a solicitações gerenciadas.
   

7. Clique em OK.

Configuração

Você configura o elemento <modules> no nível do servidor no arquivo ApplicationHost.config e no nível do aplicativo no arquivo Web.config.

Atributos

Atributo	Descrição
runAllManagedModulesForAllRequests	Valor booliano opcional. True se todos os módulos gerenciados puderem processar todas as solicitações, mesmo que a solicitação não tenha sido para conteúdo gerenciado, caso contrário, false. Observação: Em sites ASP.NET, o valor de runAllManagedModulesForAllRequests tinha que ser definido como true para oferecer suporte ao roteamento. No entanto, depois que o IIS 7 tiver sido atualizado com um Service Pack, o valor de runAllManagedModulesForAllRequests pode ser definido como false ou omitido ao trabalhar com roteamento do ASP.NET. Para obter mais informações, confira Roteamento do ASP.NET no site do MSDN. O valor padrão é false.
runManagedModulesForWebDavRequests	Valor booliano opcional. True se os módulos gerenciados puderem processar solicitações WebDAV, caso contrário, false. O valor padrão é false.

Elementos filho

Elemento	Descrição
add	Elemento opcional. Adiciona um módulo à coleção de módulos.
clear	Elemento opcional. Remove todas as referências a módulos da coleção de módulos.
remove	Elemento opcional. Remove uma referência a um módulo da coleção de módulos.

Exemplo de configuração

O exemplo configura um módulo para um aplicativo Web em execução no modo integrado do IIS 7.

<configuration>
   <system.webServer>
      <modules>
         <add name="Header" type="Contoso.ShoppingCart.Header"/>
      </modules>
   </system.webServer>
</configuration>

Exemplo de código

Observação

Os exemplos neste documento ilustram o uso de um assembly de código gerenciado que foi armazenado no .NET Global Assembly Cache (GAC). Antes de usar o código nesses exemplos para implantar seus próprios assemblies, você precisa recuperar as informações do assembly do GAC. Para fazer isso, execute as seguintes etapas:

• No Windows Explorer, abra o caminho C:\Windows\assembly, onde C: é a unidade do sistema operacional.
• Localize o assembly.
• Clique com o botão direito no assembly e selecione Propriedades.
• Copie o valor de Cultura, por exemplo: Neutro.
• Copie o número de Versão, por exemplo: 1.0.0.0.
• Copie o valor do Token de Chave Pública, por exemplo: 426f62526f636b73.
• Clique em Cancelar.

Os exemplos de código a seguir habilitam um módulo gerenciado para um site chamado Contoso. A propriedade name define o nome CartHeader para o módulo, a propriedade type define o tipo gerenciado para o módulo, a propriedade preCondition define que o IIS invoca o módulo somente para solicitações gerenciadas.

AppCmd.exe

appcmd.exe set config "Contoso" -section:system.webServer/modules /+"[name='CartHeader',type='Contoso.ShoppingCart.Header',preCondition='managedHandler']"

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetWebConfiguration("Contoso");
         ConfigurationSection modulesSection = config.GetSection("system.webServer/modules");
         ConfigurationElementCollection modulesCollection = modulesSection.GetCollection();

         ConfigurationElement addElement = modulesCollection.CreateElement("add");
         addElement["name"] = @"CartHeader";
         addElement["type"] = @"Contoso.ShoppingCart.Header";
         addElement["preCondition"] = @"managedHandler";
         modulesCollection.Add(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 config As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim modulesSection As ConfigurationSection = config.GetSection("system.webServer/modules")
      Dim modulesCollection As ConfigurationElementCollection = modulesSection.GetCollection

      Dim addElement As ConfigurationElement = modulesCollection.CreateElement("add")
      addElement("name") = "CartHeader"
      addElement("type") = "Contoso.ShoppingCart.Header"
      addElement("preCondition") = "managedHandler"
      modulesCollection.Add(addElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";
var modulesSection = adminManager.GetAdminSection("system.webServer/modules", "MACHINE/WEBROOT/APPHOST/Contoso");
var modulesCollection = modulesSection.Collection;

var addElement = modulesCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "CartHeader";
addElement.Properties.Item("type").Value = "Contoso.ShoppingCart.Header";
addElement.Properties.Item("preCondition").Value = "managedHandler";
modulesCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"
Set modulesSection = adminManager.GetAdminSection("system.webServer/modules", "MACHINE/WEBROOT/APPHOST/Contoso")
Set modulesCollection = modulesSection.Collection

Set addElement = modulesCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "CartHeader"
addElement.Properties.Item("type").Value = "Contoso.ShoppingCart.Header"
addElement.Properties.Item("preCondition").Value = "managedHandler"
modulesCollection.AddElement addElement

adminManager.CommitChanges()