Configuration Editor–An Admin’s Best Friend
Configuration Editor has to be one of my favorite pieces of the IIS7 UI, and probably one of the least publicized. For anyone who hasn’t used it, you should give it a whirl. In addition to allowing you to browse the config using a treeview style layout, it also provides samples showing how to configure IIS via appcmd or code. If you’ve struggled to figure out the proper syntax for different appcmd tasks, this feature is for you! Now, this post isn’t intended to be a walkthrough on how to use Config Editor to generate samples, as we already have blog posts on http://iis.net to demonstrate that:
http://learn.iis.net/page.aspx/417/using-configuration-editor-generate-scripts/
Instead, I’m posting to try and help others with a scenario I hit this week. From time to time, I find that the appcmd sample Config Editor gives me is incomplete in some way. It’s rare, but it does happen, no tool is bulletproof. In this case, I was working with the Advanced Logging module for IIS, trying to figure out how to add an additional logging field to the default log collection. If you’ve worked with this module, you know that the name of the default logging collection is “%COMPUTERNAME%-Server”. It didn’t occur to me that the name would be an issue when using appcmd until I went to use the sample command that Config Editor gave me.
In Config Editor, I navigated to system.webServer/advancedLogging/server, and opened the logDefinitions collection. Within the properties for the default collection, I added a new item to the selectedFields collection, specifically the UserName field. Once done, I went back to the Config Editor window and hit “Generate Script”, and here’s what I got:
Now, anyone see a problem with that? When we ran it, we got this:
C:\>appcmd.exe set config -section:system.webServer/advancedLogging/server /+"logDefinitions.[baseFileName='%COMPUTERNAME%-Server'].selectedFields.[id='UserName',logHeaderName='cs-username']" /commit:apphost
ERROR ( message:Cannot find requested collection element. )
What’s happening is that the command interpreter is seeing %COMPUTERNAME% as a variable and inserting the machine name into the command when appcmd runs it. This will obviously fail, as there is no logDefinition collection named with the actual machine name by default. To fix this, we need to implement a very simple change and escape the percent signs, which also involves removing the quotes from the command:
appcmd.exe set config -section:system.webServer/advancedLogging/server /+logDefinitions.[baseFileName='^%COMPUTERNAME^%-Server'].selectedFields.[id='UserName',logHeaderName='cs-username'] /commit:apphost
Bottom line: While it isn’t perfect, Configuration Editor can be extremely helpful in figuring out the proper syntax for different appcmd commands if you’re stuck. It’s definitely something all administrators should be familiar with.