Walkthrough: Configuring ASP.NET Applications in IIS 7.0

Article
10/22/2014

If an ASP.NET Web application is hosted in IIS 7.0, you can make configuration settings for the application in a variety of ways. This includes the following:

Using IIS Manager. For more information, see How to: Open IIS Manager and Internet Information Services (IIS) Manager.
Editing the Web.config file directly. You can do this in Visual Studio or Visual Web Developer, or by using a text-editing program.
Using the IIS 7.0 command-line tool (Appcmd.exe). This utility enables you to specify IIS configuration settings and Web application configuration settings. For more information, see IIS 7.0 Command-Line Tool.
Using Windows Management Instrumentation (WMI). The IIS 7.0 WMI provider WebAdministration namespace contains classes and methods that enable you to create script for administration tasks for Web sites, Web applications, and their associated objects and properties. For more information, see IIS 7.0: WMI.

IIS 7.0 has a modular architecture that enables you to specify which modules make up the functionality of a Web server. When IIS 7.0 is installed, by default many modules are not enabled. When you are working with ASP.NET Web sites, you might want to enable the following modules:

IIS 6 Management Compatibility module, which enables Visual Studio to use metabase calls to interact with the IIS 7.0 configuration store.
Windows Authentication module, which enables you to debug Web applications in Visual Studio.

For more information, see Running Web Applications on Windows Vista with IIS 7.0 and Visual Studio and Running Web Applications on Windows Server 2008 with IIS 7.0 and Visual Studio.

In this walkthrough, you will make configuration settings by using IIS Manager and then see how the settings are reflected in the Web.config file of a Web application. Tasks illustrated in this walkthrough include the following:

Creating a custom managed-code module and putting the module in the App_Code directory of a Web application.
Registering the custom module by using IIS Manager.
Adding a custom HTTP header by using IIS Manager.

The functionality of the module is not important in this walkthrough. Instead, the walkthrough illustrates how the module is integrated into the request pipeline and how configuring the application by using IIS Manager affects the Web.config file.

Prerequisites

In order to complete this walkthrough, you will need:

IIS 7.0 installed and running on either Windows Vista or Windows Server 2008.
At least one application pool that is running in IIS 7.0 Integrated mode.
The IIS 6 Management Compatibility module enabled in IIS 7.0.
Visual Studio 2008.
The .NET Framework version 3.0 or later.
Administrative permissions on your computer.
A tool to examine HTTP requests and responses between your computer and Web servers, such as the Fiddler tool, which is available from the Fiddler Web Debugging Proxy Web site.

Note

Fiddler is a third-party tool that is not supported by Microsoft.

Creating a Custom HTTP Module

To begin, you will create a new Web site.

To create a new Web site

In Visual Studio, create a new local HTTP Web site named WalkthroughIIS7.

For information about how to create a local IIS Web site, see Walkthrough: Creating a Local IIS Web Site in Visual Web Developer.
On the Start menu, click All Programs, click Accessories, and then click Run.
In the Open box, type inetmgr and then click OK.

Note

If User Account Control (UAC) is enabled, it might display a message when you try to access IIS Manager. If so, click Continue. For more information, see User Account Control.
Verify that the Web site is in an application pool running in Integrated mode.

For information about how to set the mode of a Web application, see Configure the Request-Processing Mode for an Application Pool.

You can now create the custom HTTP module.

To create a custom HTTP module

In Visual Studio, in Solution Explorer, right-click the Web project node and then click Add New Item.

The Add New Item dialog box is displayed.
Under Visual Studio installed templates, select Class.
Select the programming language that you prefer to use.
For the name of the class, enter CustomModule, and then click Add.

If the Web site does not already contain an App_Code folder, a message is displayed that asks whether you want to put the class in the App_Code folder. If so, click Yes.

In the class file, remove the existing code and replace it with the following code:

Imports System
Imports System.Configuration
Imports System.Web
Imports System.Web.Security
Imports System.Web.UI

