Skip to content

Environment Resource

Synopsis

Manages Windows environment variables at the User or Machine scope.

Type

OpenDsc.Windows/Environment

Capabilities

  • Get
  • Set
  • Delete
  • Export

Properties

name

The name of the environment variable.

Type: string
Required: Yes
Access: Read/Write
Default value: None

value

The value of the environment variable.

Type: string
Required: No
Access: Read/Write
Default value: None

scope

The scope. Accepts User or Machine.

Type: enum
Required: No
Access: Read/Write
Default value: User

_exist

Whether the variable should exist.

Type: bool
Required: No
Access: Read/Write
Default value: true

Note

Setting scope to Machine requires administrator privileges.

Examples

Example 1 — Get an environment variable

$resourceInput = @'
name: PATH
scope: Machine
'@

dsc resource get -r OpenDsc.Windows/Environment --input $resourceInput

resource_input=$(cat <<'EOF'
name: PATH
scope: Machine
EOF
)

dsc resource get -r OpenDsc.Windows/Environment --input "$resource_input"

actualState:
  name: PATH
  value: C:\Windows\system32;C:\Windows;...
  scope: Machine

Example 2 — Set an environment variable

$resourceInput = @'
name: APP_HOME
value: C:\MyApp
scope: User
'@

dsc resource set -r OpenDsc.Windows/Environment --input $resourceInput

resource_input=$(cat <<'EOF'
name: APP_HOME
value: C:\MyApp
scope: User
EOF
)

dsc resource set -r OpenDsc.Windows/Environment --input "$resource_input"

Example 3 — Delete an environment variable

$resourceInput = @'
name: APP_HOME
scope: User
'@

dsc resource delete -r OpenDsc.Windows/Environment --input $resourceInput

resource_input=$(cat <<'EOF'
name: APP_HOME
scope: User
EOF
)

dsc resource delete -r OpenDsc.Windows/Environment --input "$resource_input"

Example 4 — Export all environment variables

dsc resource export -r OpenDsc.Windows/Environment

Example 5 — Configuration document

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Set application home
    type: OpenDsc.Windows/Environment
    properties:
      name: APP_HOME
      value: C:\MyApp
      scope: Machine

  - name: Remove legacy variable
    type: OpenDsc.Windows/Environment
    properties:
      name: LEGACY_VAR
      scope: User
      _exist: false

Exit codes

Code Description
0 Success
1 Error
2 Invalid JSON
3 Access denied
4 Invalid argument