模块元素 <modules element>

概述

<modules> 元素定义为应用程序注册的本机代码模块和托管代码模块。 作为 Internet Information Services (IIS) 请求管道处理的一部分，IIS 会对每个请求调用 <modules> 元素中列出的每个模块。 通常使用模块来实现自定义功能，例如安全性、统计信息和日志记录，或自定义的内容处理，例如添加自定义的页眉或页脚。

<modules> 元素包含 <add> 元素的集合。 每个元素都为应用程序定义一个已启用的模块。 在你启用某个模块后，此模块便可以为特定应用程序提供服务。

如果要启用某个本机模块，必须先在服务器上安装此模块。 有关详细信息，请参阅 <globalModules> 元素。

托管模块无需安装；可以直接为每个应用程序启用托管模块。 这样，应用程序就可以在应用程序的 Web.config 文件中注册托管模块，并在 /BIN 或 /App_Code 目录中提供实现，从而直接将托管模块包含在应用程序中。

兼容性

版本	说明
IIS 10.0	<modules> 元素在 IIS 10.0 中未进行修改。
IIS 8.5	<modules> 元素在 IIS 8.5 中未进行修改。
IIS 8.0	<modules> 元素在 IIS 8.0 中未进行修改。
IIS 7.5	<modules> 元素未在 IIS 7.5 中进行修改。
IIS 7.0	<modules> 元素是在 IIS 7.0 中引入的。
IIS 6.0	空值

安装

<modules> 元素包含在 IIS 7 的默认安装中。

操作方式

如何将托管模块添加到应用程序

1. 打开 Internet Information Services (IIS) 管理器：

   • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

     • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。

   • 如果使用的是 Windows 8 或 Windows 8.1：

     • 按住 Windows 键，按字母 X，然后单击“控制面板”。
     • 单击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

   • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

     • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS)管理器”。

   • 如果使用的是 Windows Vista 或 Windows 7：

     • 在任务栏上，单击“开始”，然后单击“控制面板”。
     • 双击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

2. 在“连接”窗格中，展开服务器名称，展开“站点”，然后转至要在其中添加托管模块的网站或应用程序。

3. 在“主页”窗格中，双击“模块”。
   

4. 在“操作”窗格中，单击“添加托管模块”。

5. 在“添加托管模块”对话框中，在“名称”框中输入托管模块的名称，然后在“类型”框中输入或选择模块的 .NET Framework 完全限定类型。

6. 如果希望模块仅响应托管请求，请选择“仅对 ASP.NET 应用程序或托管处理程序的请求调用”。
   

7. 单击“确定”。

配置

使用 ApplicationHost.config 文件，在服务器级别配置 <modules> 元素，使用 Web.config 文件，则可以在应用程序级别配置。

特性

属性	说明
runAllManagedModulesForAllRequests	可选的布尔值。 如果所有托管模块都可以处理所有请求（即使请求不是针对托管内容），则为 True；否则为 false。 注意：在 ASP.NET 网站中，runAllManagedModulesForAllRequests 的值以前必须设置为 true 以支持路由。 但使用 Service Pack 更新 IIS 7 后，现在使用 ASP.NET 路由时，可以将 runAllManagedModulesForAllRequests 的值设置为 false 或是省略。 有关详细信息，请参阅 MSDN 网站上的 ASP.NET 路由。 默认值为 false。
runManagedModulesForWebDavRequests	可选的布尔值。 如果托管模块可以处理 WebDAV 请求，则为 true，否则为 false。 默认值为 false。

子元素

元素	说明
add	可选元素。 将模块添加到模块集合中。
clear	可选元素。 从模块集合中删除对模块的所有引用。
remove	可选元素。 从模块集合中移除对模块的引用。

配置示例

该示例为 IIS 7 集成模式下运行的 Web 应用程序配置模块。

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

代码示例

注意

本文档中的示例说明如何使用已存储在 .NET 全局程序集缓存 (GAC) 中的托管代码程序集。 在使用这些示例中的代码部署你自己的程序集之前，你需要从 GAC 检索程序集信息。 为此，请按照以下步骤操作：

• 在 Windows 资源管理器中打开 C:\Windows\assembly 路径，其中 C: 是操作系统驱动器。
• 找到你的程序集。
• 右键单击程序集，然后单击“属性”。
• 复制“区域性”值，例如“Neutral”。
• 复制“版本”号，例如“1.0.0.0”。
• 复制“公钥令牌”值，例如“426f62526f636b73”。
• 单击“取消” 。

以下代码示例为名为 Contoso 的网站启用托管模块。 name 属性定义模块的名称 CartHeader，type 属性定义模块的托管类型，preCondition 属性定义 IIS 仅针对托管请求调用模块。

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