In contrast to IIS 6.0, when editing configuration
with tools like the IIS Manager and Appcmd, or programmatically with
APIs like Microsoft.Web.Administration, the underlying configuration
system APIs will make sure that the resulting configuration is correct.
This will catch
most attempts to produce incorrect configuration, including using data
of the wrong type for attribute values, attempting to set nonexisting
attributes, or using data out of range of accepted values. It will even
prevent you from adding a duplicate collection element or attempting to
write configuration that has been locked at a parent configuration
level. This is the reason why you should always prefer to use tools to
write configuration, rather than doing it manually.
Note
Use tools to set configuration—this will catch most mistakes and prevent you from generating incorrect configuration. |
However, there are times
when you may still run into a situation in which configuration is
incorrect. This is most likely if you edit configuration by hand and
make a mistake in the section syntax or set attributes to unsupported
values. However, it may also happen in other cases—for example, if an
application that defines configuration is deployed to a server where
some of the sections are locked at the server level, resulting in a lock
violation.
Because of this, it
is important to be able to understand various configuration error
conditions, and be able to use the resulting configuration error
information to resolve them.
There are several
types of configuration errors that are handled differently by the
configuration system and have varying degrees of impact on IIS. Table 1 summarizes some of the common error conditions and the impact they have on the server.
Table 1. Common Error Conditions
| Error | Impact |
|---|
| Configuration file is not valid XML | If Framework machine.config, root web.config, or IIS 7.0’s applicationHost.config: the entire server will be taken offline. Otherwise: All URLs corresponding to the configuration file and below will return configuration errors.
|
| Configuration file cannot be accessed: The file is locked by another process, access denied, no network connectivity for UNC paths. | If Framework machine.config, root web.config, or applicationHost.config: the entire server will be taken offline. Otherwise: All URLs corresponding to the configuration file and below will return configuration errors.
|
| Configuration section syntax error: The configuration section has unexpected elements or attributes, or it is missing required attributes. | If
the error is in one of the system.applicationHost configuration
sections that are read by WPAS, the server may be taken offline. If
the error is in one of the core Web server sections, all requests to
the URLs affected by the errors will return configuration errors. Otherwise, requests that use features that read the configuration section will return configuration errors.
|
| Attribute validation error: There is an invalid data type; value fails attribute validation rules. | Same as above. |
| Collection validation error: There are duplicate collection elements. | Same as above. |
| Lock violation: Specifying configuration for the section or attribute that is locked at a parent level. | Same as above. |
The key to
understanding these error conditions is to understand how the
configuration system handles errors. Errors that cause the entire
configuration file to become unavailable, because it cannot be read or
because it contains invalid XML (as shown in Figure 1),
cause all attempts to read configuration from that file to fail.
Because of this, all operations that require reading this file will
fail—if this file is applicationHost.config, which is read by the
Windows Process Activation Service component of IIS that is responsible
for managing IIS worker processes, the entire server will be taken
offline. In this case, you will not be able to get a detailed request
error describing the error condition, because the server will not be
able to start any IIS worker processes to serve the request. In this
case, the error information will be logged by WPAS to the System
EventLog.
If the file is a
distributed web.config file that corresponds to a particular URL
namespace, that namespace will not be available. However, IIS worker
processes will still be able to start and generate a detailed
configuration request error that will describe the reason, and sometimes
even the position in the file, where the error has occurred.
Finally, for all
other errors in configuration sections that are not invalid XML, only
accesses to the affected section will fail. If the error is in one of
the system.applicationHost sections that are read by WPAS, including
<sites> and <applicationPools>, WPAS may again fail to start
IIS worker processes, resulting in the entire server being offline and
errors being logged to the System EventLog. If the error is in one of
the core IIS configuration sections that are read on every request,
which include <serverRuntime>, <modules>, and
<handlers>, all requests to the URL namespace corresponding to the
invalid configuration will return configuration errors. These errors
will contain the exact reason why the configuration access failed,
including details such as the line number and the element or attribute
in question that has incorrect configuration, as shown in Figure 2. You can use this information to quickly pinpoint the location of configuration syntax error and resolve it.
Note
To see the detailed configuration error, you will need to either make a request locally on the server or enable detailed errors. |
For all other
sections, only requests that use features whose configuration has the
error will trigger request errors. This also means that if you make a
mistake in configuration for a feature that is not being used (for
example, the module is disabled), no error will be given and invalid
configuration will remain ignored.
Finally, if the error is in
an ASP.NET configuration section, which is read by the ASP.NET using
the .NET configuration system, you may get an ASP.NET exception error
page containing the configuration error details.
Note
To
see the detailed ASP.NET configuration exception, you will need to
either make a request locally on the server or enable ASP.NET detailed
errors. |
