How to: Configure the <system.webServer> Section for IIS 7.0

The system.webServer section in the Web.config file specifies settings for IIS 7.0 that are applied to the Web application. The system.WebServer is a child of the configuration section. For more information, see IIS 7.0: system.webServer Section Group (IIS Settings Schema).

Examples of Web server settings that you can make in the system.WebServer configuration group are as follows:

• The default document that the Web server returns to a client when a request does not include a specific resource (defaultDocument element).

• The compression settings for responses (httpCompression element).

• Custom headers (customHeaders element of the httpProtocol section).

• Modules (modules element).

• Handlers (handlers element).

Some settings in the system.webServer section apply only to IIS 7.0 Integrated mode and do not apply to Classic mode. In particular, any managed-code modules and handlers specified in the system.WebServer section of the Web.config file are ignored if the application is running in Classic mode. Instead, the managed-code modules and handlers must be defined as in earlier versions of IIS, in the httpModules and httpHandlers elements of the system.web section.

This topic illustrates three common configuration tasks that require modifications to the system.webServer section:

• Adding a default file so that when a request URL does not include a specific file, the default file is served.

• Registering a managed-code module.

• Adding a custom response header.

Configuring a Default File

A default file is served by IIS 7.0 when a request URL does not include a specific file of the Web application.

To configure a default file

1. If your application does not have a Web.config file, create one in Visual Studio or with a text editor.

   For more information, see Editing ASP.NET Configuration Files.

2. If the Web.config file does not already contain a system.webServer section, create one inside the configuration element, as shown in the following example:

   <configuration>
     <system.webServer>
     </system.webServer>
   </configuration>
   

3. Create a defaultDocument element inside the system.webServer element.

4. Create a files element inside the defaultDocument element.

5. Create an add element inside the files element and in the value attribute, specify the path and name of the default file.

   The following example shows a system.webServer section that is configured to serve the Products.aspx file as a default file.

   <configuration>
     <system.webServer>
       <defaultDocument> 
         <files> 
           <add value="Products.aspx" /> 
         </files> 
       </defaultDocument>
     </system.webServer>
   </configuration>
   

Registering a Managed-code Module

A managed-code module is invoked on every request and lets you customize the request or the response.

To configure a custom managed-code module

1. If the application does not have a Web.config file, create one in Visual Studio or with a text editor.

   For more information, see Editing ASP.NET Configuration Files.

2. If the Web.config file does not already contain a system.webServer section, create one inside the configuration element, as shown in the following example:

   <configuration>
     <system.webServer>
     </system.webServer>
   </configuration>
   

3. Inside the system.webServer element, create a modules element.

4. Create an add element inside the modules element, and in the name and type attributes, specify the custom module.

   The actual name and type depend on the module you are adding. The following example shows how to add a custom module named CustomModule, which is implemented as the type Samples.CustomModule.

   <configuration>
     <system.webServer>
       <modules> 
         <add name="CustomModule" type="Samples.CustomModule" /> 
       </modules>
     </system.webServer>
   </configuration>
   

5. Add a precondition attribute to the module registration and set its value to managedHandler.

   The precondition causes the module to be invoked only for requests to the ASP.NET application resources, such as .aspx files or managed handlers. This excludes static files like .htm files.

   The configuration section will resemble the following example.

   <configuration>
     <system.webServer>
       <modules>
         <add name="CustomModule" type="Samples.CustomModule" 
              precondition="managedHandler" />
       </modules>
       <defaultDocument>
         <files>
           <add value="Products.aspx" />
         </files>
       </defaultDocument>
     </system.webServer>
   </configuration>
   

Configuring a Custom Response Header

A custom response header lets you send application-specific information to the browser. For example, you can add a Content-Language header to describe the language that is used in the body of the Web page. To dot his, you provide one or more language and country/regions values such as en-US (United State English) or en-GB (British English).

To configure a custom response header

1. If your application does not have a Web.config file, create one in Visual Studio or with a text editor.

   For more information, see Editing ASP.NET Configuration Files.

2. If the Web.config file does not already contain a system.webServer section, create one inside the configuration element, as shown in the following example:

   <configuration>
     <system.webServer>
     </system.webServer>
   </configuration>
   

3. Inside the system.webServer element, create an httpProtocol element.

4. Inside the httpProtocol element, create a customHeaders element.

5. Create an add tag inside the customHeaders element, and in the name and value attributes, specify that define the custom header.

   The actual name and value depend on the function of the header in the application. The following example shows how to add a custom header named CustomHeader whose value is CustomHeader.

   <configuration>
     <system.webServer>
       <httpProtocol> 
         <customHeaders> 
           <add name="CustomHeader" value="CustomHeader" /> 
         <customHeaders> 
       </httpProtocol>
     </system.webServer>
   </configuration>
   

See Also

Reference

configuration Element (General Settings Schema)

Concepts

Moving an ASP.NET Application from IIS 6.0 to IIS 7.0

Other Resources

Walkthrough: Configuration ASP.NET Applications in IIS 7.0