How to: Configure an HTTP Handler Extension in IIS

  • Article

By default, Internet Information Services (IIS) passes requests for only certain file types to ASP.NET to service. Files with file-name extensions such as .aspx, asmx, and .ashx are already mapped to the ASP.NET ISAPI extension (Aspnet_isapi.dll). This applies to IIS 6.0, to IIS 7.0 running in Classic mode, and to managed handlers in IIS 7.0 that are running in Integrated mode.

To have IIS pass other file-name extensions to ASP.NET, you must register the extensions in IIS. For more information about how handlers participate in the application life cycle, see ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0 or ASP.NET Application Life Cycle Overview for IIS 7.0.

To map a file-name extension in IIS 6.0

  1. Open IIS Manager.

  2. Expand the node for the Web server computer, expand Web Sites, and then expand Default Web Site.

  3. Right-click the name of your application, and then click Properties.

    Note

    For information about how to create an ASP.NET application, see How to: Create and Configure Local ASP.NET Web Sites in IIS 6.0.

  4. Click the Virtual Directory tab, and then click Configuration.

  5. On the Mappings tab, click Add.

    The Add/Edit Application Extension Mapping dialog box is displayed.

  6. In the Executable box, type or browse to the file Aspnet_isapi.dll. By default, the file is in the following location:

    %windows%\Microsoft.NET\Framework\version\

    Note

    You can get the complete path and file name from other mappings, such as the mapping to .aspx files.

  7. In the Extension box, type the file-name extension, such as .sample.

    Note

    Make sure that you include the dot (.) as part of the file-name extension.

  8. Select the Verify that file exists check box according to what the file-name extension represents in your application. Choose these options:

    • True. The file-name extension represents a physical file in the application. In this case, if the requested file does not exist on disk, IIS displays an error.

    • False. The file-name extension does not represent a physical file. Instead, the extension is handled dynamically by a class that is mapped to the extension in ASP.NET.

  9. Click OK and then close IIS Manager.

To map a file-name extension in IIS 7.0 running in Classic mode

  1. Open IIS Manager.

    Note

    In and Windows Server 2008, if the User Account Control (UAC) feature is enabled, it prompts you to continue access to the manager. For more information, see User Account Control Overview.

  2. Expand the node for the Web server computer, expand Sites, and then expand Default Web Site.

  3. Select the node for your application.

    The Features View pane is displayed.

  4. In Features View, double-click Handler Mappings.

  5. On the Actions pane, click Add Script Map.

    The Add Script Map dialog box is displayed.

  6. In the Add Script Map dialog box, specify the following:

    • Request Path. The name or file-name extension to map.

    • Executable. The path of the .exe or .dll file that will handle the request. For Classic mode, specify the ASP.NET ISAPI extension (Aspnet_isapi.dll).

    • Name. A descriptive name.

  7. Click OK to close the Add Script Map dialog box.

    Note

    Using IIS Manager in IIS 7.0 to add a custom handler extension is equivalent to registering the handler extension in the Web.config file of an ASP.NET application. The registration adds a handler element in the handlers section of the system.webServer group. 

  8. Open the Web.config file for the application.

  9. Locate the httpHandlers element of the system.web section and add an entry for the file-name extension.

    Note

    The file-name extension must be registered in both the httpHandlers element and the handlers element.

To map a file-name extension in IIS 7.0 running in Integrated mode

  1. Follow steps 1 through 3 of the previous procedure.

  2. On the Actions pane, click Add Managed Handler.

    The Add Managed Handler dialog box is displayed.

  3. In the Add Managed Handler dialog box, specify the following:

    • Request Path. The file name or file-name extension to map.

    • Type. The type (class) name of the managed handler. If the handler is defined in the App_Code folder of the ASP.NET application, its type name will appear in the drop-down list.

    • Name. A descriptive name.

  4. Click OK to close the Add Managed Handler dialog box.

    Note

    Using IIS Manager in IIS 7.0 to add a custom handler extension is equivalent to registering the handler extension in the Web.config file.

    Note

    For a handler that services a custom extension in IIS 7.0 running in Integrated mode, only a registration in the handlers element is needed. If you want to keep the registration in the httpHandlers element also, create a validation element in the system.webServer section (if it does not exist) and set its validateIntegratedModeConfiguration attribute to false. For more information, see How to: Suppress IIS 7.0 Registration Warnings,

See Also

Tasks

How to: Register HTTP Handlers