IIS 7.0 : Using Command Line Tools - Working with Configuration

Editing IIS 7.0 configuration is a key task for Appcmd. Appcmd commands are a great way to encapsulate configuration changes such that you can show them to other users, save them for future use, or use them to quickly automate management tasks. This is why, when showing how to perform them using IIS Manager is too time-consuming, the IIS 7.0 online help documentation uses Appcmd to show how to perform most configuration tasks.

Though you can manage the configuration for key Web server objects—such as the Web site, application, virtual directory, and application pools—through the corresponding Appcmd-friendly objects, the majority of configuration sections are not exposed through friendly objects. Instead, you use the Config object to manipulate configuration settings. By using the Config object, you can edit any configuration section exposed through the IIS 7.0 configuration stack (built-in or third-party).

The Config object supports the verbs listed in Table 1.

Table 1. Supported Verbs for the Config Object

Verb	Description
List	Show the configuration for any specific configuration section, for any URL or configuration path
Set	Set the configuration for any specific configuration section, for any URL or configuration path
Search	Find where the configuration is defined
Lock	Lock a specific configuration section to prevent it from being delegated to child configuration levels
Unlock	Unlock a specific configuration section to prevent it from being delegated to child configuration levels
Clear	Clear a particular configuration section, collection, or attribute
Reset	Used by Window Setup to restore each built-in configuration section to setup default; do not use this command
Migrate	Migrate ASP.NET configuration sections to an IIS configuration for running in Integrated pipeline

You can use the List Config command to display the effective configuration for a specific URL or configuration path, either in its entirety or for a specific configuration section. You can use the Set Config command to set the configuration for a specific URL or configuration path for a specific configuration section. Finally, you can use the Clear Config command to clear the configuration for a specific section, at the specified URL or configuration path. You can also manage the delegation state of configuration sections by using the Lock Config and Unlock Config commands. 

