The ASP.NET Web.config File Demystified Article

Share this article

Key Takeaways

  • The Web.config file in ASP.NET is an XML file that stores configuration settings for web applications. These can include application-wide data such as database connection strings, custom error messages, and culture settings.
  • The Web.config file can consist of any valid XML tags, but the root element should always be . Within this tag, various other tags can be included to describe settings. The file can contain several other section groups apart from system.web and appSettings, such as the configSettings group.
  • A web application can have multiple Web.config files. The settings in a file apply to the directory in which it’s located, and all child directories. Web.config files in child directories take precedence over the settings that are specified in parent directories.
  • Web.config files are protected by IIS, so clients cannot access them. IIS monitors the Web.config files for changes and caches the contents for performance reasons. There’s no need to restart the Web server after you modify a Web.config file.

Applications of XML have been integrated into .NET to such an extent that XML is hardly a buzzword anymore. Microsoft, as you probably know, has taken XML into the core of its .NET framework. Not only is XML a generally accepted format for the exchange of data, it’s also used to store configuration settings.

Configuration settings for any of your ASP.NET Web applications can be stored in a simple text file. Presented in an easily understandable XML format, this file, called Web.config, can contain application-wide data such as database connection strings, custom error messages, and culture settings.

Because the Web.config is an XML file, it can consist of any valid XML tags, but the root element should always be <configuration>. Nested within this tag you can include various other tags to describe your settings. Since a Web.config file comes as a standard when you start to build a new Web application, let’s look at the default XML file generated by Visual Studio .NET:

<?xml version="1.0" encoding="utf-8" ?> 
<configuration>
 <system.web>
   <compilation  
        defaultLanguage="c#"
        debug="true"
   />
   <customErrors  
   mode="RemoteOnly"  
   />  
   <authentication mode="Windows" />  
   <authorization>
       <allow users="*" />
   </authorization>
   <trace
       enabled="false"
       requestLimit="10"
       pageOutput="false"
       traceMode="SortByTime"
   localOnly="true"
   />
   <sessionState  
           mode="InProc"
           stateConnectionString="tcpip=127.0.0.1:42424"
           sqlConnectionString="data source=127.0.0.1;Trusted_Connection=yes"
           cookieless="false"  
           timeout="20"  
   />
   <globalization  
           requestEncoding="utf-8"  
           responseEncoding="utf-8"  
  />
   
</system.web>

</configuration>

Experienced ASP.NET programmers will have noticed that I’ve left out the comment tags that are generated automatically with the file. I’ve done that to provide a clear view of the XML that’s used here. Also, I’ll elaborate on each configuration tag later in this article, and this discussion will make the comment tags rather obsolete.

If you look at the example XML, you’ll notice that the <configuration> tag has only one child tag, which we call section group, the <system.web> tag. A section group typically contains the setting sections, such as: compilation, customErrors, authentication, authorization, etc. The way this works is pretty straightforward: you simply include your settings in the appropriate setting sections. If, for example, you wanted to use a different authentication mode for your Web application, you’d change that setting in the authentication section.

Apart from the standard system.web settings, you can define your own specific application settings, such as a database connection string, using the <appSettings> tag. Consequently, your most common Web.config outline would be:

<configuration> 
 <system.web>
   <! - sections-->    
 </system.web>
 <appSettings>
   <! - sections -->    
 </appSettings >
</configuration>

Let’s discuss the details of both section groups now.

The system.web Section Group

In this section group, you’ll typically include configuration settings that, in the pre-.NET era, you’d have set up somewhere in the IIS administration console. At Microsoft’s MSDN Library, you can find an overview of all the tags that the system.web section group understands, but, depending on the complexity of your site, you may not ever use even half of those options.

Let’s have a look at the most valuable tweaks you can make within the system.web section group, in alphabetical order.

<authentication>

The authentication section controls the type of authentication used within your Web application, as contained in the attribute mode. You’ll enter the value “None” if anyone may access your application. If authentication is required, you’ll use “Windows”, “Forms” or “Passport” to define the type of authentication. For example:

    <authentication mode="Windows" />
<authorization>

To allow or deny access to your web application to certain users or roles, use <allow> or <deny> child tags.

    <authorization> 
       <allow roles="Administrators,Users" />
       <deny users="*" />
   </authorization>

It’s important to understand that ASP.NET’s authorization module iterates through the sections, applying the first rule that corresponds to the current user. In this example, users carrying the role Administrators or Users will be allowed access, while all others (indicated by the * wildcard) will encounter the second rule and will subsequently be denied access.

