From e069e17ef9dba4929cba65d6ea94ea59bee42325 Mon Sep 17 00:00:00 2001 From: Guillermo Date: Tue, 27 Jan 2026 20:44:51 +0100 Subject: [PATCH] Add sample for Windows PowerShell (environment variable) --- .../env-variable/env.dsc.resource.json | 73 +++++++++++ .../resources/env-variable/env.resource.ps1 | 114 ++++++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 samples/powershell/resources/env-variable/env.dsc.resource.json create mode 100644 samples/powershell/resources/env-variable/env.resource.ps1 diff --git a/samples/powershell/resources/env-variable/env.dsc.resource.json b/samples/powershell/resources/env-variable/env.dsc.resource.json new file mode 100644 index 0000000..a222cf9 --- /dev/null +++ b/samples/powershell/resources/env-variable/env.dsc.resource.json @@ -0,0 +1,73 @@ +{ + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json", + "description": "Manages user/machine environment variables in Windows.", + "type": "Sample.Windows/EnvironmentVariable", + "version": "0.0.1", + "get": { + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$input | env.resource.ps1 -Operation get" + ], + "input": "stdin" + }, + "set": { + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$input | env.resource.ps1 -Operation set" + ], + "input": "stdin" + }, + "delete": { + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$input | env.resource.ps1 -Operation delete" + ], + "input": "stdin" + }, + "exitCodes": { + "0": "Success", + "1": "Error", + "2": "Invalid parameters" + }, + "schema": { + "embedded": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": [ + "object", + "null" + ], + "properties": { + "name": { + "type": "string", + "readOnly": true + }, + "value": { + "type": [ + "string", + "null" + ], + "readOnly": true + }, + "scope": { + "type": [ + "string", + "null" + ], + "readOnly": true + } + } + } + } +} diff --git a/samples/powershell/resources/env-variable/env.resource.ps1 b/samples/powershell/resources/env-variable/env.resource.ps1 new file mode 100644 index 0000000..91d79f9 --- /dev/null +++ b/samples/powershell/resources/env-variable/env.resource.ps1 @@ -0,0 +1,114 @@ +[CmdletBinding()] +param( + [ValidateSet('get', 'set', 'delete')] + [string]$Operation, + [Parameter(Mandatory, ValueFromPipeline)] + [string]$InputObject +) + +function Write-DSCTrace +{ + param( + [ValidateSet('info', 'warn', 'error')] + [string]$Level, + [ValidateNotNullOrEmpty()] + [string]$Message + ) + + # We MUST follow a prescriptive format for logs/traces. + $Host.UI.WriteErrorLine((@{ $Level = $Message } | ConvertTo-Json -Compress)) +} + +Write-DSCTrace warn "This DSC Resource displays unredacted environment variable values." + +Set-Variable -Option ReadOnly -Name Parameters -Value ($Input | ConvertFrom-Json) +Set-Variable -Option Constant -Name ExitCodeParameterError -Value 2 + +if ($Parameters.scope -notin ('user', 'machine')) +{ + Write-DSCTrace error "Invalid parameter 'scope': $($Parameters.scope)." + + # FIXME: Ignored? DSC always returns 1. + exit $ExitCodeParameterError +} + +Set-Variable -Option ReadOnly -Name EnvironmentVariableTarget -Value ([System.EnvironmentVariableTarget]$Parameters.scope) + +$result = @{ name = $null ; value = $null ; scope = $null } + +switch ($Operation) +{ + 'get' + { + if ([string]::IsNullOrWhiteSpace($Parameters.name)) + { + Write-DSCTrace error "Invalid parameter 'name': $($Parameters.name)." + + exit $ExitCodeParameterError + } + + $value = [System.Environment]::GetEnvironmentVariable($Parameters.name, $EnvironmentVariableTarget) + + # Assume env var set to null doesn't exist. + $result['name'] = if ($null -ne $value) { $Parameters.name } else { $null } + $result['value'] = $value + $result['scope'] = $EnvironmentVariableTarget.ToString().ToLower() + } + 'set' + { + if ([string]::IsNullOrWhiteSpace($Parameters.name) -or [string]::IsNullOrEmpty($Parameters.value)) + { + Write-DSCTrace error "Invalid value for parameter 'name' ($($Parameters.name)) or parameter 'value' ($($Parameters.value))." + + exit $ExitCodeParameterError + } + + if ($EnvironmentVariableTarget -eq [System.EnvironmentVariableTarget]::Machine) + { + Write-DSCTrace error "The 'set' operation for the scope 'machine' is not implemented." + + exit 1 + } + + Write-DSCTrace info "Setting environment variable '$($Parameters.name)' to '$($Parameters.value)' ($EnvironmentVariableTarget)." + + [System.Environment]::SetEnvironmentVariable($Parameters.name, $Parameters.value, $EnvironmentVariableTarget) + + $result["name"] = $Parameters.name + $result["value"] = [System.Environment]::GetEnvironmentVariable($Parameters.name, $EnvironmentVariableTarget) + $result["scope"] = $EnvironmentVariableTarget.ToString().ToLower() + } + 'delete' + { + if ([string]::IsNullOrWhiteSpace($Parameters.name)) + { + Write-DSCTrace error "Invalid parameter 'name': $($Parameters.name)" + + exit $ExitCodeParameterError + } + + if ($EnvironmentVariableTarget -eq [System.EnvironmentVariableTarget]::Machine) + { + Write-DSCTrace error "The 'delete' operation for the scope 'machine' is not implemented." + + exit 1 + } + + Write-DSCTrace info "Deleting environment variable '$($Parameters.name)' ($EnvironmentVariableTarget)." + + [System.Environment]::SetEnvironmentVariable($Parameters.name, $null, $EnvironmentVariableTarget) + + $result["name"] = $Parameters.name + $result["value"] = [System.Environment]::GetEnvironmentVariable($Parameters.name, $EnvironmentVariableTarget) + $result["scope"] = $EnvironmentVariableTarget.ToString().ToLower() + } + default + { + Write-DSCTrace error "Operation not implemented: $Operation." + + exit 1 + } +} + +return $result | ConvertTo-Json -Compress +