Merge branch 'main' of https://github.com/Gijsreyn/operation-methods into add-skip-function

Author: Gijsreyn

docs/reference/schemas/config/functions/lastIndexOf.md

@@ -0,0 +1,150 @@
+---
+description: Reference for the 'lastIndexOf' DSC configuration document function
+ms.date:     08/29/2025
+ms.topic:    reference
+title:       lastIndexOf
+---
+
+## Synopsis
+
+Returns an integer for the index of the last occurrence of an item in an array.
+If the item isn't present, returns -1.
+
+## Syntax
+
+```Syntax
+lastIndexOf(arrayToSearch, itemToFind)
+```
+
+## Description
+
+The `lastIndexOf()` function searches an array from the end to the beginning
+and returns the zero-based index of the last matching element. String
+comparisons are case-sensitive. If no match is found, `-1` is returned.
+
+Supported `itemToFind` types:
+
+- string (case-sensitive)
+- number (integer)
+- array (deep equality)
+- object (deep equality)
+
+## Examples
+
+### Example 1 - Find the last rollout slot for a server role (strings)
+
+Use `lastIndexOf()` to locate where a particular role (like a web node)
+appears last in a planned rollout sequence. This is handy when you need to
+schedule a final step (for example, draining traffic) after the last matching
+node has been processed. This example uses [`createArray()`][02] to build the
+list of nodes.
+
+```yaml
+# lastindexof.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Rollout Plan
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      lastWebIndex: "[lastIndexOf(createArray('web01','db01','web02','cache01','web03'), 'web03')]"
+      lastWebFamilyIndex: "[lastIndexOf(createArray('web01','db01','web02','cache01','web02'), 'web02')]"
+```
+
+```bash
+dsc config get --file lastindexof.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Rollout Plan
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        lastWebIndex: 4
+        lastWebFamilyIndex: 4
+messages: []
+hadErrors: false
+```
+
+Note that string comparison is case-sensitive. Searching for `WEB02` would
+return `-1` in this example.
+
+### Example 2 - Locate the last matching configuration object (objects)
+
+Deep equality lets you search arrays of objects. Here we find the last
+occurrence of a feature flag object with a specific name. This example uses
+[`createObject()`][03] to build objects and [`createArray()`][10] to build the
+collection.
+
+```yaml
+# lastindexof.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Feature Flags
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      lastBetaIndex: "[lastIndexOf(createArray(createObject('name','Beta'), createObject('name','Gamma'), createObject('name','Beta')), createObject('name','Beta'))]"
+```
+
+```bash
+dsc config get --file lastindexof.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Feature Flags
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        lastBetaIndex: 2
+messages: []
+hadErrors: false
+```
+
+Property order in objects doesn't matter. The following also returns `1` due to
+deep equality: `lastIndexOf(array(createObject('a',1,'b',2), createObject('b',2,'a',1)), createObject('a',1,'b',2))`.
+
+## Parameters
+
+### arrayToSearch
+
+The array to search. Required.
+
+```yaml
+Type:     array
+Required: true
+Position: 1
+```
+
+### itemToFind
+
+The item to search for. Required.
+
+```yaml
+Type:     string | number | array | object
+Required: true
+Position: 2
+```
+
+## Output
+
+Returns a number representing the last index or -1 if not found.
+
+```yaml
+Type: number
+```
+
+## Related functions
+
+- [`indexOf()`][00] - First occurrence index in an array
+- [`contains()`][01] - Checks for presence in arrays/objects/strings
+
+<!-- Link reference definitions -->
+[00]: ./indexOf.md
+[01]: ./contains.md
+[02]: ./createArray.md
+[03]: ./createObject.md

dsc/src/subcommand.rs

@@ -319,6 +319,8 @@ pub fn config(subcommand: &ConfigSubCommand, parameters: &Option<String>, parame
         }
     };
 
