Microsoft Corporation
October 2003

Applies to:
    Microsoft® ASP.NET
    Microsoft Visual Studio® .NET
    Java Server Pages (JSP)

Summary: Learn about configuration elements in Java and ASP.NET. (11 printed pages)


The Java Web.xml File
Converting a Web.xml File
The .NET Web.config File


Web applications in both Java and Microsoft® ASP.NET store configuration information in XML files. These XML files are stored inside the deployment archives so that configuration settings are maintained when applications are moved from one machine to another. However, in many cases you may need to change the configuration of your applications once they have been deployed on production Web servers, either because the Web servers' environment differs from the development environment or simply because your needs have changed. In either case, in order to reconfigure you application you will need to understand the structure and purpose of the various elements and attributes found in the XML configuration files. This article will introduce you to some of the more commonly modified configuration elements in both JSP and ASP.NET.

The Java Web.xml File

Configuration options for JSP/servlet Web applications are stored inside a file called Web.xml, which you will find in the WEB-INF directory under your application's root directory. Web.xml is often referred to as the deployment descriptor for JSP/servlets. This file is used to tell the Web server where the various parts of the application can be found, how to access them and, sometimes, who can access them. Note that this configuration file may not be the only one available in the WEB-INF directory. Many Web servers require additional proprietary configuration files, which will also need to be included in WAR archives when the application is deployed (assuming you are deploying the application to the same server application with which you developed it).

Additionally, Web servers may store configuration files in directories outside the file structure of the Web application itself. Tomcat, for example, can store user names and passwords in a special XML document called Tomcat-users.xml. Tomcat also has its own Server.xml file with default settings that are processed and then overridden (if necessary) by the Web.xml for your own application. As you can see, you must be certain that you know where all the necessary configuration files are for any Web application you plan to deploy, and be prepared to move or duplicate settings manually when necessary if they are not included in the WAR file.

This section of the article will discuss some of the commonly used elements in web.xml files. An excellent complete resource on the web.xml file can be found at web.xml Deployment Descriptor Elements.

A Simple Web.xml File

Listing 1 shows a simple Web.xml file for an application that exposes a single servlet class named HelloServlet. As you can see, Web.xml is an XML document, and references a DTD that dictates what elements it can contain and how they should be structured. The XML declaration and DOCTYPE declaration shown here, as well as the <web-app> root element, are typical of all Web.xml files. The other elements, such as <servlet> and <servlet-mapping>, will be discussed in the sections that follow.

Listing 1. A simple Web.xml file

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web

Application 2.2//EN" "">











Registering a Servlet with the <servlet> Tag

Every servlet deployed as a part of your Web application must have a <servlet> element specifically for it in the Web.xml deployment descriptor. This element describes the servlet and its behavior, so that the Web server can find it and expose it to the client. The <servlet> tag has no attributes, but it does have a set of both required and optional child elements.

Required elements

The following are the two required child elements of a <servlet> element:

  • <servlet-name> contains the name of the servlet, which is used to reference it from elsewhere in Web.xml.
  • <servlet-class> contains the fully qualified class name of the servlet. Remember that all servlet classes will be contained in the WEB-INF\classes directory, so that the servlet name is relative to that directory.

Optional elements

The following are some of the optional elements that can exist within a <servlet> element:

  • <description> provides a text description of the servlet, for documentation purposes.
  • <display-name> can be used to provide a name that will be displayed by a GUI interface, if one exists.
  • <icon> can be used to indicate the location of images that will represent the servlet in a graphical interface, if one exists. This element can in turn contain <small-icon> and <large-icon> elements.
  • <jsp-file> allows you to specify a full path to a JSP page (relative to the Web application root directory). This element replaces the <servlet-class> element mentioned previously; both cannot exist inside the same <servlet> element. Note that you do not have to reference JSP pages in this way in order for them to work.
  • <load-on-startup> allows you to indicate the order in which servlets should be loaded when the server is started up. This element should contain a positive integer; servlets will be loaded from lowest to highest value according to this element. If you do not include a <load-on-startup> element, servlets can be loaded in any order. Note that if you use the <jsp-file> element in combination with a <load-on-startup> element, the JSP referred to will be precompiled instead of being read on-the-fly when accessed.
  • <init-param> is perhaps the most important and useful of the optional elements. It allows you to provide startup parameters for your servlet. You can use this tag to declaratively provide information to your servlet, such as debug level or resource names.

