IIS 7.0 : Runtime Web Server Extensibility (part 4) - Using IIS Manager to Install and Manage Modules

Using IIS Manager to Install and Manage Modules

IIS Manager provides a powerful UI for managing modules on the server. This UI can be used to install both native and managed modules, as well as manage enabled modules on the server and for specific applications.

The Modules feature provides this functionality, and it can be accessed at two separate levels for slightly different functionality:

• By server administrators at the server level, to install native modules on the server, add new managed modules, and configure modules that are enabled on the server by default.

• By server or site administrators at the application level, to add new managed modules and configure enabled modules for the application.

At the server level, you can select the machine node in the tree view and then double-click the modules to access the Modules feature, as shown in Figure 2.

Figure 2. The Modules feature in IIS Manager.

You will see the list of modules enabled at the server level, which corresponds to the list of modules in the modules configuration section at the server level in ApplicationHost.config. For each module, you will see its name. For native modules, you’ll also see the path to the image DLL. For managed modules, you’ll also see the module type name. You will also see three actions available on this page:

• Add Managed Module. Enables you to add a new managed module to the list of enabled modules. In the resulting dialog box, you can specify the name of your new module, as well as the module’s type.

  

  You can select a module type from the Type drop-down list, which contains all module types available from the assemblies located in the machine’s Global Assembly Cache listed in the system.web/compilation/assemblies section of the .NET Framework’s root Web.config. You can also type in your own type if it’s not yet listed. Select the Invoke Only For Requests To ASP.NET Applications Or Managed Handlers check box if you want your module to use the managedHandler precondition and only execute for requests to ASP.NET handlers .

• Configure Native Modules. Enables you to enable an already installed native module, install a new native module, or uninstall an existing native module.

  

  Here, you can enable native modules that are installed but not currently enabled by selecting one or more of them. You can also use the Register button to install a new native module, the Edit button to edit the name or the path for an installed module, or the Remove button to uninstall the selected native module.

• View Ordered List. Enables you to display the list of modules in an ordered list so that you can adjust their sequence by using the Move Up and Move Down actions. When this is done at the server level, you can reorder the modules without resorting to clearing the modules collection .

Also, when you select a module entry in the list, three additional actions become available:

1. Edit. This action enables you to edit the modules entry. For native modules, you can directly change the native module installation information including its name and path to native image DLL. For managed modules, you can edit the module name and the module type.

2. Lock/Unlock. These actions enable you to lock the specific module item at the server level, such that it cannot be removed or modified at the application level. 

3. Remove. This action enables you to remove the module entry. For native modules, this disables the module by default. For managed modules, this removes the module entry, requiring you to later re-add this entry at the application level to enable it there.

To access the Modules feature at the application level, go to the tree view and select the application you would like to administer. Then double-click the Modules feature icon. You will be presented with the same view as before, except for the following differences:

• You will no longer be able to add new native modules from the Configure Native Modules dialog box. Remember, this is because native modules are installed for the entire server, and you must have Administrative privileges to do that. Instead, you will only be able to enable already installed native modules that are not currently enabled for your application.

• You will no longer be able to edit native module information or edit managed module information for managed modules that are enabled at the server level (you can still edit module information for managed modules added in your application).

• You will not be able to lock/unlock modules.

• When adding managed modules, the tool will also inspect all assemblies in the /BIN and /App_Code source files for possible modules to add.

• You can use the Revert To Inherited action to discard whatever changes were made to the modules configuration section at the application level and then revert to the default module configuration at the server level.

Despite these limitations, site administrators can still use IIS Manager to install new managed modules or manage their applications’ module feature set without requiring Administrative privileges on the machine. This is especially valuable given the ability of IIS Manager to enable remote delegated administration for application owners. Of course, server administrators can also benefit from IIS Manager for unrestricted module management.

Using IIS Manager to Create and Manage Handler Mappings

IIS Manager also provides a convenient interface to manage handler mappings, thus removing some of the complexity involved with editing the handler mappings manually. This functionality is provided by the Handler Mappings feature, which both server administrators and site administrators can access.