Public Class CustomModule
    Implements IHttpModule

    Public Sub New()
        ' Constructor
    End Sub

    Public Sub Init(ByVal app As HttpApplication) Implements IHttpModule.Init
        AddHandler app.BeginRequest, AddressOf Me.BeginRequest
    End Sub


    Public Sub BeginRequest(ByVal source As Object, ByVal e As EventArgs)
        Dim app As HttpApplication = CType(source, HttpApplication)
        Dim cont As HttpContext = app.Context
        Dim notification As String = cont.CurrentNotification.ToString()
        Dim postNotification As String = cont.IsPostNotification.ToString()
        cont.Response.Headers.Set("CustomHeader2", "ASPX, Event = " & notification & _
                ", PostNotification = " & postNotification + _
                ", DateTime = " & DateTime.Now.ToString())

    End Sub

    Public Sub Dispose() Implements IHttpModule.Dispose
    End Sub
End Class

using System;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;

public class CustomModule : IHttpModule
{
    public CustomModule()
    {
        // Constructor
    }
    public void Init(HttpApplication app)
    {
        app.BeginRequest += new EventHandler(BeginRequest);
    }
    public void BeginRequest(object source, EventArgs e)
    {

        HttpApplication app = (HttpApplication)source;
        HttpContext cont = app.Context;
        string notification = cont.CurrentNotification.ToString();
        string postNotification = cont.IsPostNotification.ToString();
        cont.Response.Headers.Set("CustomHeader2", "ASPX, Event = " + notification +
                ", PostNotification = " + postNotification +
                ", DateTime = " + DateTime.Now.ToString());

    }
    public void Dispose()
    {
    }
}

The code does the following:

Defines a custom managed-code module that implements the IHttpModule interface.
Defines an event handler for the BeginRequest event of the HttpApplication instance. The event handler defines a custom header to add to the response header collection.
Adds the handler to the request pipeline for notification in the Init method of the module.

Because the class implements the IHttpModule interface, the class must implement an Init method and a Dispose method. The Dispose method in this module has no functionality, but this is where you can implement dispose logic if you need it.

In the Build menu, click Build Web Site to make sure that there are no errors in the module.

As the last task in this section, you will create ASP.NET and HTML pages that will let you test the custom module later in the walkthrough.

To create ASP.NET and HTML test pages

Add a new single-file ASP.NET Web page named ASPXpage.aspx to the root folder of the application.

Remove the existing markup and replace it with the following markup:

<%@ Page Language="VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>ASPX Module Test Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <%= Response.Headers.Get("CustomHeader2").ToString() %>
    </div>
    </form>
</body>
</html>

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>ASPX Module Test Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <%= Response.Headers.Get("CustomHeader2").ToString() %>
    </div>
    </form>
</body>
</html>

Add a new HTML page named HTMLPage.htm to the root folder of the Web application.

Add the following markup to the HTML page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>HTML Module Test Page</title>
</head>
<body>
    <div>
       HTML page.
       <br />
    </div>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>HTML Module Test Page</title>
</head>
<body>
    <div>
       HTML page.
       <br />
    </div>
</body>
</html>

Save all changes.
Run the ASPXpage.aspx page and the HTMLpage.htm page individually to make sure that they can be viewed in a browser.

Note

Leave the Visual Studio application open. You will return to this application to verify configuration changes that you will make by using IIS Manager.

At this point, the pages run but they do not invoke the custom module. In the next procedure, you will add the custom module to the request pipeline.

Making Configuration Changes Using IIS Manager

In this section you will use IIS Manager to make several configuration settings for the IIS application. You will register the custom module, add a custom header, and turn off static compression.

To register the custom managed-code module

On the Start menu, click All Programs, click Accessories, and then click Run.
In the Open box, type inetmgr and then click OK.

Note

If User Account Control (UAC) is enabled, it might display a message when you try to access IIS Manager. If so, click Continue. For more information, see User Account Control.
In the Connections pane, expand the name of the computer or of the server that is hosting the Web site.
Expand the Sites folder.
Select the Web site WalkthroughIIS7. In Windows Server 2008, if the Web application is an application of a Web site, expand that Web site first and then select WalkthroughIIS7.

By default, the center pane of IIS Manager displays Web server configuration options by area. For the WalkthroughIIS7 Web application there are two areas: ASP.NET and IIS.
In the IIS section of the center pane, double-click the Modules icon.

The Modules detail in the center pane shows all the modules that are currently configured for IIS.
In the Actions pane, click Add Managed Module.

The Add Managed Module dialog box is displayed.
Type CustomModule in the Name box.

The name can be any word or phrase that describes the module. In this walkthrough you will use just the name of the module.
In the Type list, select or type the fully qualified name of managed type for the module.