Most of the configuration commands enable the use of the identifier, which for the Config object represents the configuration path for which you are performing the command. By default, if the identifier is not specified, it defaults to MACHINE/WEBROOT/APPHOST, which targets the configuration to the Web server level in the applicationHost.config file. You can specify the identifier as both a configuration path in the format of SiteName/UrlPath (for example, "Default Web Site/myapp") or as a normal URL (for example, http://localhost/myapp). If you are using the former, Appcmd will automatically append the "MACHINE/WEBROOT/APPHPOST" prefix to form the configuration path. If you are using the latter, Appcmd will resolve the URL to a configuration path by using the Web site bindings.

For example, to display the effective settings for the system.webServer/asp section at http://localhost/myapp, you can use the following command.

appcmd list config "Default Web Site/myapp"

Or you can use this command.

appcmd list config "http://localhost/myapp"

Viewing Configuration with the List Config Command

To view a configuration, you can use the List Config command. This command has the following syntax.

appcmd list config ConfigurationPath [/section:SectionName]

ConfigurationPath is the configuration path or URL at which Appcmd will read configuration. If you omit it, Appcmd will read configuration at the Web server level, using the "MACHINE/WEBROOT/APPHOST" configuration path. Keep in mind that Appcmd reads the effective configuration at the specified path, which is a product of merging all configuration paths in the hierarchy corresponding to the provided configuration path. Therefore, it is not the same as just opening a configuration file at the specified path in Notepad.

If the /section parameter is not provided, Appcmd will list the configuration for all configuration sections. This is a lot to process, so most of the time you will want to specify the name of the section you’d like to view. If you are not sure what the section name is, you can list all registered sections by using the following trick.

appcmd list config /section:?

This will list all of the sections. You can use wildcards after the ? to search for sections with a specific name. For example, "?*security*" shows all sections that have the string security in their names.

The output of the List Config command uses the configuration view by default. 

Setting Configuration with the Set Config Command

The Set Config command is a versatile command that enables you to set or edit any configuration properties. This command uses the following syntax.

appcmd list config ConfigurationPath [/section:SectionName] [/attribute:value]
[/+attribute] [/–attribute]

As with the List Config command, ConfigurationPath is the configuration path or URL at which Appcmd will apply configuration changes. If you omit it, Appcmd will apply configuration to the Web server level, using the "MACHINE/WEBROOT/APPHOST" configuration path. By default, Appcmd will write the configuration to the file corresponding to the configuration path. This facilitates the creation of delegated configuration.

However, you can choose to persist the configuration setting to a higher location in the configuration hierarchy, using a location tag to apply it to the specified configuration path. You may want to do this for cases in which the configuration section being edited is locked and does not enable configuration settings to be set at the configuration path for which is it being applied. To do this, you can use the /commit parameter. 

Direct from the Source: Understanding Where Configuration Is Saved

It is important to understand the difference between the configuration path for which the configuration is applied and the configuration path where it is persisted. The two are the same by default, but you may want to decouple them by writing the configuration changes to a higher configuration path by using a location tag to apply the settings to the configuration path specified for the command. To do this, you can use the /commit parameter provided by Appcmd.

When using this parameter, you can explicitly specify a configuration path where the settings should be saved. You can specify machine, webroot, or apphost for specific server-level configuration files, to keep all configuration in administrator-controlled configuration files. This is a good option when the configuration sections are locked and are not allowed to be specified in the distributed web.config files.

Alternatively, you can specify site or app to save the changes in a web.config file corresponding to the Web site root or application root for the provided configuration path. Finally, you can use the parent value to specify the parent path segment of the provided URL.

You should use the site, app, or parent values when applying a configuration to a specific URL that does not correspond to a directory, because Appcmd will otherwise fail to generate the web.config file. Additionally, you can use these values to place a configuration for multiple URLs in a single distributed web.config file in the root of the Web site or application, maintaining the benefit of distributed configuration and avoiding too many disparate web.config files.

The right choice depends on your configuration delegation strategy and your requirements for producing portable configuration.

Mike Volodarsky

IIS Core Server Program Manager

The /section parameter is required for the Set Config command, and it must specify a valid configuration section for which you want to set the configuration.

Note

You may want to use the List Config command to find the configuration section you are interested in.

Use additional parameters to actually make the changes to the configuration, including setting attribute values and adding, removing, or editing collection elements.

Setting Configuration Attributes

To set configuration attributes on a specific section by using the Set Config command, you specify each attribute you’d like to set as a parameter and provide its value as a parameter value. For example, to set the allowDoubleEscaping attribute of the system.webServer/security/requestFiltering section, you can use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/allowDoubleEscaping:true

Some configuration sections contain subelements. To address attributes in those sections, you can use the "." notation to specify the full element path to the attribute. The element path is relative to the section, so it is not used for top-level attributes on the section element. For example, to set allowUnlisted in the fileExtensions element of the section we just edited, you can use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/fileExtensions.allowUnlisted:false

Note

You can specify multiple parameters to set multiple configuration attributes of a section in a single command. You cannot specify each parameter more than once, however. Due to a bug, if you specify the same attribute more than once, the last value takes effect.

You can also use the "/-Attribute" syntax to delete values set for the attribute in a configuration, to return the configuration to the value inherited from the parent configuration level or configuration default from the schema definition of the configuration section. For example, to delete the explicitly set value for the allowDoubleEscaping attribute we set earlier, you can use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/-allowDoubleEscaping

Direct from the Source: Case Sensitivity in Appcmd

Appcmd treats parameter names in a case-insensitive manner, which means you do not have to worry about the correct case of each configuration attribute you are setting. However, the underlying configuration system is case-sensitive with respect to attribute names. Therefore, in the highly unlikely event that a configuration element has two attributes that differ only in case, you will not be able to address the second attribute, because Appcmd will always target the first one. This decision was the result of a heated discussion about correctness versus the usability of the tool and is a case (pun intended) of optimizing for the common experience. In general, the ability to use case-sensitive names for attributes should never be taken advantage of, because it produces a very confusing user experience and is so error-prone. So, think twice before designing configuration sections that have multiple attributes that differ only in case.

Likewise, the names of the configuration sections specified in the /section parameter for configuration commands are also case-insensitive, even though it is technically possible to have multiple sections that differ only by case.

In the end, the case-insensitive nature of attribute names and section names makes it significantly easier to use the tool for configuration tasks. However, keep in mind that configuration attribute values themselves can be, and often are, case-sensitive due to how the Web server features interpret the values.

Mike Volodarsky

IIS Core Server Program Manager

Managing Configuration Collections

For configuration sections that contain collections, you can use the Set Config command to add new collection elements, remove existing elements, or edit the configuration contained by each existing element.

To add a collection element, you can use the "/+elementpath.[attribute=‘value’,...]" syntax, where elementpath is the path to the collection element using the "." notation, and each attribute / value pair represents each attribute on the collection element. You must specify the values for all required attributes to create a new collection element, and you can optionally specify other attributes supported by the collection element. For example, to add a new entry to the collection in the fileExtensions element of the system.webServer/security/requestFiltering section, you can use the following command.

appcmd set config /section:system.webServer/security/requestFiltering
/+fileExtensions.[fileExtension='.test',allowed='true']

Note

If you do not specify all of the required attributes for the new collection element, the Set Config command will fail with the "Element is missing required attributes" error message.

The preceding command will create a child element in the collection with the fileExtension and allowed attributes set to the specified values. Note that if the section itself is a collection, you simply specify the bracket expression and don’t need an element path.

You can control where in the collection you add the new element. By default, the element is added at the end of the collection for collections configured to use the merge append mode in the configuration schema, and at the beginning of the collection if the collection is configured to use the merge prepend mode. You can override this default position by using the position qualifier, which can have the values of @start, @end, and @Position where Position is the 0-indexed position in the collection. The position qualifier should be the first item in the bracketed list. For example, to insert the element we added in the preceding command at the start of the collection, you could use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/+fileExtensions.[@start,fileExtension='.test',allowed='true']

Note

If the collection already has an element that contains the same values for the key attributes as the one being added, the Set Config command will fail with a "Cannot add duplicate collection entry" error message.

To remove a collection element, use the "/-elementpath.[attribute=‘value’,...]" syntax, which must specify attribute / value for all attributes that comprise a collection key to uniquely identify the collection element to be removed. For example, to remove the collection element added in the previous example, use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/-fileExtensions.[fileExtension='.test']

Because the fileExtension attribute is the single unique key of the collection, it is sufficient to remove the desired element.

Instead of specifying the key attributes, you can remove collection elements by using the position qualifier we discussed earlier. For example, to remove the first element in the collection, use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/-fileExtensions.[@start]

Finally, to set attributes for a specific collection element, you can use the standard element path notation for setting configuration attributes but also use the bracketed collection indexer expression to select the required collection element. For example, to set the allowed attribute on the collection entry we added earlier, you can use the following syntax.

appcmd set config /section:system.webServer/security/requestFiltering
/fileExtensions.[fileExtension='.test'].allowed:true

Note that we had to identify the element by using the unique key of the collection, much as we do for the deletion of collection elements. However, also note that the attribute we are setting is specified outside of the bracketed expression—the attributes in the bracketed expression serve to uniquely identify the element you are modifying. Because of this, you need to use the full element path notation to set each attribute on a collection element. As before, instead of using the key attributes to identify the collection element, we can also use the position qualifier.

Managing Configuration Delegation

You can also use the Config object to manage configuration delegation; to determine which configuration sections are allowed in distributed web.config configuration files; and to configure fine-grained configuration locking for specific elements, attributes, and collections. Appcmd provides the following support for this:

• Lock Config command. Lock a configuration section to prevent it from being delegated at a specific configuration level and below.

• Unlock Config command. Unlock a configuration section to allow it to be delegated at a specific configuration level and below.

• Set Config command. Set the special configuration attributes including lockAttributes, lockElements, and lockItem, to configure fine-grained configuration locking.

Managing Configuration Backups

Appcmd provides a Backup object that you can use to create backups of global configuration files and to restore them. Creating a backup can be as simple as using the Add verb on the Backup object as shown here.

appcmd add backup

Issuing this command creates a new backup with a name based on the current date and time. The format is as follows: YYYYMMDDThhmmss (where YYYY is the four-digit year, MM is the two-digit month, DD is the two-digit day, T is a delimiter between the date and time, hh is the two-digit hour, mm is the two-digit minute, and ss is the two-digit second). If you prefer to provide your own name for the backup, you can simply add it to the end of your Appcmd request.

appcmd add backup "MyServerBackup"

By issuing the List verb against the Backup object, you can see your newly created backup.

appcmd list backup

To restore a configuration backup, use the Restore verb and the name of the backup you want to restore. For instance, to restore a backup named "MyServerBackup", type the following.

appcmd restore backup "MyServerBackup"

Note

The backup files are stored as subdirectories of the %SystemRoot%\System32\Inetsrv\Backup folder with the name given to the backup instance. When you create a new backup, administration.config and applicationHost.config are among the files that are stored.