After selecting the node at which you’d like to manage handler mappings, you can select the feature by double-clicking the Handler Mappings icon. This presents the Handler Mappings view, as shown in Figure 3.

Figure 3. The Handler Mappings feature in IIS Manager.

Here, you will see a list of handler mappings including the handler mapping name, path, and other useful information. The Handler column provides a summary of how the handler is implemented, showing either the modules list for native handlers or the type for managed handlers. The Path Type indicates the resourceType of the handler mapping. The State column indicates if this handler is enabled (this applies only to handler mappings using IsapiModule or CgiModule) and indicates whether the ISAPI extension or CGI program specified by the mapping is enabled in the system.webServer/security/isapiCgiRestrictions configuration (analogous to the Web Service Restriction List in IIS 6.0).

The tool provides a number of ways to add new handler mappings, breaking them out by type to simplify handler mapping creation:

• Add Managed Handler. This action enables you to create handler mapping to an ASP.NET handler. This mapping is available only in application pools that are using Integrated mode. It is shown in Figure 4.

  

  Figure 4. Add Managed Handler dialog box.

  In this dialog box, you specify the path mask for the handler mapping, as well as the ASP.NET handler type that should provide processing for it. Much like when adding managed modules, the tool searches for usable types in the assemblies from the Global Assembly Cache (GAC) that are referenced in the ASP.NET compilation/assemblies collection. It also searches for application assemblies when you’re adding the handler at the application level. You can use the Request Restrictions dialog box to also specify the verb list for the handler mapping (otherwise, it defaults to "*"), restrict the mapping to physical resources such as a file or directory (the default is unspecified), and set access level as required to execute the mapping (defaults to Script). You should indeed set these to the strictest possible levels for added security instead of leaving them at default values.

• Add Script Map. This action enables you to create an ISAPI extension or CGI program handler mapping, similar to the IIS 6.0 scriptmap. This is shown in Figure 5.

  

  Figure 5. Add Script Map dialog box.

  This is similar to the previous dialog box, except instead of the .NET handler type, you select the ISAPI extension, DLL, or CGI program executable on the server’s local file system. This dialog box also prompts you to automatically create the isapiCgiRestriction entry to allow the ISAPI extension or CGI program to execute on the server.

• Add Wildcard Script Map. This is identical to the Add Script Map dialog box, except that it enables you to create a wildcard script map that intercepts all requests.

• Add Module Mapping. This is the most interesting action, because it enables you to create a general handler mapping that specifies one or more native modules and optionally a script processor. You can use this dialog box to create ISAPI extension, CGI, and FastCGI handler mappings in addition to simple handler mappings for native modules, as shown in Figure 6.

  

  Figure 6. Add Module Mapping dialog box.

  The dialog box enables you to specify the Module (and it displays a list of available native modules, although not all of them can function as handlers) and the Executable (the script processor). It also provides special handling for IsapiModule, CgiModule, and FastCgiModule handler mappings by prompting you to automatically create the corresponding isapiCgiRestrictions or FastCGI configuration needed for the mapping to work correctly.

Note

It is not possible to edit preconditions via the Handler Mappings feature. Instead, the tool automatically generates the correct preconditions for handler mappings to make it function correctly by default. If you would like to change the preconditions, you need to edit configuration directly by hand, with Appcmd, or with other configuration APIs.

In addition to adding new handler mappings, you can also edit or delete existing handler mappings by clicking the item in the list and using the Edit or Delete commands that become available. At the server level, you can also lock handler mappings to prevent them from being removed at the lower level, although this has less effect than locking modules because handler mappings can be overridden by adding new handler mappings for the same path/verb.

You can also use the "View Ordered List" action to order handler mappings. Keep in mind that just as it is for modules, ordering inherited elements requires the tool to use <clear/> to clear the handlers collection and add again all parent items into the configuration level being edited, essentially orphaning the configuration from the parent handler mappings configuration.

If you edit handler mappings as a site administrator, you have virtually the same functionality available to you for managing the handler mappings for your site, application, or any URL inside your site. However, the tool will not prompt you to enable ISAPI extensions, CGI programs, and FastCGI programs that the administrator has not already enabled at the server level.