Mapping the Servlet with <servlet-mapping>

Each <servlet> element must have a corresponding <servlet-mapping> element that maps the servlet to a URL pattern. This URL pattern can then be used to access the servlet. <servlet-mapping> has two required child elements:

  • <servlet-name> must correspond to a <servlet-name> element in a <servlet> element. This indicates which servlet is being mapped to the URL.
  • <url-pattern> contains the URL pattern that will be added to your host name/application name URL and used as a unique URL for the servlet. For example, if our host name was and our application name was TestApplication, we could specify <url-pattern>/example1</url-pattern> to have the indicated servlet resolve at the URL


The <session-config> element allows you to specify how long a session with this Web application lasts. <session-config> contains a single child element, <session-timeout>, whose value should be an integer representing the session length in minutes. Listing 2 shows an example of a <session-config> element indicating that sessions on this application will last for five minutes.

Listing 2. A <session-config> element




In addition to positive integers representing minute values, <session-timeout> allows two special values. A value of -1 indicates that the session does not time out (in other words, the session is of infinite length). A value of -2 indicates that this configuration file should defer to the default configuration file maintained by the server application to determine how long sessions last.


The <error-page> element allows you to map HTTP error codes or Java exceptions to specific pages, so that you can provide users with customized error messages.

Every <error-page> element must contain a <location> element that indicates the page to display as an error message, the location of which is relative to the root of the application. In addition, <error-page> elements must contain either an <error-code> element (which contains a valid HTTP error code) or an <exception-type> element (which contains a fully qualified Java exception class), but not both.

Listing 3 shows an example of an <error-page> element that will forward the user to a page called Error.htm if a page cannot be found within the application boundaries.

Listing 3. An <error-page> element






This element allows you to define security (authentication and authorization) constraints for servlets and JSP pages that make up your application. You can find more information on authentication and authorization in the Authentication article, which is included in this migration guide.


This element is typically used to indicate what method is used to authenticate a user, and (if authenticating using a forms-based interface) where the login and error pages can be found.

Converting a Web.xml File

In a .NET Web application, most of the configuration information is stored in a file called Web.config. This file serves several of the same purposes as Web.xml, although there is not a complete overlap. If you break apart a Web.xml file, you really have the following sections:

  • Servlet registration, initialization and mapping
  • Tag library registration
  • Security information
  • Startup page information

Of these four areas, only the security section has direct mappings between the files.

The Java Language Conversion Assistant (JLCA) will ignore your existing Web.xml file, so you will have to convert the content manually. Fortunately, most of the content from Web.xml is not required in an ASP.NET Web application. However, the few pieces that are required (servlet initialization, security and startup) can easily be accommodated in the Web.config file.

The .NET Web.config File

The Web.config XML file is basically the ASP.NET equivalent of Web.xml. It is automatically generated by Microsoft® Visual Studio® .NET for each Web application project you create, and can be found with the rest of the application's files in the Solution Explorer in Visual Studio .NET. Web.config has some default settings that are always included upon generation, but you are free to modify, add, and remove settings as you see fit. When you deploy your ASP.NET Web application using an MSI file, you should always be sure that the Web.config file is included.

A Sample Web.config File

Listing 4 shows an example of a simple Web.config file. In fact, this is the default Web.config file generated by Visual Studio .NET for a brand new C# ASP.NET Web application (with all of the comments removed and extra spacing and indentation added for legibility).

Listing 4. A simple Web.config file

<?xml version="1.0" encoding="utf-8"?>



<compilation defaultLanguage="c#" debug="true" />

<customErrors mode="RemoteOnly" />

<authentication mode="Windows" />

<trace enabled="false" requestLimit="10"

pageOutput="false" traceMode="SortByTime"

localOnly="true" />

<sessionState mode="InProc"


sqlConnectionString="data source=;user id=sa;password="

cookieless="false" timeout="20" />

<globalization requestEncoding="utf-8"

responseEncoding="utf-8" />



Notice that, like Web.xml, Web.config begins with an XML declaration. It does not, however, reference a DTD. All Web.config files have a root element named <configuration>. This element can actually have two child elements: <appSettings> and <system.web>. This article will only cover the contents of <system.web>, as <appSettings> is rarely used, and then only for application-specific settings. <system.web> contains all of the ASP.NET-specific settings.

