From 0d935b696f7e4f750c528ce2fe423e3091885a96 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 5 Dec 2024 08:10:58 -0600 Subject: [PATCH] Provide a reason for this rule --- .../Rules/AvoidUsingWriteHost.md | 27 ++++++++++++------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingWriteHost.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingWriteHost.md index 5619141..a02571c 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingWriteHost.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingWriteHost.md @@ -1,6 +1,6 @@ --- description: Avoid Using Write-Host -ms.date: 06/28/2023 +ms.date: 12/05/2024 ms.topic: reference title: AvoidUsingWriteHost --- @@ -10,10 +10,15 @@ title: AvoidUsingWriteHost ## Description -The use of `Write-Host` is greatly discouraged unless in the use of commands with the `Show` verb. -The `Show` verb explicitly means 'show on the screen, with no other possibilities'. +The primary purpose of the `Write-Host` cmdlet is to produce display-only output in the host. For +example: printing colored text or prompting the user for input when combined with `Read-Host`. +`Write-Host` uses the `ToString()` method to write the output. The particular result depends on the +program that's hosting PowerShell. The output from `Write-Host` isn't sent to the pipeline. To +output data to the pipeline, use `Write-Output` or implicit output. -Commands with the `Show` verb do not have this check applied. +The use of `Write-Host` in a function is discouraged unless the function uses the `Show` verb. The +`Show` verb explicitly means _display information to the user_. This rule doesn't apply to functions +with the `Show` verb. ## How @@ -27,22 +32,22 @@ logging or returning one or more objects. ```powershell function Get-MeaningOfLife { - ... Write-Host 'Computing the answer to the ultimate question of life, the universe and everything' - ... Write-Host 42 } ``` ### Correct +Use `Write-Verbose` for informational messages. The user can decide whether to see the message by +providing the **Verbose** parameter. + ```powershell function Get-MeaningOfLife { - [CmdletBinding()]Param() # to make it possible to set the VerbosePreference when calling the function - ... + [CmdletBinding()]Param() # makes it possible to support Verbose output + Write-Verbose 'Computing the answer to the ultimate question of life, the universe and everything' - ... Write-Output 42 } @@ -51,3 +56,7 @@ function Show-Something Write-Host 'show something on screen' } ``` + +## More information + +[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host)