From 189a9ab075dd325b8e205929113c31d9eea5d215 Mon Sep 17 00:00:00 2001
From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com>
Date: Sun, 10 May 2026 16:37:21 +0200
Subject: [PATCH] docs: Update PSScript examples

---
 .../powershell-script-with-input-output.md    | 197 ++++++++++++++++++
 .../run-a-simple-powershell-script.md         | 189 +++++++++++++++++
 .../Transitional/PowerShellScript/index.md    |   2 +-
 ...e-windows-service-state-with-powershell.md | 183 ++++++++++++++++
 .../WindowsPowerShellScript/index.md          |   2 +-
 5 files changed, 571 insertions(+), 2 deletions(-)

diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/powershell-script-with-input-output.md b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/powershell-script-with-input-output.md
index e69de29bb..ec0110374 100644
--- a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/powershell-script-with-input-output.md
+++ b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/powershell-script-with-input-output.md
@@ -0,0 +1,197 @@
+---
+description: >
+  Example showing how to pass input data to a PowerShellScript resource and access properties,
+  array elements, and nested values inside the script.
+ms.date:     05/10/2026
+ms.topic:    reference
+title:       PowerShell script with input and output
+---
+
+# PowerShell script with input and output
+
+This example shows how to pass input data to the `Microsoft.DSC.Transitional/PowerShellScript`
+resource and how to bind that data to your script via a `param` block.
+
+## Passing a string as input
+
+When the `input` property is a simple string, it is bound to the first parameter of the script's
+`param` block.
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  "You passed: $inputObj"
+input: Hello, World!
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  output:
+    - 'You passed: Hello, World!'
+```
+
+## Passing an object as input
+
+When `input` is a YAML mapping, the resource deserialises it into a `PSObject`. Script code can
+access individual properties using dot notation.
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  "Name:  $($inputObj.name)"
+  "Value: $($inputObj.value)"
+input:
+  name:  MyApp
+  value: 42
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  output:
+    - 'Name:  MyApp'
+    - 'Value: 42'
+```
+
+## Passing an array as input
+
+When `input` is a YAML sequence, the resource deserialises it into a PowerShell array. Script code
+can index into it or iterate over it.
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  "First:  $($inputObj[0])"
+  "Second: $($inputObj[1])"
+  "Count:  $($inputObj.Count)"
+input:
+  - alpha
+  - beta
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  output:
+    - 'First:  alpha'
+    - 'Second: beta'
+    - 'Count:  2'
+```
+
+## Using input in a configuration document
+
+You can pass input to a `PowerShellScript` instance inside a DSC configuration document, including
+values from configuration parameters. The following configuration uses the [dsc config get][01]
+command to pass a port number into the script:
+
+```yaml
+# check-port.dsc.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+parameters:
+  port:
+    type: int
+    defaultValue: 8080
+resources:
+  - name: checkPort
+    type: Microsoft.DSC.Transitional/PowerShellScript
+    properties:
+      getScript: |
+        param($inputObj)
+        "Checking port $($inputObj.port)..."
+        Test-NetConnection -ComputerName localhost -Port $inputObj.port |
+          Select-Object -ExpandProperty TcpTestSucceeded
+      input:
+        port: "[parameters('port')]"
+```
+
+```powershell
+dsc config get --file check-port.dsc.yaml
+```
+
+```yaml
+executionInformation:
+  duration: <time omitted>
+  endDatetime: <time omitted>
+  executionType: actual
+  operation: get
+  securityContext: restricted
+  startDatetime: <time omitted>
+  version: <redacted>
+metadata:
+  Microsoft.DSC:
+    duration: <time omitted>
+    endDatetime: <time omitted>
+    executionType: actual
+    operation: get
+    securityContext: restricted
+    startDatetime: <time omitted>
+    version: <redacted>
+results:
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: checkPort
+  type: Microsoft.DSC.Transitional/PowerShellScript
+  result:
+    actualState:
+      output:
+      - Checking port 8080...
+      - false
+messages: []
+hadErrors: false
+```
+
+## Error: input provided but script has no param block
+
+If you provide a value for `input` but the script does not have a `param(...)` block, the resource
+exits with code `2` and emits:
+
+```plaintext
+ERROR: Input was provided but script does not have a parameter to accept input.
+```
+
+```powershell
+$instance = @'
+getScript: |
+  "No param block here"
+input: oops
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+# Exit code: 2
+```
+
+## Error: param block present but no input provided
+
+Conversely, if the script defines a `param` block but no `input` is supplied, the resource exits
+with code `2` and emits:
+
+```plaintext
+ERROR: Script has a parameter 'inputObj' but no input was provided.
+```
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  "This will not run"
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+# Exit code: 2
+```
+
+<!-- Link definitions -->
+[01]: ../../../../../../cli/config/get.md
diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/run-a-simple-powershell-script.md b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/run-a-simple-powershell-script.md
index e69de29bb..2d42c4af5 100644
--- a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/run-a-simple-powershell-script.md
+++ b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/run-a-simple-powershell-script.md
@@ -0,0 +1,189 @@
+---
+description: >
+  Example showing how to use the Microsoft.DSC.Transitional/PowerShellScript resource to run
+  simple get, set, and test scripts and how PowerShell streams map to DSC log levels.
+ms.date:     05/10/2026
+ms.topic:    reference
+title:       Run a simple PowerShell script
+---
+
+# Run a simple PowerShell script
+
+This example shows how you can use the `Microsoft.DSC.Transitional/PowerShellScript` resource to
+run inline PowerShell 7 scripts for **Get**, **Set**, and **Test** operations without passing any
+input data.
+
+## Get operation
+
+The following snippet uses the [dsc resource get][01] command to execute a `getScript`. Any values
+written to the PowerShell pipeline are collected and returned in the `output` array.
+
+```powershell
+$instance = @'
+getScript: |
+  "Hello, World!"
+  1 + 1
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  output:
+    - Hello, World!
+    - 2
+```
+
+Pipeline output is captured in order. Non-string values retain their type — `1 + 1` produces the
+integer `2`, not the string `"2"`.
+
+## Set operation
+
+The following snippet uses the [dsc resource set][02] command to execute a `setScript`. The result
+appears in `afterState.output`.
+
+```powershell
+$instance = @'
+setScript: |
+  "Hello, World!"
+  1 + 1
+'@
+
+dsc resource set --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+afterState:
+  output:
+    - Hello, World!
+    - 2
+```
+
+## Test operation
+
+The following snippets use the [dsc resource test][03] command to execute a `testScript`. The
+`testScript` must return exactly one boolean value. DSC uses it to determine whether the instance
+is in the desired state.
+
+### Returning in desired state
+
+```powershell
+$instance = @'
+testScript: |
+  $true
+'@
+
+dsc resource test --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  _inDesiredState: true
+inDesiredState: true
+differingProperties: []
+```
+
+### Returning out of desired state
+
+```powershell
+$instance = @'
+testScript: |
+  $false
+'@
+
+dsc resource test --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  _inDesiredState: false
+inDesiredState: false
+differingProperties:
+  - _inDesiredState
+```
+
+### Invalid test script output
+
+If the `testScript` returns anything other than a single boolean — such as a string, a number, or
+multiple values — DSC exits with code `2` and emits an error:
+
+```plaintext
+ERROR: Test operation did not return a single boolean value.
+```
+
+## Get and Set in the same instance
+
+When both `getScript` and `setScript` are defined, `dsc resource set` runs `getScript` first to
+capture `beforeState`, then runs `setScript` and captures `afterState`.
+
+```powershell
+$instance = @'
+getScript: |
+  "Hello, World!"
+  1 + 1
+setScript: |
+  "Hello, World!"
+  2 + 2
+'@
+
+dsc resource set --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+```
+
+```yaml
+beforeState:
+  output:
+    - Hello, World!
+    - 2
+afterState:
+  output:
+    - Hello, World!
+    - 4
+```
+
+## Omitting scripts
+
+Any script property that is absent or empty is silently ignored. For example, calling
+`dsc resource get` when only `setScript` is defined returns an empty `output` array:
+
+```yaml
+actualState:
+  output: []
+```
+
+If `testScript` is absent, the test operation returns `_inDesiredState: true` without executing
+any script.
+
+## PowerShell streams and DSC log levels
+
+PowerShell stream cmdlets map to DSC log levels.
+
+| PowerShell stream                              | DSC log level  | Example cmdlet            |
+|:-----------------------------------------------|:---------------|:--------------------------|
+| Error (`Write-Error`)                          | error (always) | `Write-Error "msg"`       |
+| Warning (`Write-Warning`)                      | warn (always)  | `Write-Warning "msg"`     |
+| Host / Verbose (`Write-Host`, `Write-Verbose`) | info           | `Write-Host "msg"`        |
+| Debug (`Write-Debug`)                          | debug          | `Write-Debug "msg"`       |
+| Information stream (`Write-Information`)       | trace          | `Write-Information "msg"` |
+
+> [!NOTE]
+> `Write-Error` causes the resource to exit with code `2`. `Write-Warning` does not affect the
+> exit code.
+
+A thrown exception also exits with code `2`:
+
+```powershell
+$instance = @'
+getScript: |
+  throw "This is an exception"
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/PowerShellScript --input $instance
+# Exit code: 2
+# stderr: ERROR: This is an exception
+```
+
+<!-- Link definitions -->
+[01]: ../../../../../../cli/resource/get.md
+[02]: ../../../../../../cli/resource/set.md
+[03]: ../../../../../../cli/resource/test.md
diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/index.md b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/index.md
index 29b0a1f6a..80a1a59b6 100644
--- a/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/index.md
+++ b/docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/index.md
@@ -264,7 +264,7 @@ to the PowerShell scripts or when the input data is in an unexpected format.
 
 <!-- Link definitions -->
 [00]: ../../../../concepts/dsc/resource-capabilities.md
