Skip to content

Commit 9c8ea54

Browse files
sdwheelersdwheeler
authored
Update notes about assigning null values (MicrosoftDocs#12316)
1 parent ceaddb0 commit 9c8ea54

2 files changed

Lines changed: 142 additions & 68 deletions

File tree

‎reference/7.5/Microsoft.PowerShell.Core/About/about_Environment_Variables.md‎

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how to access and manage environment variables in PowerShell.
33
Locale: en-US
4-
ms.date: 09/05/2024
4+
ms.date: 08/27/2025
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.5&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about_Environment_Variables
@@ -122,38 +122,24 @@ The 'Foo' environment variable is set to: An example
122122
An example!
123123
```
124124

125-
In PowerShell, an environment variable can't be set to an empty string. Setting
126-
an environment variable to `$null` or an empty string removes it from the
127-
current session. For example:
125+
Beginning in PowerShell 7.5, you can set an environment variable to an empty string. Setting an
126+
environment variable to `$null` removes it from the current session. For example:
128127

129128
```powershell
130-
$Env:Foo = ''
131-
$Env:Foo | Get-Member -MemberType Properties
132-
```
129+
PS> $env:TEST = ''
130+
PS> Get-ChildItem env:TEST
133131
134-
```Output
135-
Get-Member : You must specify an object for the Get-Member cmdlet.
136-
At line:1 char:12
137-
+ $Env:foo | Get-Member
138-
+ ~~~~~~~~~~
139-
+ CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException
140-
+ FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand
141-
```
142-
143-
`Get-Member` returned an error because the environment variable was removed.
144-
You can see that it doesn't return an error when you use it on an empty
145-
string:
132+
Name Value
133+
---- -----
134+
TEST
146135
147-
```powershell
148-
'' | Get-Member -MemberType Properties
149-
```
136+
PS> $env:TEST = $null
137+
PS> $env:TEST.Length
138+
0
150139
151-
```Output
152-
TypeName: System.String
140+
PS> Get-ChildItem env:TEST
153141
154-
Name MemberType Definition
155-
---- ---------- ----------
156-
Length Property int Length {get;}
142+
Get-ChildItem: Cannot find path 'TEST' because it does not exist.
157143
```
158144

159145
For more information about variables in PowerShell, see [about_Variables][11].
@@ -208,6 +194,31 @@ Use the `Get-ChildItem` cmdlet to see a full list of environment variables:
208194
Get-ChildItem Env:
209195
```
210196

197+
Beginning in PowerShell 7.5, you can set an environment variable to an empty
198+
string using the environment provider and `Set-Item` cmdlet. Setting an
199+
environment variable to `$null` removes it from the current session. For
200+
example:
201+
202+
```powershell
203+
PS> Set-Item env:TEST 'Foo'
204+
PS> Get-ChildItem env:TEST
205+
206+
Name Value
207+
---- -----
208+
TEST Foo
209+
210+
PS> Set-Item env:TEST ''
211+
PS> Get-ChildItem env:TEST
212+
213+
Name Value
214+
---- -----
215+
TEST
216+
217+
PS> Set-Item -Path env:TEST -Value $null
218+
PS> Get-ChildItem env:TEST
219+
Get-ChildItem: Cannot find path 'TEST' because it does not exist.
220+
```
221+
211222
For more information on using the **Environment** provider to manage
212223
environment variables, see [about_Environment_Provider][04].
213224

@@ -228,19 +239,45 @@ of `Bar` and then returns its value.
228239
Bar
229240
```
230241

231-
You can remove an environment variable with the `SetEnvironmentVariable()`
232-
method by specifying an empty string for the variable's value. For example,
233-
to remove the `Foo` environment variable:
242+
Beginning in PowerShell 7.5, you can set an environment variable to an empty
243+
string using the `SetEnvironmentVariable()` method and specifying an empty
244+
string or `$null` for the variable's value. For example:
234245

235246
```powershell
236-
[Environment]::SetEnvironmentVariable('Foo','')
237-
[Environment]::GetEnvironmentVariable('Foo')
238-
```
247+
PS> [Environment]::SetEnvironmentVariable('Foo','Bar')
248+
PS> Get-ChildItem env:Foo
239249
240-
```Output
250+
Name Value
251+
---- -----
252+
Foo Bar
253+
254+
PS> [Environment]::SetEnvironmentVariable('Foo','')
255+
PS> Get-ChildItem env:Foo
256+
257+
Name Value
258+
---- -----
259+
Foo
260+
261+
PS> [Environment]::SetEnvironmentVariable('Foo','bar')
262+
PS> Get-ChildItem env:Foo
263+
264+
Name Value
265+
---- -----
266+
Foo bar
241267
268+
PS> [Environment]::SetEnvironmentVariable('Foo',$null)
269+
PS> Get-ChildItem env:Foo
270+
271+
Name Value
272+
---- -----
273+
Foo
242274
```
243275

276+
> [!NOTE]
277+
> Unlike the variable syntax and provider cases, assigning the value to `$null`
278+
> using the `SetEnvironmentVariable()` method doesn't remove the environment
279+
> variable.
280+
244281
For more information about the methods of the **System.Environment** class, see
245282
[Environment Methods][01].
246283

‎reference/7.6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md‎

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how to access and manage environment variables in PowerShell.
33
Locale: en-US
4-
ms.date: 09/05/2024
4+
ms.date: 08/27/2025
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.6&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about_Environment_Variables
@@ -122,38 +122,24 @@ The 'Foo' environment variable is set to: An example
122122
An example!
123123
```
124124

125-
In PowerShell, an environment variable can't be set to an empty string. Setting
126-
an environment variable to `$null` or an empty string removes it from the
127-
current session. For example:
125+
Beginning in PowerShell 7.5, you can set an environment variable to an empty string. Setting an
126+
environment variable to `$null` removes it from the current session. For example:
128127

129128
```powershell
130-
$Env:Foo = ''
131-
$Env:Foo | Get-Member -MemberType Properties
132-
```
129+
PS> $env:TEST = ''
130+
PS> Get-ChildItem env:TEST
133131
134-
```Output
135-
Get-Member : You must specify an object for the Get-Member cmdlet.
136-
At line:1 char:12
137-
+ $Env:foo | Get-Member
138-
+ ~~~~~~~~~~
139-
+ CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException
140-
+ FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand
141-
```
142-
143-
`Get-Member` returned an error because the environment variable was removed.
144-
You can see that it doesn't return an error when you use it on an empty
145-
string:
132+
Name Value
133+
---- -----
134+
TEST
146135
147-
```powershell
148-
'' | Get-Member -MemberType Properties
149-
```
136+
PS> $env:TEST = $null
137+
PS> $env:TEST.Length
138+
0
150139
151-
```Output
152-
TypeName: System.String
140+
PS> Get-ChildItem env:TEST
153141
154-
Name MemberType Definition
155-
---- ---------- ----------
156-
Length Property int Length {get;}
142+
Get-ChildItem: Cannot find path 'TEST' because it does not exist.
157143
```
158144

159145
For more information about variables in PowerShell, see [about_Variables][11].
@@ -208,6 +194,31 @@ Use the `Get-ChildItem` cmdlet to see a full list of environment variables:
208194
Get-ChildItem Env:
209195
```
210196

197+
Beginning in PowerShell 7.5, you can set an environment variable to an empty
198+
string using the environment provider and `Set-Item` cmdlet. Setting an
199+
environment variable to `$null` removes it from the current session. For
200+
example:
201+
202+
```powershell
203+
PS> Set-Item env:TEST 'Foo'
204+
PS> Get-ChildItem env:TEST
205+
206+
Name Value
207+
---- -----
208+
TEST Foo
209+
210+
PS> Set-Item env:TEST ''
211+
PS> Get-ChildItem env:TEST
212+
213+
Name Value
214+
---- -----
215+
TEST
216+
217+
PS> Set-Item -Path env:TEST -Value $null
218+
PS> Get-ChildItem env:TEST
219+
Get-ChildItem: Cannot find path 'TEST' because it does not exist.
220+
```
221+
211222
For more information on using the **Environment** provider to manage
212223
environment variables, see [about_Environment_Provider][04].
213224

@@ -228,19 +239,45 @@ of `Bar` and then returns its value.
228239
Bar
229240
```
230241

231-
You can remove an environment variable with the `SetEnvironmentVariable()`
232-
method by specifying an empty string for the variable's value. For example,
233-
to remove the `Foo` environment variable:
242+
Beginning in PowerShell 7.5, you can set an environment variable to an empty
243+
string using the `SetEnvironmentVariable()` method and specifying an empty
244+
string or `$null` for the variable's value. For example:
234245

235246
```powershell
236-
[Environment]::SetEnvironmentVariable('Foo','')
237-
[Environment]::GetEnvironmentVariable('Foo')
238-
```
247+
PS> [Environment]::SetEnvironmentVariable('Foo','Bar')
248+
PS> Get-ChildItem env:Foo
239249
240-
```Output
250+
Name Value
251+
---- -----
252+
Foo Bar
253+
254+
PS> [Environment]::SetEnvironmentVariable('Foo','')
255+
PS> Get-ChildItem env:Foo
256+
257+
Name Value
258+
---- -----
259+
Foo
260+
261+
PS> [Environment]::SetEnvironmentVariable('Foo','bar')
262+
PS> Get-ChildItem env:Foo
263+
264+
Name Value
265+
---- -----
266+
Foo bar
241267
268+
PS> [Environment]::SetEnvironmentVariable('Foo',$null)
269+
PS> Get-ChildItem env:Foo
270+
271+
Name Value
272+
---- -----
273+
Foo
242274
```
243275

276+
> [!NOTE]
277+
> Unlike the variable syntax and provider cases, assigning the value to `$null`
278+
> using the `SetEnvironmentVariable()` method doesn't remove the environment
279+
> variable.
280+
244281
For more information about the methods of the **System.Environment** class, see
245282
[Environment Methods][01].
246283

0 commit comments

Comments
 (0)