The CustomModule type appears in the list because IIS configuration includes any classes in the App_Code folder that implement IHttpModule.
Make sure that the Invoke only for request to ASP.NET applications or managed handlers check box is not selected.

For this walkthrough, you want the module to apply to all requests in the pipeline, not just ASP.NET requests.
Click OK.

The managed-code module is added to the list of modules. You might have to scroll or re-sort the list to see the added module.

To add a custom response header

In the left pane of IIS Manager, click the name of the WalkthroughIIS7 node to display the main configuration pane for the site.
In the center pane, in the IIS settings section, double-click the HTTP Response Headers icon.

The HTTP Response Headers feature detail is displayed in the center pane. It shows all the HTTP response headers that are currently defined.
In the Actions pane, click Add.

The Add Custom HTTP Response Header dialog box is displayed.
In the Name text box, enter CustomHeader1.

The name can be any word or phrase that describes the header.
In the Value text box, type the value SampleHeader.

You will now turn off static compression. This prevents static content such as the HTML pages from being compressed.

To turn off static compression

Click the name of the WalkthroughIIS7 node in the left pane to view the main configuration pane for the site in the center pane.
In the center pane of IIS Manager, double-click the Compression icon in the IIS settings section.

The Compression feature detail is displayed in the center pane.
Make sure that the Enable static content compression check box is cleared.

Verifying Configuration Changes in Visual Studio

In this walkthrough, you have performed the configuration tasks by using IIS Manager. In this procedure, you will view the changes in the application's Web.config file.

To check the module registration in the Web.config file

Return to the Visual Studio application and to the WalkthroughIIS7 application.
In Solution Explorer, right-click the Web site name and then click Refresh Folder.

This causes the Visual Studio view of the Web site folder to synchronize with the folder and files on disk.

If the application did not originally contain a Web.config file, there is now a Web.config file in the Web application. If the application already had a Web.config file, changes were made to the file.
In Solution Explorer, double-click the Web.config file to view its contents.

The system.webServer section includes the configuration changes that you made by using IIS Manager. The system.webServer section has the following child elements:
- A modules element that registers the custom module for the request processing pipeline.
- An httpProtocol element that defines the custom response header.
- A urlCompression element that disables static compression.
The system.webServer section will resemble the following example:
```
<system.webServer>
  <modules>
    <add name="CustomModule" type="CustomModule" preCondition="" />
  </modules>
  <httpProtocol>
    <customHeaders>
      <add name="CustomHeader1" value="SampleHeader" />
    </customHeaders>
  </httpProtocol>
  <urlCompression doStaticCompression="false" />
</system.webServer>
```
For more information about the system.webServer section, see Using ASP.NET Configuration and IIS 7.0: system.webServer Section Group (IIS Settings Schema).

Testing the Custom Module

IIS 7.0 has an integrated request pipeline. Requests for all application resources (such as an .aspx page or .htm page) can raise pipeline notifications in a managed-code module like the custom module that you have created in this walkthrough.

Note

When you configured the managed-code module in IIS Manager, you did not select the Invoke only for request to ASP.NET applications or managed handlers option. If you had selected this option, the custom module would receive pipeline notifications only for ASP.NET resources and not for static resources such as HTML files.

To verify that the custom module applies to all resources

In Visual Studio, open the ASPXpage.aspx page and press CTRL+F5 to view the page in a browser.

The custom header that is defined in the module is displayed in the browser. In the ASP.NET page, you cannot access the custom header defined by IIS, because this header information is added after the page content has been rendered to the stream. However, you can confirm that the header is set by using a tool that monitors HTTP traffic, such as Fiddler.
Open the HTTP traffic monitoring tool and refresh the ASPXpage.aspx page in the browser.

Note

If the URL for the ASPXpage.aspx page uses localhost, change localhost to the name of the computer that IIS 7.0 is installed on. In a typical development scenario, this is also the computer that Visual Studio is running on.
Verify that CustomHeader1 and CustomHeader2 appear in the headers collection of the response.
View the HTMLPage.htm in a browser.
Verify that CustomHeader1 and CustomHeader2 appear in the headers collection of the response.

Next Steps

This walkthrough provided you with an introduction to the configuration of ASP.NET in IIS 7.0. Configuration settings for the IIS 7.0 Web server and for ASP.NET are unified into one configuration file that you can edit using a single administrative interface.

You might also want to explore additional setting in IIS Manager and how changes are reflected in the configuration file. For more information, see Internet Information Services (IIS)