WebConfigPropertyCollection: Allow deleting single item property collections, update examples, remove duplicate resource documentation (#644)

Borgquite · web-flow · commit 76d82ae4590d · 2024-11-05T18:08:06.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
 
 - WebConfigPropertyCollection
   - Allowed different property collection key types to be added beyond the default.
+  - Allowed control over single item property collection key types, including examples - fixes ([issue #379](https://github.com/dsccommunity/WebAdministrationDsc/issues/379)), ([issue #631](https://github.com/dsccommunity/WebAdministrationDsc/issues/631)).
 
 ### Changed
 
@@ -24,6 +25,10 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
 - WebAdministrationDsc
   - Fixed CertificateStoreName default value from `MY` to `My` ([issue #642](https://github.com/dsccommunity/WebAdministrationDsc/issues/642))
 
+### Removed
+
+- Removed outdated resources documentation from README.md.
+
 ## [4.2.0] - 2024-08-26
 
 ### Removed
diff --git a/README.md b/README.md
diff --git a/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1 b/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1
@@ -274,6 +274,12 @@ function Set-TargetResource
         Write-Verbose `
             -Message ($script:localizedData.VerboseSetTargetRemoveItem -f $ItemPropertyName )
 
+        # If we are removing a single collection item with the wildcard syntax for the key, set key name to match the property name
+        if ($ItemKeyName -eq '*')
+        {
+            $ItemKeyName = $ItemPropertyName
+        }
+
         $filter = "$($Filter)/$($CollectionName)"
         Remove-WebConfigurationProperty `
             -PSPath $WebsitePath `
diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1
@@ -30,7 +30,6 @@ Configuration Sample_WebConfigPropertyCollection_Remove
             ItemKeyName       = 'verb'
             ItemKeyValue      = 'TRACE'
             ItemPropertyName  = 'allowed'
-            ItemPropertyValue = 'false'
             Ensure            = 'Absent'
         }
     }
diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1
@@ -0,0 +1,37 @@
+<#
+.SYNOPSIS
+    Make appsettings.json inaccessible to clients.
+
+.DESCRIPTION
+    This example shows how to use the WebConfigPropertyCollection DSC resource for adding a single item configuration element.
+    It will add an "add" element to the system.webServer/security/requestFiltering/hiddenSegments collection to block appsettings.json.
+#>
+Configuration Sample_WebConfigPropertyCollection_SingleItemAdd
+{
+    param
+    (
+        # Target nodes to apply the configuration.
+        [Parameter()]
+        [String[]]
+        $NodeName = 'localhost'
+    )
+
+    # Import the modules that define custom resources
+    Import-DscResource -ModuleName WebAdministrationDsc
+
+    Node $NodeName
+    {
+        WebConfigPropertyCollection "$($NodeName) - Block appsettings.json"
+        {
+            WebsitePath       = 'MACHINE/WEBROOT/APPHOST'
+            Filter            = 'system.webServer/security/requestFiltering'
+            CollectionName    = 'hiddenSegments'
+            ItemName          = 'add'
+            ItemKeyName       = '*'
+            ItemKeyValue      = 'appsettings.json'
+            ItemPropertyName  = 'segment'
+            ItemPropertyValue = 'appsettings.json'
+            Ensure            = 'Present'
+        }
+    }
+}
diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1
@@ -0,0 +1,36 @@
+<#
+.SYNOPSIS
+    Removes making appsettings.json inaccessible to clients.
+
+.DESCRIPTION
+    This example shows how to use the WebConfigPropertyCollection DSC resource for removing a single item configuration element.
+    It will remove the "add" element from the system.webServer/security/requestFiltering/hiddenSegments collection (if present) for blocking appsettings.json.
+#>
+Configuration Sample_WebConfigPropertyCollection_SingleItemRemove
+{
+    param
+    (
+        # Target nodes to apply the configuration.
+        [Parameter()]
+        [String[]]
+        $NodeName = 'localhost'
+    )
+
+    # Import the modules that define custom resources
+    Import-DscResource -ModuleName WebAdministrationDsc
+
+    Node $NodeName
+    {
+        WebConfigPropertyCollection "$($NodeName) - Remove blocking appsettings.json"
+        {
+            WebsitePath       = 'MACHINE/WEBROOT/APPHOST'
+            Filter            = 'system.webServer/security/requestFiltering'
+            CollectionName    = 'hiddenSegments'
+            ItemName          = 'add'
+            ItemKeyName       = '*'
+            ItemKeyValue      = 'appsettings.json'
+            ItemPropertyName  = 'segment'
+            Ensure            = 'Absent'
+        }
+    }
+}
diff --git a/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1 b/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1
@@ -59,6 +59,12 @@ try
                     IntegerItemKeyValue      = 'Content-Type'
                     IntegerItemPropertyName  = 'Sizelimit'
                     IntegerItemPropertyValue = [string](Get-Random -Minimum 11 -Maximum 100)
+                    SingleItemFilter         = 'system.webServer/security/requestFiltering'
+                    SingleItemCollectionName = 'hiddenSegments'
+                    SingleItemKeyName        = '*'
+                    SingleItemKeyValue       = 'appsettings.json'
+                    SingleItemPropertyName   = 'segment'
+                    SingleItemPropertyValue  = 'appsettings.json'
                 }
             )
         }
@@ -78,6 +84,12 @@ try
         $integerItemKeyValue      = $ConfigurationData.AllNodes.IntegerItemKeyValue
         $integerItemPropertyName  = $ConfigurationData.AllNodes.IntegerItemPropertyName
         $integerItemPropertyValue = $ConfigurationData.AllNodes.IntegerItemPropertyValue
+        $singleItemFilter         = $ConfigurationData.AllNodes.SingleItemFilter
+        $singleItemCollectionName = $ConfigurationData.AllNodes.SingleItemCollectionName
+        $singleItemKeyName        = $ConfigurationData.AllNodes.SingleItemKeyName
+        $singleItemKeyValue       = $ConfigurationData.AllNodes.SingleItemKeyValue
+        $singleItemPropertyName   = $ConfigurationData.AllNodes.SingleItemPropertyName
+        $singleItemPropertyValue  = $ConfigurationData.AllNodes.SingleItemPropertyValue
 
         $startDscConfigurationParameters = @{
             Path              = $TestDrive
@@ -89,6 +101,7 @@ try
 
         $filterValue = "$($filter)/$($collectionName)/$($itemName)[@$($itemKeyName)='$($itemKeyValue)']/@$itemPropertyName"
         $integerFilterValue = "$($integerFilter)/$($integerCollectionName)/$($itemName)[@$($integerItemKeyName)='$($integerItemKeyValue)']/@$integerItemPropertyName"
+        $singleItemFilterValue = "$($singleItemFilter)/$($singleItemCollectionName)/$($itemName)[@$($singleItemKeyName)='$($singleItemKeyValue)']/@$singleItemPropertyName"
 
         Context 'When Adding Collection item' {
             It 'Should compile and apply the MOF without throwing' {
@@ -183,6 +196,53 @@ try
             }
         }
 
+        Context 'When Adding Single Collection item' {
+            It 'Should compile and apply the MOF without throwing' {
+                {
+                    & "$($script:dscResourceName)_SingleItemAdd" -OutputPath $TestDrive -ConfigurationData $configurationData
+                    Start-DscConfiguration @startDscConfigurationParameters
+                } | Should -Not -Throw
+            }
+
+            It 'Should be able to call Get-DscConfiguration without throwing' {
+                { Get-DscConfiguration -Verbose -ErrorAction Stop } | Should -Not -Throw
+            }
+
+            It 'Should return $true for Test-DscConfiguration' {
+                Test-DscConfiguration | Should Be $true
+            }
+
+            It 'Should have the correct value of the configuration property collection item' {
+                # Get the new value.
+                $value = (Get-WebConfigurationProperty -PSPath $websitePath -Filter $singleItemFilterValue -Name "." -ErrorAction SilentlyContinue).Value
+
+                $value | Should -Be $singleItemPropertyValue
+            }
+        }
+
+        Context 'When Removing Single Collection item' {
+            It 'Should compile and apply the MOF without throwing' {
+                {
+                    & "$($script:dscResourceName)_SingleItemRemove" -OutputPath $TestDrive -ConfigurationData $configurationData
+                    Start-DscConfiguration @startDscConfigurationParameters
+                } | Should -Not -Throw
+            }
+
+            It 'Should be able to call Get-DscConfiguration without throwing' {
+                { Get-DscConfiguration -Verbose -ErrorAction Stop } | Should -Not -Throw
+            }
+
+            It 'Should return $true for Test-DscConfiguration' {
+                Test-DscConfiguration | Should Be $true
+            }
+
+            It 'Should remove configuration property' {
+                $value = (Get-WebConfigurationProperty -PSPath $websitePath -Filter $singleItemFilterValue -Name "." -ErrorAction SilentlyContinue).Value
+
+                $value | Should -BeNullOrEmpty
+            }
+        }
+
         # Remove the website we created for testing purposes.
         if (Get-Website -Name $websiteName)
         {
diff --git a/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1 b/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1
@@ -81,3 +81,44 @@ Configuration DSC_WebConfigPropertyCollection_Integer
         }
     }
 }
+
+Configuration DSC_WebConfigPropertyCollection_SingleItemAdd
+{
+    Import-DscResource -ModuleName WebAdministrationDsc
+
+    node localhost
+    {
+        WebConfigPropertyCollection IntegrationTest
+        {
+            WebsitePath       = $Node.WebsitePath
+            Filter            = $Node.SingleItemFilter
+            CollectionName    = $Node.SingleItemCollectionName
+            ItemName          = $Node.ItemName
+            ItemKeyName       = $Node.SingleItemKeyName
+            ItemKeyValue      = $Node.SingleItemKeyValue
+            ItemPropertyName  = $Node.SingleItemPropertyName
+            ItemPropertyValue = $Node.SingleItemPropertyValue
+            Ensure            = 'Present'
+        }
+    }
+}
+
+Configuration DSC_WebConfigPropertyCollection_SingleItemRemove
+{
+    Import-DscResource -ModuleName WebAdministrationDsc
+
+    node localhost
+    {
+        WebConfigPropertyCollection IntegrationTest
+        {
+            WebsitePath       = $Node.WebsitePath
+            Filter            = $Node.SingleItemFilter
+            CollectionName    = $Node.SingleItemCollectionName
+            ItemName          = $Node.ItemName
+            ItemKeyName       = $Node.SingleItemKeyName
+            ItemKeyValue      = $Node.SingleItemKeyValue
+            ItemPropertyName  = $Node.SingleItemPropertyName
+            Ensure            = 'Absent'
+        }
+    }
+}
diff --git a/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1 b/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1
@@ -60,6 +60,18 @@ try
             Ensure            = 'Absent'
         }
 
+        $script:absentSingleItemParameters = @{
+            WebsitePath       = 'MACHINE/WEBROOT/APPHOST'
+            Filter            = 'system.webServer/security/requestFiltering'
+            CollectionName    = 'hiddenSegments'
+            ItemName          = 'add'
+            ItemKeyName       = '*'
+            ItemKeyValue      = 'appsettings.json'
+            ItemPropertyName  = 'segment'
+            ItemPropertyValue = 'appsettings.json'
+            Ensure            = 'Absent'
+        }
+
         #region Function Get-TargetResource
         Describe "$($script:dscResourceName)\Get-TargetResource" {
             $parameters = @{
@@ -310,6 +322,18 @@ try
                     Assert-MockCalled -CommandName Remove-WebConfigurationProperty -Times 1 -Exactly
                 }
             }
+
+            Context 'Ensure is absent and single collection item element' {
+                Mock -CommandName Remove-WebConfigurationProperty -MockWith {}
+
+                It 'Should call the right Mocks' {
+                    Set-TargetResource @script:absentSingleItemParameters
+
+                    Assert-MockCalled -CommandName Remove-WebConfigurationProperty -Times 1 -Exactly -ParameterFilter {
+                        $AtElement[$script:absentSingleItemParameters.ItemPropertyName] -eq $script:absentSingleItemParameters.ItemKeyValue
+                    }
+                }
+            }
         }
         #endregion Function Set-TargetResource
 

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,6 @@ Configuration Sample_WebConfigPropertyCollection_Remove`
`30`	`30`	`ItemKeyName = 'verb'`
`31`	`31`	`ItemKeyValue = 'TRACE'`
`32`	`32`	`ItemPropertyName = 'allowed'`
`33`		`- ItemPropertyValue = 'false'`
`34`	`33`	`Ensure = 'Absent'`
`35`	`34`	`}`
`36`	`35`	`}`