<compilation>

Here, you can configure the compiler settings for ASP.NET. You can use loads of attributes here, of which the most common are debug and defaultLanguage. Set debug to "true" only if you want the browser to display debugging information. Since turning on this option reduces performance, you'd normally want to set it to "false". The defaultLanguage attribute tells ASP.NET which language compiler to use, since you could use either Visual Basic .NET or C# for instance. It has value vb by default.

<customErrors>

To provide your end users with custom, user-friendly error messages, you can set the mode attribute of this section to On. If you set it to RemoteOnly, custom errors will be shown only to remote clients, while local host users will see the ugly but useful ASP.NET errors -- clearly, this is helpful when debugging. Setting the mode attribute to Off will show ASP.NET errors to all users.

If you supply a relative (for instance, /error404.html) or absolute address (http://yourdomain.com/error404.html) in the defaultRedirect attribute, the application will be automatically redirected to this address in case of an error. Note that the relative address is relative to the location of the Web.config file, not the page in which the error takes place. In addition you can use <error> tags to provide a statusCode and a redirect attribute:

    <customErrors mode="RemoteOnly" defaultRedirect="/error.html"> 
       <error statusCode="403" redirect="/accessdenied.html" />
       <error statusCode="404" redirect="/pagenotfound.html" />
   </customErrors>
<globalization>

The globalization section is useful when you want to change the encoding or the culture of your application. Globalization is such an extensive subject that an entire article could be dedicated to the matter. In short, this section allows you to define which character set the server should use to send data to the client (for instance UTF-8, which is the default), and which settings the server should use to interpret and displaying culturally specific strings, such as numbers and dates.

    <globalization requestEncoding="utf-8" responseEncoding="utf-8"  
       culture="nl-NL" />

Encoding is done through the attributes requestEncoding and responseEncoding. The values should be equal in all one-server environments. In this example, the application culture is set to Dutch. If you don’t supply a culture, the application will use the server’s regional settings.

<httpRuntime>

You can use the httpRuntime section to configure a number of general runtime settings, two of which are particularly convenient.

    <httpRuntime appRequestQueueLimit="100" executionTimeout="600" />

The first attribute specifies the number of requests the server may queue in memory at heavy-traffic times. In the example, if there are already 100 requests waiting to be processed, the next request will result in a 503 error (“Server too busy”).

The executionTimeout attribute indicates the number of seconds for which ASP.NET may process a request before it’s timed out.

<sessionState>

In this section of the Web.config file, we tell ASP.NET where to store the session state. The default is in the process self:

    <sessionState mode="InProc" />

Session variables are very powerful, but they have a few downsides. Information is lost when the ASP.NET process crashes, and sessions are generally useless in the case of a Web farm (multiple Web servers). In that instance, a shared session server can solve your issues. It’s beyond the scope of this article to expand on this topic, but it’s worth a mention. More information on sessionState can be found in the MSDN Library online.

<trace>

Your application’s trace log is located in the application root folder, under the name trace.axd. You can change the display of tracing information in the trace section.

The attributes you will look for initially are enabled: localOnly, and pageOutput.

    <trace enabled="true" localOnly="true" pageOutput="false" />

Set localOnly to “false” to access the trace log from any client. If you set the value of pageOutput to “true”, tracing information will be added to the bottom of each Web page.

The appSettings Section Group

Apart from the Website configuration settings I’ve been talking about in the preceding paragraphs, you’ll know that a programmer frequently likes to use custom application-wide constants to store information over multiple pages. The most appealing example of such a custom constant is a database connection string, but you can probably think of dozens more from your own experience.

The common denominator of these constants is that you want to retrieve their values programmatically from your code. The Web.config file provides the possibility to do so, but as a security measure, these constants have to be included in the <appSettings> section group. Just like <system.web>, <appSettings> is a direct child tag of the Web.config’s configuration root.

A typical custom section group would look something like this:

    <appSettings> 
       <add key="sqlConn" value="Server=myPc;Database=Northwind" />
       <add key="smtpServer" value="smtp.mydomain.com" />
   </appSettings>

The example shows that keys and values can be included in the custom application settings via an <add> tag. The way to access such a value in any of your Web pages is illustrated below:

    ConfigurationSettings.AppSettings("sqlConn")

Yes, it’s as easy as that! Note that the value of these settings is always a String format.

A Few Other Issues

I won’t go into them here, but the Web.config file can contain several other section groups besides the aforementioned system.web and appSettings, such as the configSettings group.

  • A Web application can contain more than one Web.config file. The settings in a file apply to the directory in which it’s located, and all child directories. Web.config files in child directories take precedence over the settings that are specified in parent directories.
  • Web.config files are protected by IIS, so clients cannot get to them. If you try to retrieve an existing http://mydomain.com/Web.config file, you’ll be presented with an “Access denied” error message.
  • IIS monitors the Web.config files for changes and caches the contents for performance reasons. There’s no need to restart the Web server after you modify a Web.config file.
Closing Remarks

In this article, I’ve touched upon the possibilities that the Web.config file offers the ASP.NET programmer. You can use the easily accessible XML file to define your application settings, without the hassle of using the IIS management console. With the Web.config file, ASP.NET lets you add, change and delete basic configuration settings like authentication and authorization, custom error displaying, and tracing in a straightforward manner.

Moreover, the Web.config file offers you room to define any custom key you require, such as database connection strings. What we’ve subsequently seen is that, with just one line of code, you can retrieve the information you need from any page in your application.

Frequently Asked Questions (FAQs) about Web.config File

What is the purpose of the Web.config file in ASP.NET?

The Web.config file is a configuration file for ASP.NET web applications. It is an XML file that contains settings and configuration data for the web application. This includes database connection strings, session state settings, error handling instructions, security settings, and more. The Web.config file is a crucial part of any ASP.NET application, as it allows developers to control various aspects of the application’s behavior without needing to modify the application’s code.

How do I create a Web.config file?

A Web.config file is automatically created when you create a new ASP.NET web application in Visual Studio. However, if you need to create one manually, you can do so by creating a new XML file and naming it “Web.config”. The file should be placed in the root directory of your web application. The content of the file will depend on the specific settings and configurations you want to apply to your application.

Can I have multiple Web.config files in my ASP.NET application?

Yes, you can have multiple Web.config files in an ASP.NET application. In fact, each directory in your application can have its own Web.config file. The settings in these files will apply to the directory in which they are located and all its subdirectories. This allows you to have different settings for different parts of your application.

How do I secure sensitive data in my Web.config file?

Sensitive data, such as database connection strings, should be encrypted to ensure they are not exposed if the Web.config file is accessed by unauthorized users. ASP.NET provides a feature called Protected Configuration that allows you to encrypt sensitive data in your Web.config file. You can use the aspnet_regiis.exe tool provided by .NET Framework to encrypt and decrypt sections of your Web.config file.

What happens if there is an error in my Web.config file?

If there is an error in your Web.config file, such as a syntax error or a reference to a non-existent setting, your ASP.NET application will not run. Instead, an error message will be displayed, indicating that there is a problem with the Web.config file. This is why it’s important to carefully check your Web.config file for errors before deploying your application.

Can I use the Web.config file to customize error handling in my ASP.NET application?

Yes, the Web.config file allows you to customize how your ASP.NET application handles errors. You can specify custom error pages to be displayed for specific HTTP status codes, enable or disable detailed error messages, and more. This can be done in the section of the Web.config file.

How do I use the Web.config file to configure session state in my ASP.NET application?

The Web.config file allows you to configure session state settings for your ASP.NET application. This includes specifying the session state mode (InProc, StateServer, or SQLServer), setting the session timeout value, and more. These settings can be configured in the section of the Web.config file.

Can I use the Web.config file to control access to my ASP.NET application?

Yes, the Web.config file allows you to control access to your ASP.NET application. You can specify which users or roles have access to certain parts of your application, and you can also deny access to certain users or roles. This can be done in the section of the Web.config file.

How do I use the Web.config file to configure caching in my ASP.NET application?

The Web.config file allows you to configure caching settings for your ASP.NET application. This includes setting the cache expiration policy, specifying the location of the cache, and more. These settings can be configured in the section of the Web.config file.

Can I use the Web.config file to configure URL rewriting in my ASP.NET application?

Yes, the Web.config file allows you to configure URL rewriting rules for your ASP.NET application. This can be useful for improving the SEO of your application, among other things. URL rewriting rules can be configured in the section of the Web.config file.

Ruben HeetebrijRuben Heetebrij
View Author

Ruben is a senior software engineer and team manager for Capgemini in the Netherlands. He is specialized in Web development and Visual Basic applications.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week