We will discuss some of the child elements of <system.web> as well as some additional useful elements in the sections that follow. A full reference for the XML grammar configuration file can be found on MSDN®.


The <authentication> element allows you to customize the authentication mode and functionality for your ASP.NET pages. <authentication> has one attribute, mode, whose value must be the type of authentication you want performed for your site (either WINDOWS, FORMS, PASSPORT, or NONE).

In addition, <authentication> can have one of two child elements. <forms> allows you to specify URLs, protection schemes, and credentials for forms-based authentication. You can find more information on forms-based authentication in the Authentication article, contained within this migration guide.

The <passport> element is an empty element with a single attribute named redirectUrl. If you are using Passport authentication, the value of redirectUrl should be the URL of a page to which you want the user forwarded if the page requires authentication and the user has not yet signed on using his or her Passport credentials.


The <authorization> element lets you allow or deny users using their names, roles, or HTTP verbs as filters. Generally, the <authorization> element contains two children—<allow> and <deny>—each of which has up to three attributes (users, roles, and verbs). For example, the <authorization> element in Listing 5 would allow only users calling the page using HTTP POST and who are in the group goodUsers, and deny all others access.

Listing 5. A sample <authorization> element


<allow roles=goodUsers

verbs=POST />

<deny users=*


verbs=* />



The <compilation> element is used to contain all of the settings that tell ASP.NET how to compile your ASP.NET pages and how to treat them once they are compiled. If you look at Listing 4 you can see that, by default, the <compilation> element contains a defaultLanguage attribute that specifies what language the CodeBehind file is written in, and a debug attribute, which allows you to indicate whether you want to compile debug binaries (in other words, those not intended for publication to a Web server) or release binaries.


<compilation> has many other attributes, some of which you will find useful to modify:

  • batch indicates whether batching is supported (must be true or false).
  • batchTimeout indicates the time, in seconds, before a batch operation times out.
  • numRecompilesBeforeApprestart indicates how many times the resources for the application can be compiled before the application itself must restart.
  • tempDirectory indicates the directory used for temporary file storage during compilation.


In addition, <compilation> supports two child elements: <compilers>, which allows you to customize what compiler is used to compile files with particular extensions, and <assemblies>, which allows you to include or remove assemblies at compilation time.


This element allows you to customize error handling for your ASP.NET pages. <customErrors> can have two attributes:

  • mode indicates how errors should be handled. A value of ON indicates that custom error handling is on, a value of OFF indicates that custom error handling is off, and a value of REMOTEONLY indicates that custom errors will only be shown to remote clients and not to users on the local host.
  • defaultRedirect allows you to specify a URL to which the user will be forwarded should an error occur, unless any special handling is provided for the specific error code (we will discuss this shortly). Obviously, this attribute is only useful if the mode attribute is set to ON or REMOTEONLY.

In addition, <customErrors> can contain any number of <error> elements, each of which provides a statusCode and a redirect attribute. <error> elements allow you to customize error handling for specific HTTP error codes. For example, Listing 6 shows a <customErrors> element that sends the user to defaultError.htm for all errors except HTTP 404 errors, in which case it sends the user to http404error.htm.

Listing 6. A sample <customErrors> attribute

<customErrors mode=On


<error statusCode=404 redirect=http404error.htm />



The <sessionState> element allows you to configure session settings for your ASP.NET pages. <sessionState> is an empty element, and supports the following attributes:

  • mode specifies where the session state will be stored. This attribute is required. Options for values are: OFF (no session state); INPROC (stored locally); STATESERVER (stored on a remote server); SQLSERVER (stored on a SQL server).
  • cookieless is a boolean attribute which indicates whether or not cookies should be used to identify sessions. (The default is FALSE.)
  • timeout allows you to provide an integer representing the time, in minutes, before a session times out and the user must re-authenticate. (The default is 20.)
  • stateConnectionString specifies the location of the remote server to be used if mode=StateServer.
  • sqlConnectionString specifies a connection string for the SQL server being used to store state, assuming mode=SQLServer.

Servlet Parameters

