To set configuration, you need to know three things:
the name of the section that contains the desired configuration
settings, the desired property of that section, and the configuration
path at which you want to set this setting to apply (as we discussed in
the previous section). You will typically know the first two from the
documentation of the feature you are attempting to configure. For more
information about what configuration sections are available and their
format, you can consult the schema files in the
%windir%\system32\inetsrv\config\schema directory.
When you know this information, you can specify the corresponding section element in the configuration file.
<configuration>
<system.webServer>
<defaultDocument ... />
</system.webServer>
<configuration>
Note the
<configuration> element—this must always be the root element of
any configuration file. Also, notice the <system.webServer>
element—this is the section group element for the
<defaultDocument> section (and all other IIS 7.0 configuration
settings) that is being configured.
Configuration sections contain the properties that you intend to configure, such as defaultDocument,
but you need to do more than just provide a name. You turn the default
document feature on and off and provide the list of default documents
using attributes or collection elements contained inside the section.
Setting Section Attributes
The majority of
configuration settings are expressed via attributes, which may either be
exposed on the collection element itself or in one of the child
elements of the collection.
To specify a value for
the attribute, you simply need to set the value of that attribute. This
effectively overrides any default value or value previously set to this
attribute in earlier configuration paths. Following is an example of
setting the enabled value on the <defaultDocument> section.
<defaultDocument enabled="true" />
Each attribute has a
specific type and may have additional validation rules associated with
it in the schema definition of the section. Likewise, attributes may be
given default values that are taken on by them if they are not
explicitly set in configuration. This will be documented for each
section to assist you in setting their values.
Manipulating Configuration Collections
In addition to
attributes, configuration sections can also contain collections.
Collections allow lists of items to be represented in configuration, and
they support additional behaviors such as adding or removing elements
in multiple configuration levels and preventing duplicate items from
being added.
Collections are
typically configured through three different operations: adding
collection elements, removing collection elements, and clearing the
collection.
Adding Items to a Collection with <add />
To add items to a
collection, you typically use the <add /> element and specify the
desired attribute values inside of it. For example, following is an
excerpt from the <files> collection of the <defaultDocument>
section specified in applicationHost.config after installation.
<defaultDocument enabled="true">
<files>
<add value="Default.htm" />
<add value="Default.asp" />
...
</files>
</defaultDocument>
In this case, elements in
the <files> collection only support a single attribute called
“value”. However, collection elements are not limited to a single
attribute—they can define any number of
attributes, child elements, or even subcollections. In fact, each
collection element has the same schema flexibility as any other
configuration element or the section itself. Following is an example
from the <sites> section.
<sites>
<site name="Default Web Site" id="1">
<application path="/">
<virtualDirectory path="/
" physicalPath="%SystemDrive%\inetpub\wwwroot" />
</application>
<bindings>
<binding protocol="http" bindingInformation="*:80:" />
</bindings>
<traceFailedRequestsLogging enabled="true" />
</site>
</sites>
The <sites>
section is a collection of <site> elements (notice that it uses
<site> as the name for its <add> element—this is a
capability provided by the IIS configuration schema that some sections
take advantage of for readability). Each <site> element in turn is
a collection of <application> elements, which in turn contain a
collection of <virtualDirectory> elements. Each <site>
element also has a <bindings> child element, which itself is a
collection of site bindings.
Luckily, the
<sites> section is the most complicated section on the entire IIS
7.0 configuration schema, and most other sections are a lot simpler.
Most collections
enforce item uniqueness to prevent duplicate items from being added.
This is done by marking one or more of the attributes allowed on the
collection <add> elements as the collection key. If an item with a
duplicate key is specified, the collection will trigger a configuration
error when accessed.
When you add
collection elements at a particular configuration level, they add to the
existing elements that were inherited from a parent level. For example,
the <defaultDocument> section can use this to specify a base set
of default documents in applicationHost.config and then add specific
default documents at the site or virtual directory levels.
The ordering of
collection items inside a collection is determined by the order in
which they are added. When collection items are inherited from the
parent configuration levels, they are placed before the collection items
specified at the current level. This is true for most collections,
except for collections that elect to have a prepend order—these
collections place the elements declared at the current level before
elements inherited from parent levels. These include the IIS
<handlers> and the ASP.NET <authorization> sections.
Removing Items from a Collection with <remove />
Because of the collection
inheritance, it is sometimes necessary to remove elements that are
declared at a higher configuration level. For example, you may want to
remove a specific module from the <modules> configuration collection for a specific application if you do not need this module to run.
Note
If
you are removing a collection element that is added at the current
configuration level, you can simply delete the corresponding <add>
element. Use <remove> to remove the elements that are specified
by parent configuration levels. |
To do this, you can use
the <remove> element. Each remove element specifies the attributes
that together comprise the collection key to uniquely identify the
element that is to be removed. For example, following is the
configuration you can use to remove “Default.asp” from the <files>
collection of the <defaultDocument> section.
<defaultDocument>
<files>
<remove value="Default.asp" />
</files>
</defaultDocument>
Clearing the Collection with <clear />
Sometimes you may want
to completely clear the collection items that are defined by the parent
configuration levels and specify only the items that are required. This
is often done whenever the current configuration level has to have
complete control over the contents of the collection and cannot inherit
parent items.
This is accomplished with
the <clear/> element. The <clear/> element removes all of
the inherited collection items, leaving only the items that are added at
the current level after the <clear/> element. The following
example clears the default document collection and adds back a single
element to make sure that only Default.aspx is treated as a default
document.
<defaultDocument>
<files>
<clear/>
<add value="Default.aspx" />
</files>
</defaultDocument>
Important
Be
careful when using the <clear/> element, however, because it
completely stops the inheritance of parent collection items to the
current configuration level or its children. This means that if the
administrator adds new collection items at the server level, they will
not be propagated to the current level. Therefore, use <clear/>
only when you want to take complete control over the contents of the
collection. |
