PowerShell IIS Set-WebConfigurationProperty - Locked ApplicationHost.config section - powershell

Question

I am writing a PowerShell 3.0 installer for our web applications and web services and am getting tripped up when attempting to set physical path credentials.
My code looks like this:
# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
# >>>>>> Path credentials
# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
# Set the physical path credentials of the web application (on Basic Settings screen) to Connect As...
$filter="/system.applicationHost/sites/site[#name='{0}' and #id='1']/application[#path='/{1}']/VirtualDirectory[#path='/']" -f $script:WebSiteName,$appName
Set-WebConfiguration $filter -Value #{userName="$physicalPathCredentialUserID";password="$physicalPathCredentialPassword"}
When executing, I get an error in PowerShell stating "This configuration section cannot be used at this path. This happens when the section is locked at a parent level". I tried the PSPath and location tags that work when Authentication sections are locked, but those don't seem to have any effect. I thought maybe the -Force option would work, but although no error was thrown, the physical path credentials didn't seem to take.
Without the -Force option, the error is thrown but PowerShell cuts off the message so I can't tell exactly what section it is complaining about, or what parent level is locked. I have to assume it is the Sites section since I am attempting to configure: /configuration/system.applicationHost/sites/application/virtualDirectory
I'm a bit confused about the difference between unlocking and allowing override to get the values to stick. PowerShell WebAdministration is pretty confusing in this area. I don't know why it has to be so confusing to set the values that are corollaries to what can be set in the IIS adminstration UI. Some values use Set-WebConfiguration with an ugly string as shown above, others use Set-WebConfigurationProperty. If locking is a known issue, why isn't unlocking better documented?
I don't want to unlock all sites or all applications. I just want to unlock what I have to in order to set the configuration values on each web application I am installing under Default Web Site.
What is the definitive solution to unlocking or overriding configuration sections as of 2014 and PowerShell 3.0? And which settings accept PSPath and location?
By the way, I have tried variants of the following:
$filter="/system.applicationHost/sites/site[#name='{0}' and #id='1']/application[#path='/{1}']/VirtualDirectory[#path='/']" -f $script:WebSiteName,$appName
Set-WebConfiguration $filter machine/webroot/appHost -metadata overrideMode -value Allow
but continued to get the locked section message until the filter was backed off to the sites level.
I also tried setting the virtualDirectoryDefaults.userName and virtualDirectoryDefaults.password, which didn't seem to take initially, but after an IISReset I noticed they were indeed added at the bottom of the applicationHost.config file. I don't really want them set as defaults because our apps shouldn't affect other apps on the server.
I appreciate any assistance you can provide. I must be missing something because it shouldn't be so difficult to set these and other web application configuration values.
Regards

Answer 1

The sections you are trying to change are set in the IIS machine config. You have to unlock the sections in order to set them per-site.
See: Programmatically unlocking IIS configuration sections in Powershell

Answer 2

Your Filter does not look right. You can think of the filter as basically an XPath query. So if you use a filter of //authentication/* then that will get all of your configuration under an authentication node. It's not exactly the same as XPath, but it's pretty close. Just remember that you can't select metadata sections like sectionGroup or location tags using just the Filter parameter alone.
I had an issue where I needed to have Windows authentication unlocked at the server level that way I could set Windows auth to different values at the application level. So I had to do something like this:
Set-WebConfiguration -Metadata OverrideMode -Value Allow -Filter //windowsAuthentication
Set-WebConfigurationProperty -PSPath IIS:\Sites\$WebsiteName\$AppName -Filter //windowsAuthentication -Name Enabled -Value $true
What this did was create a section in the applicationHost.config file that looked like this:
<location path="" overrideMode="Allow">
<system.webServer>
<security>
<authentication>
<windowsAuthentication>
</windowsAuthentication>
</authentication>
</security>
</system.webServer>
</location>
Whatever configuration you place with that location tag will be considered unlocked according to IIS I believe.
And this is what was added to the Web.config file in the web application itself:
<authentication>
<windowsAuthentication enabled="true" />
</authentication>
Hopefully this helps.