+    configurator.context.dsc_version = Some(env!("CARGO_PKG_VERSION").to_string());
+
     if let ConfigSubCommand::Set { what_if , .. } = subcommand {
         if *what_if {
             configurator.context.execution_type = ExecutionKind::WhatIf;

dsc/tests/dsc_discovery.tests.ps1

@@ -95,7 +95,6 @@ Describe 'tests for resource discovery' {
             $env:DSC_RESOURCE_PATH = $testdrive
             Set-Content -Path "$testdrive/test.dsc.resource.json" -Value $manifest
             $out = dsc resource list 2>&1
-            write-verbose -verbose ($out | Out-String)
             $out | Should -Match 'WARN.*?Validation.*?invalid version' -Because ($out | Out-String)
         }
         finally {
@@ -166,21 +165,18 @@ Describe 'tests for resource discovery' {
         $env:PSModulePath = $oldPSModulePath
     }
 
-    It 'Verify non-zero exit code when resource not found' {
+    It 'Verify non-zero exit code when resource not found: <cmdline>' -TestCases @(
+        @{ cmdline = "dsc resource get -r abc/def" }
+        @{ cmdline = "dsc resource get --all -r abc/def" }
+        @{ cmdline = "dsc resource set -r abc/def -i 'abc'" }
+        @{ cmdline = "dsc resource test -r abc/def -i 'abc'" }
+        @{ cmdline = "dsc resource delete -r abc/def -i 'abc'" }
+        @{ cmdline = "dsc resource export -r abc/def" }
+        @{ cmdline = "dsc resource schema -r abc/def" }
+    ) {
+        param($cmdline)
 
-        $out = dsc resource get -r abc/def
-        $LASTEXITCODE | Should -Be 7
-        $out = dsc resource get --all -r abc/def
-        $LASTEXITCODE | Should -Be 7
-        $out = 'abc' | dsc resource set -r abc/def -f -
-        $LASTEXITCODE | Should -Be 7
-        $out = 'abc' | dsc resource test -r abc/def -f -
-        $LASTEXITCODE | Should -Be 7
-        $out = 'abc' | dsc resource delete -r abc/def -f -
-        $LASTEXITCODE | Should -Be 7
-        $out = dsc resource export -r abc/def
-        $LASTEXITCODE | Should -Be 7
-        $out = dsc resource schema -r abc/def
+        Invoke-Expression $cmdline 2>$null
         $LASTEXITCODE | Should -Be 7
     }
 

dsc/tests/dsc_extension_discover.tests.ps1

@@ -108,7 +108,6 @@ Describe 'Discover extension tests' {
             $out.Count | Should -Be 1 -Because ($out | Out-String)
             $out.type | Should -Be 'Test/DiscoverRelative'
             $out = dsc resource list 2> $TestDrive/error.log
-            write-verbose -verbose (Get-Content -Path "$TestDrive/error.log" -Raw)
             $LASTEXITCODE | Should -Be 0
             $out | Should -BeNullOrEmpty
             $errorMessage = Get-Content -Path "$TestDrive/error.log" -Raw

dsc/tests/dsc_functions.tests.ps1

@@ -434,4 +434,33 @@ Describe 'tests for function expressions' {
     $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
     ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
   }
+
+  It 'lastIndexOf function works for: <expression>' -TestCases @(
+    @{ expression = "[lastIndexOf(createArray('a', 'b', 'a', 'c'), 'a')]"; expected = 2 }
+    @{ expression = "[lastIndexOf(createArray(10, 20, 30, 20), 20)]"; expected = 3 }
+    @{ expression = "[lastIndexOf(createArray('Apple', 'Banana'), 'apple')]"; expected = -1 }
+    @{ expression = "[lastIndexOf(createArray(createArray('a','b'), createArray('c','d'), createArray('a','b')), createArray('a','b'))]"; expected = 2 }
+    @{ expression = "[lastIndexOf(createArray(createObject('name','John'), createObject('name','Jane'), createObject('name','John')), createObject('name','John'))]"; expected = 2 }
+    @{ expression = "[lastIndexOf(createArray(), 'test')]"; expected = -1 }
+    # Objects are compared by deep equality: same keys and values are equal, regardless of property order.
+    # Both createObject('a',1,'b',2) and createObject('b',2,'a',1) are considered equal.
+    # Therefore, lastIndexOf returns 1 (the last position where an equal object occurs).
+    @{ expression = "[lastIndexOf(createArray(createObject('a',1,'b',2), createObject('b',2,'a',1)), createObject('a',1,'b',2))]"; expected = 1 }
+    @{ expression = "[lastIndexOf(createArray('1','2','3'), 1)]"; expected = -1 }
+    @{ expression = "[lastIndexOf(createArray(1,2,3), '1')]"; expected = -1 }
+  ) {
+    param($expression, $expected)
+
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: "$expression"
+"@
+    $out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log | ConvertFrom-Json
+    $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+    ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
+  }
 }

dsc/tests/dsc_include.tests.ps1

@@ -35,7 +35,7 @@ Describe 'Include tests' {
 "@
         $configPath = Join-Path $TestDrive 'config.dsc.yaml'
         $config | Set-Content -Path $configPath
-        dsc config get -f $configPath
+        dsc config get -f $configPath 2>$null
         $LASTEXITCODE | Should -Be 2
     }
 

dsc/tests/dsc_securitycontext.tests.ps1

@@ -13,7 +13,7 @@ Describe 'Tests for configuration security context metadata' {
     }
 
     It 'Require admin' {
-        $out = dsc config get -f $PSScriptRoot/../examples/require_admin.yaml
+        $out = dsc config get -f $PSScriptRoot/../examples/require_admin.yaml 2>$null
         if ($isAdmin) {
             $LASTEXITCODE | Should -Be 0
             $out | Should -Not -BeNullOrEmpty
@@ -24,7 +24,7 @@ Describe 'Tests for configuration security context metadata' {
     }
 
     It 'Require non-admin' {
-        $out = dsc config get -f $PSScriptRoot/../examples/require_nonadmin.yaml
+        $out = dsc config get -f $PSScriptRoot/../examples/require_nonadmin.yaml 2>$null
         if ($isAdmin) {
             $LASTEXITCODE | Should -Be 2
         }

dsc/tests/dsc_set.tests.ps1

@@ -61,7 +61,7 @@ Describe 'resource set tests' {
                 "_exist": false
             }
 '@
-            $null = registry config set --input $json
+            $null = registry config set --input $json 2>$null
         }
     }
 
@@ -73,7 +73,7 @@ Describe 'resource set tests' {
                 "_exist": false
             }
 '@
-            $null = registry config set --input $json
+            $null = registry config set --input $json 2>$null
         }
     }
 

dsc/tests/dsc_test.tests.ps1

@@ -9,7 +9,7 @@ Describe 'resource test tests' {
             "valueName": "ProductName"
         }
 '@
-        $current = registry config get --input $json
+        $current = registry config get --input $json 2>$null
         $out = $current | dsc resource test -r Microsoft.Windows/Registry -f -
         $LASTEXITCODE | Should -Be 0
         $out = $out | ConvertFrom-Json

dsc/tests/dsc_variables.tests.ps1

@@ -22,7 +22,6 @@ resources:
     output: "[variables('myVariable')]"
 '@
     $out = dsc config get -i $configYaml | ConvertFrom-Json
-    Write-Verbose -Verbose $out
     $LASTEXITCODE | Should -Be 0
     $out.results[0].result.actualState.output | Should -Be 'bar'
   }
@@ -39,7 +38,6 @@ resources:
     output: "[variables('myVariable')]"
 '@
     $out = dsc config get -i $configYaml 2>&1 | Out-String
-    Write-Verbose -Verbose $out
     $LASTEXITCODE | Should -Be 2
     $out | Should -BeLike "*Variable 'myVariable' does not exist or has not been initialized yet*"
   }