Skip to content

Commit 1465505

Browse files
sdwheelersdwheeler
authored
Add note about WhatIf for Tee-Object (MicrosoftDocs#12368)
1 parent 0dd7374 commit 1465505

File tree

4 files changed

+136
-20
lines changed

4 files changed

+136
-20
lines changed

‎reference/5.1/Microsoft.PowerShell.Utility/Tee-Object.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 12/12/2022
5+
ms.date: 09/17/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/tee-object?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -37,10 +37,14 @@ Tee-Object [-InputObject <PSObject>] -Variable <String> [<CommonParameters>]
3737

3838
## DESCRIPTION
3939

40-
The `Tee-Object` cmdlet redirects output, that is, it sends the output of a command in two
41-
directions (like the letter T). It stores the output in a file or variable and also sends it down
42-
the pipeline. If `Tee-Object` is the last command in the pipeline, the command output is displayed
43-
at the prompt.
40+
The `Tee-Object` cmdlet write output in two directions. It stores the output in a file or variable
41+
and also sends it down the pipeline. If `Tee-Object` is the last command in the pipeline, the
42+
command output is displayed in the console.
43+
44+
Internally, `Tee-Object` uses the `Set-Variable` and `Out-File` commands. These commands support the
45+
**WhatIf** parameter. The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if
46+
you wrap `Tee-Object` in a script or function that support the **WhatIf** parameter, `Tee-Object`
47+
passes the state of **WhatIf** to the `Set-Variable` and `Out-File` commands.
4448

4549
## EXAMPLES
4650

@@ -99,6 +103,31 @@ drive. A pipeline operator (`|`) sends the list to `Tee-Object`, which appends t
99103
AllSystemFiles.txt file and passes the list down the pipeline to the `Out-File` cmdlet, which saves
100104
the list in the `NewSystemFiles.txt file`.
101105

106+
### Example 4: Use `Tee-Object` in a script with the **WhatIf** parameter
107+
108+
The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if you wrap `Tee-Object`
109+
in a script or function that support the **WhatIf** parameter, `Tee-Object` passes the state of
110+
**WhatIf** to the `Set-Variable` and `Out-File` commands it uses internally.
111+
112+
```powershell
113+
PS> function Test-Tee {
114+
[Cmdletbinding(SupportsShouldProcess)]
115+
Param()
116+
$true|tee -Variable b
117+
"Variable `$b is set to '$b'"
118+
}
119+
120+
PS> Test-Tee
121+
122+
True
123+
Variable $b is set to 'True'
124+
125+
PS> Test-Tee -WhatIf
126+
True
127+
What if: Performing the operation "Set variable" on target "Name: b Value: True".
128+
Variable $b is set to ''
129+
```
130+
102131
## PARAMETERS
103132

104133
### -Append

‎reference/7.4/Microsoft.PowerShell.Utility/Tee-Object.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 04/25/2023
5+
ms.date: 09/17/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/tee-object?view=powershell-7.4&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -37,10 +37,14 @@ Tee-Object [-InputObject <PSObject>] -Variable <String> [<CommonParameters>]
3737

3838
## DESCRIPTION
3939

40-
The `Tee-Object` cmdlet redirects output, that is, it sends the output of a command in two
41-
directions (like the letter T). It stores the output in a file or variable and also sends it down
42-
the pipeline. If `Tee-Object` is the last command in the pipeline, the command output is displayed
43-
at the prompt.
40+
The `Tee-Object` cmdlet write output in two directions. It stores the output in a file or variable
41+
and also sends it down the pipeline. If `Tee-Object` is the last command in the pipeline, the
42+
command output is displayed in the console.
43+
44+
Internally, `Tee-Object` uses the `Set-Variable` and `Out-File` commands. These commands support the
45+
**WhatIf** parameter. The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if
46+
you wrap `Tee-Object` in a script or function that support the **WhatIf** parameter, `Tee-Object`
47+
passes the state of **WhatIf** to the `Set-Variable` and `Out-File` commands.
4448

4549
## EXAMPLES
4650

@@ -151,6 +155,31 @@ and comparing that string to `$frontMatterPattern`.
151155
Finally, the example prints the names of the files in the folder that have a defined front matter
152156
metadata block.
153157

158+
### Example 5: Use `Tee-Object` in a script with the **WhatIf** parameter
159+
160+
The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if you wrap `Tee-Object`
161+
in a script or function that support the **WhatIf** parameter, `Tee-Object` passes the state of
162+
**WhatIf** to the `Set-Variable` and `Out-File` commands it uses internally.
163+
164+
```powershell
165+
PS> function Test-Tee {
166+
[Cmdletbinding(SupportsShouldProcess)]
167+
Param()
168+
$true|tee -Variable b
169+
"Variable `$b is set to '$b'"
170+
}
171+
172+
PS> Test-Tee
173+
174+
True
175+
Variable $b is set to 'True'
176+
177+
PS> Test-Tee -WhatIf
178+
True
179+
What if: Performing the operation "Set variable" on target "Name: b Value: True".
180+
Variable $b is set to ''
181+
```
182+
154183
## PARAMETERS
155184

156185
### -Append

‎reference/7.5/Microsoft.PowerShell.Utility/Tee-Object.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 04/25/2023
5+
ms.date: 09/17/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/tee-object?view=powershell-7.5&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -37,10 +37,14 @@ Tee-Object [-InputObject <PSObject>] -Variable <String> [<CommonParameters>]
3737

3838
## DESCRIPTION
3939

40-
The `Tee-Object` cmdlet redirects output, that is, it sends the output of a command in two
41-
directions (like the letter T). It stores the output in a file or variable and also sends it down
42-
the pipeline. If `Tee-Object` is the last command in the pipeline, the command output is displayed
43-
at the prompt.
40+
The `Tee-Object` cmdlet write output in two directions. It stores the output in a file or variable
41+
and also sends it down the pipeline. If `Tee-Object` is the last command in the pipeline, the
42+
command output is displayed in the console.
43+
44+
Internally, `Tee-Object` uses the `Set-Variable` and `Out-File` commands. These commands support the
45+
**WhatIf** parameter. The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if
46+
you wrap `Tee-Object` in a script or function that support the **WhatIf** parameter, `Tee-Object`
47+
passes the state of **WhatIf** to the `Set-Variable` and `Out-File` commands.
4448

4549
## EXAMPLES
4650

@@ -151,6 +155,31 @@ and comparing that string to `$frontMatterPattern`.
151155
Finally, the example prints the names of the files in the folder that have a defined front matter
152156
metadata block.
153157

158+
### Example 5: Use `Tee-Object` in a script with the **WhatIf** parameter
159+
160+
The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if you wrap `Tee-Object`
161+
in a script or function that support the **WhatIf** parameter, `Tee-Object` passes the state of
162+
**WhatIf** to the `Set-Variable` and `Out-File` commands it uses internally.
163+
164+
```powershell
165+
PS> function Test-Tee {
166+
[Cmdletbinding(SupportsShouldProcess)]
167+
Param()
168+
$true|tee -Variable b
169+
"Variable `$b is set to '$b'"
170+
}
171+
172+
PS> Test-Tee
173+
174+
True
175+
Variable $b is set to 'True'
176+
177+
PS> Test-Tee -WhatIf
178+
True
179+
What if: Performing the operation "Set variable" on target "Name: b Value: True".
180+
Variable $b is set to ''
181+
```
182+
154183
## PARAMETERS
155184

156185
### -Append

‎reference/7.6/Microsoft.PowerShell.Utility/Tee-Object.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 04/25/2023
5+
ms.date: 09/17/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/tee-object?view=powershell-7.6&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -37,10 +37,14 @@ Tee-Object [-InputObject <PSObject>] -Variable <String> [<CommonParameters>]
3737

3838
## DESCRIPTION
3939

40-
The `Tee-Object` cmdlet redirects output, that is, it sends the output of a command in two
41-
directions (like the letter T). It stores the output in a file or variable and also sends it down
42-
the pipeline. If `Tee-Object` is the last command in the pipeline, the command output is displayed
43-
at the prompt.
40+
The `Tee-Object` cmdlet write output in two directions. It stores the output in a file or variable
41+
and also sends it down the pipeline. If `Tee-Object` is the last command in the pipeline, the
42+
command output is displayed in the console.
43+
44+
Internally, `Tee-Object` uses the `Set-Variable` and `Out-File` commands. These commands support the
45+
**WhatIf** parameter. The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if
46+
you wrap `Tee-Object` in a script or function that support the **WhatIf** parameter, `Tee-Object`
47+
passes the state of **WhatIf** to the `Set-Variable` and `Out-File` commands.
4448

4549
## EXAMPLES
4650

@@ -151,6 +155,31 @@ and comparing that string to `$frontMatterPattern`.
151155
Finally, the example prints the names of the files in the folder that have a defined front matter
152156
metadata block.
153157

158+
### Example 5: Use `Tee-Object` in a script with the **WhatIf** parameter
159+
160+
The `Tee-Object` command doesn't support the **WhatIf** parameter. However, if you wrap `Tee-Object`
161+
in a script or function that support the **WhatIf** parameter, `Tee-Object` passes the state of
162+
**WhatIf** to the `Set-Variable` and `Out-File` commands it uses internally.
163+
164+
```powershell
165+
PS> function Test-Tee {
166+
[Cmdletbinding(SupportsShouldProcess)]
167+
Param()
168+
$true|tee -Variable b
169+
"Variable `$b is set to '$b'"
170+
}
171+
172+
PS> Test-Tee
173+
174+
True
175+
Variable $b is set to 'True'
176+
177+
PS> Test-Tee -WhatIf
178+
True
179+
What if: Performing the operation "Set variable" on target "Name: b Value: True".
180+
Variable $b is set to ''
181+
```
182+
154183
## PARAMETERS
155184

156185
### -Append

0 commit comments

Comments
 (0)