docs: Update PSScript examples

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

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

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