-[01]: ./examples/run-simple-powershell-script.md
+[01]: ./examples/run-a-simple-powershell-script.md
 [02]: ./examples/powershell-script-with-input-output.md
 [03]: ../RunCommandOnSet/index.md
 [04]: ../../PowerShell/index.md
diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/examples/manage-windows-service-state-with-powershell.md b/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/examples/manage-windows-service-state-with-powershell.md
index e69de29bb..54f39c2dc 100644
--- a/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/examples/manage-windows-service-state-with-powershell.md
+++ b/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/examples/manage-windows-service-state-with-powershell.md
@@ -0,0 +1,183 @@
+---
+description: >
+  Example showing how to use the Microsoft.DSC.Transitional/WindowsPowerShellScript resource
+  to get, test, and set Windows service state using inline Windows PowerShell 5.1 scripts.
+ms.date:     05/10/2026
+ms.topic:    reference
+title:       Manage Windows service state with PowerShell
+---
+
+# Manage Windows service state with PowerShell
+
+> [!IMPORTANT]
+> This example is intended to illustrate the capabilities and patterns of the
+> `Microsoft.DSC.Transitional/WindowsPowerShellScript` resource, not as a recommended approach for
+> managing Windows services. DSC ships the [`Microsoft.Windows/Service`][02] resource specifically
+> for this purpose. Use `Microsoft.Windows/Service` instead — it provides a dedicated schema,
+> better error messages, and does not require you to write inline scripts.
+
+This example shows how to use Windows PowerShell 5.1 scripts to get the status of a Windows
+service, test whether it is running, and start or stop it.
+
+## Get service status
+
+The following snippet uses the [dsc resource get][03] command to retrieve the current status of the
+**Print Spooler** service.
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  $svc = Get-Service -Name $inputObj.name
+  [PSCustomObject]@{
+      name        = $svc.Name
+      displayName = $svc.DisplayName
+      status      = $svc.Status.ToString()
+      startType   = $svc.StartType.ToString()
+  }
+input:
+  name: spooler
+'@
+
+dsc resource get --resource Microsoft.DSC.Transitional/WindowsPowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  output:
+    - name:        spooler
+      displayName: Print Spooler
+      status:      Running
+      startType:   Automatic
+```
+
+## Test service state
+
+The following snippet uses the [dsc resource test][04] command to check whether the **Print
+Spooler** service is running. The `testScript` must return exactly one boolean value.
+
+```powershell
+$instance = @'
+testScript: |
+  param($inputObj)
+  $svc = Get-Service -Name $inputObj.name
+  $svc.Status -eq 'Running'
+input:
+  name: spooler
+'@
+
+dsc resource test --resource Microsoft.DSC.Transitional/WindowsPowerShellScript --input $instance
+```
+
+```yaml
+actualState:
+  _inDesiredState: true
+inDesiredState: true
+differingProperties: []
+```
+
+## Set service state
+
+The following snippet uses the [dsc resource set][05] command to ensure the **Print Spooler**
+service is running. The `getScript` captures `beforeState` and the `setScript` starts the service
+if it is not already running, then captures `afterState`.
+
+```powershell
+$instance = @'
+getScript: |
+  param($inputObj)
+  $svc = Get-Service -Name $inputObj.name
+  [PSCustomObject]@{
+      name   = $svc.Name
+      status = $svc.Status.ToString()
+  }
+setScript: |
+  param($inputObj)
+  $svc = Get-Service -Name $inputObj.name
+  if ($svc.Status -ne 'Running') {
+      Start-Service -Name $inputObj.name
+  }
+  $svc.Refresh()
+  [PSCustomObject]@{
+      name   = $svc.Name
+      status = $svc.Status.ToString()
+  }
+input:
+  name: spooler
+'@
+
+dsc resource set --resource Microsoft.DSC.Transitional/WindowsPowerShellScript --input $instance
+```
+
+```yaml
+beforeState:
+  output:
+    - name:   spooler
+      status: Stopped
+afterState:
+  output:
+    - name:   spooler
+      status: Running
+```
+
+## Using a configuration document
+
+The following configuration document ensures the **Print Spooler** service is running and the
+**Fax** service is stopped. Use the [dsc config set][01] command to enforce it.
+
+```yaml
+# services.config.dsc.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: ensureSpoolerRunning
+    type: Microsoft.DSC.Transitional/WindowsPowerShellScript
+    properties:
+      getScript: |
+        param($inputObj)
+        [PSCustomObject]@{ name = $inputObj.name; status = (Get-Service $inputObj.name).Status.ToString() }
+      testScript: |
+        param($inputObj)
+        (Get-Service -Name $inputObj.name).Status -eq 'Running'
+      setScript: |
+        param($inputObj)
+        Start-Service -Name $inputObj.name
+      input:
+        name: spooler
+
+  - name: ensureFaxStopped
+    type: Microsoft.DSC.Transitional/WindowsPowerShellScript
+    properties:
+      getScript: |
+        param($inputObj)
+        [PSCustomObject]@{ name = $inputObj.name; status = (Get-Service $inputObj.name).Status.ToString() }
+      testScript: |
+        param($inputObj)
+        (Get-Service -Name $inputObj.name).Status -eq 'Stopped'
+      setScript: |
+        param($inputObj)
+        Stop-Service -Name $inputObj.name -Force
+      input:
+        name: fax
+```
+
+```powershell
+dsc config set --file services.config.dsc.yaml
+```
+
+> [!TIP]
+> If you find yourself writing patterns like the one above for multiple services, switch to
+> [`Microsoft.Windows/Service`][02]. It handles the get/test/set logic for you with a declarative
+> schema and requires no inline scripts.
+>
+> More broadly, before writing any inline script resource, check whether DSC already ships a
+> purpose-built resource for what you need. Native resources provide validated schemas, better
+> error messages, and safer idempotency guarantees than hand-written scripts. Browse the
+> [resource reference][06] to see what is available.
+
+<!-- Link definitions -->
+[01]: ../../../../../../cli/config/set.md
+[02]: ../../../Windows/Service/index.md
+[03]: ../../../../../../cli/resource/get.md
+[04]: ../../../../../../cli/resource/test.md
+[05]: ../../../../../../cli/resource/set.md
+[06]: ../../../../../../resources/overview.md
diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/index.md b/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/index.md
index 12c64bf15..6f8e1e03f 100644
--- a/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/index.md
+++ b/docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/index.md
@@ -260,7 +260,7 @@ to the PowerShell scripts or when the input data is in an unexpected format.
 
 <!-- Link definitions -->
 [00]: ../../../../concepts/dsc/resource-capabilities.md
-[01]: ./examples/manage-windows-services-with-powershell.md
+[01]: ./examples/manage-windows-service-state-with-powershell.md
 [02]: ../PowerShellScript/index.md
 [03]: ../RunCommandOnSet/index.md
 [04]: ../../../../Microsoft/Windows/WindowsPowerShell/index.md