You may recall that a Web.xml file can contain initialization parameters for servlets that can be accessed through the ServletContext object. In ASP.NET, the functional equivalent is to store your startup parameters in your own section of the Web.config file. The Web.config file allows you to add your own configuration sections so that you can store application-specific information, such as servlet parameters, in the Web.config file in addition to the information contained in the <appSettings> and <system.Web> sections. Information for user-defined sections is stored in two areas of the Web.config file: the section handler declaration area and the section settings area.

The section handler declaration area is contained within the <configSections> and </configSections> tags just after the <configuration> tag at the top of the Web.config file. These <configSections> tags are not automatically created by Visual Studio .NET because they are necessary only when adding your own configuration section. For each user-defined configuration section, there must be an accompanying <section> element in the <configSections> element. <section> elements have two attributes: name and type. name attributes must be unique among all configuration sections. The type attribute lists the class name and assembly of the .NET Framework class that should be used to process data in the configuration section. In order to refer to the .NET Framework class, you must provide the namespace-qualified class name, as well as the assembly name, version, culture, and public key. For example, to define a configuration section called InitParams that should be handled by a NameValueFileSectionHandler object, you would add the following XML at the top of your Web.config file:

Listing 7. Creating a sample configuration section

<!-- immediately after the <configuration> element -->


<section name="InitParams"

type="System.Configuration.NameValueFileSectionHandler, System,

Version=1.0.3300.0, Culture=neutral,



A NameValueFileSectionHandler is used to handle almost all configuration sections because it allows you to access the information in a name-value relationship, similar to the functionality provided by a hash table. Notice the format for the type attribute. It must always follow the classname, assemblyName, Version=version#, Culture=culture, PublicKeyToken=publickeytoken format. When using the NameValueFileSectionHandler for your configuration sections, you can use the exact same code as Listing 7, because the NameValueFileSectionHandler is included as part of the .NET Framework.

Once you have defined your configuration section, you place your configuration section between the opening and closing <configuration> tags. When defining multiple configuration sections, they can appear in any order within the <configuration> tags, provided that they appear after the <configSections> element and that they do not overlap with any other configuration sections. For example, to add the parameter validate with a value of true to the InitParams section we defined in Listing 7, you would place the following after the </configSections> tag:

Listing 8. A sample configuration section


<addkey="validate" value="true"/>


Now that you have created and entered information into the configuration section, you need to retrieve it from your code. This is a two-step process. First, you call the System.Configuration.ConfigurationSettings.GetConfig() method to retrieve all information for the configuration section. When using a NameValueFileSectionHandler to process the data in your configuration section, the GetConfig() method will return a NameValueCollection object. However, as previously mentioned, configuration sections can be set up to have different types of classes process the data in their section, so you must cast the value returned by GetConfig() to a NameValueCollection object. Once you have the NameValueCollection object, you can retrieve the values stored within the configuration section simply by indexing on the parameter's name, as shown in Listing 9.

Listing 9. Retrieving the value of validate from the Web.config file


System.Collections.Specialized; // NameValueCollection


System.Configuration; // ConfigurationSettings




= (NameValueCollection)



value = InitParams["validate"];

In short, converting from a servlet configuration in Web.xml to an aspx configuration in Web.config is not very difficult.

Editing Web.config the Easy Way

Editing Web.config manually can sometimes be a tedious process, as the configuration files for large applications can be large and unwieldy. Fortunately, there is an easier way. HunterStone's Web.Config Editor is a GUI application specifically for editing Web.config XML files. You can open a Web.config file for any application in the editor, which will then allow you to select various sections and make changes to settings using standard Windows controls.

At the time of this writing, the full version of the Web.Config Editor is available free provided you are willing to visit one of HunterStone's sponsors to get a discount code. Otherwise, registration is $50.


Web applications in both JSP and ASP.NET use XML configuration files to indicate the location and setup of the various services available in the application. When deploying Web applications to a remote machine, you need to make sure you include these configuration files and that you modify them to adapt to the new environment.

The configuration file for JSP/servlets is called Web.xml, and can usually be found in the WEB-INF directory underneath the root directory for the application. Visual Studio .NET automatically generates Web.config for every new ASP.NET application. Both of these files can be modified using ordinary text editors or XML editors. In addition, HunterStone's Web.Config Editor is available and makes modifying configuration settings for ASP.NET applications much easier.

Unfortunately, the current version of the JLCA will not convert your Web.xml deployment descriptor to the equivalent Web.config settings. Although some portions map directly, you may need to find alternative means to store some of your information.