Understanding appcmd.exe [list|set] config [ConfigurationPath] /section:name /parameter_name:value
To use appcmd efficiently for setting/listing configuration, we need to understand how we pass parameter. This requires us to be familiar with some syntax to edit attribute located at section, child element or collection element.
In this blog, we will go over those with examples.
1.Basic command string
Here is how basic command string looks like.
appcmd.exe [list|set] config [ConfigurationPath] /section:name /parameter_name:value
In plain English, it says that we retrieve or edit configuration of a specific section defined at specific configuration path. To illustrate examples, we are using system.webServer/security/requestFiltering section.
This is good example since this section has attribute at section, child element, and collection element, so we can go over each one.
Here is part of schema.
<sectionSchema name="system.webServer/security/requestFiltering">
<attribute name="allowDoubleEscaping" type="bool" defaultValue="false" />
<attribute name="allowHighBitCharacters" type="bool" defaultValue="true" />
<attribute name="unescapeQueryString" type="bool" defaultValue="true" />
<element name="fileExtensions">
<attribute name="allowUnlisted" type="bool" defaultValue="true" />
<attribute name="applyToWebDAV" type="bool" defaultValue="true" />
<collection addElement="add" clearElement="clear" removeElement="remove" >
<attribute name="fileExtension" type="string" required="true" isUniqueKey="true" validationType="nonEmptyString" />
<attribute name="allowed" type="bool" required="true" defaultValue="true" />
</collection>
</element>
...
</sectionSchema>
2. Edit attribute
From the schema, attribute is defined at 1) section (system.webServer/security/requestFiltering), 2) child elemement (fileExtensions), and 3) collection element (add).
The following examples show how to edit each one.
2.1 Edit attribute at section
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /allowDoubleEscaping:false
This example will set attribute allowDoubleEscaping to false on section system.webServer/security/requestFiltering located at configuration path MACHINE/WEBROOT/APPHOST/Default Web Site.
After run command sussessfully, the web.config on site will add the following configuration.
<security>
<requestFiltering allowDoubleEscaping="false" />
</security>
You can also delete attribute on element by using set with ‘-‘ notation.
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /-allowDoubleEscaping
2.2 Edit attribute on child element of section
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /fileExtensions.allowUnlisted:false
This example shows setting attribute on child element of the section. In order to access child element, appcmd introduces ‘.' (dot) notation to specify the attribute defined at the child element
You can also pass multiple parameters to edit multiple attributes.
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /fileExtensions.allowUnlisted:false /fileExtensions.applyToWebDAV:false
Once command run successfully, web.config will look like the following.
<security>
<requestFiltering allowDoubleEscaping="false">
<fileExtensions allowUnlisted="false" applyToWebDAV="false" />
</requestFiltering>
</security>
2.3 edit attribute on collection element
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /fileExtensions.[fileExtension='.text'].allowed:false
This example shows setting attribute on collection element.
There could be multiple entries in collection element. So, the command first finds the element to edit, and then set attribute. That requires square bracket ‘[]' syntax. /fileExtensions.[fileExtension='.text'] will tell you to find an entry having fileExtension ‘.text' under fileExtensions element, and set allowed attribute to false.
This will change web.config like below. Note that we need an entry before run this command.
<security>
<requestFiltering allowDoubleEscaping="false">
<fileExtensions allowUnlisted="false" applyToWebDAV="false">
<add fileExtension=".text" allowed="false" />
</fileExtensions>
</requestFiltering>
</security>
3. Collection element
3.1 Add collection element
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /+fileExtensions.[fileExtension='.test',allowed='true'] /+fileExtensions.[fileExtension='.test2',allowed='true']
This example shows adding collection element with attributes.
set command can add collection element. Note that verb ‘add' is not applicable with config object. We still need verb ‘set' with ‘+' notation to indicate adding a collection element, and use [] to put attributes for this collection element. You can put multiple parameters to add multiple collection elements.
<security>
<requestFiltering allowDoubleEscaping="false">
<fileExtensions allowUnlisted="false" applyToWebDAV="false">
<add fileExtension=".test" allowed="true" />
<add fileExtension=".test2" allowed="true" />
</fileExtensions>
</requestFiltering>
</security>
3.2. Delete collection element
C:\Windows\System32\inetsrv>appcmd set config "Default Web Site" /section:system.webServer/security/requestFiltering /-fileExtensions.[fileExtension='.test']
set command also deletes a collection element. Again, note that verb ‘delete' is not applicable with config object. We still need verb ‘set' with ‘-' notation to indicate deleting a collection element, and use [] to find which one to delete.
Reference
1. Getting Started with AppCmd.exe