1

In a PowerShell script I have a function like Log-Statistics() which just outputs some stuff to stdout. But it might as well output stuff to a specific log file.

However, Log- is not an approved PS verb.

Any recommends ?

I'm considering:

  • Out-Statistics()
  • Write-Statistics()
  • LogStatistics()
orion elenzil
  • 4,484
  • 3
  • 37
  • 49
  • 1
    How is `Out-Log()`/`ol()`? You're question is a bit unclear, can you clarify what you want? Sounds like `Out-File` will do the same thing... – Nico Nekoru Jul 08 '20 at 21:44
  • 2
    Per the PowerShell approved verbs Write- would be appropriate. If you are updating an existing log Update-. If you are overwriting the log Set- would be used. Pretty much your choice. – RetiredGeek Jul 08 '20 at 21:53
  • 1
    the idea that i have most often seen is `Write-SpiffyThing` or some variant of that. [*grin*] – Lee_Dailey Jul 08 '20 at 22:00

3 Answers3

2

Considering other examples, I have decided to go with WRITE as it does do actions to write (either on screen or as file). OUT (for me) implies that this is output (i.E. end of pipeline)

I have Write-Log and Write-ErrorLog as helper functions (and other variations thereof) that I use (though not best practice, I generally fit my Write-Log with an -Append switch as to not overwrite a log (and to find all instances where I do write output quickly). Ideally that is done with the already existing Add-Content).

It also fits neatly into their cousins, Write-Error, Write-Warning, Write-Verbose, etc.

DEberhardt
  • 21
  • 3
1

The documentation you link to unfortunately doesn't reflect the fact that what Out-* cmdlets have in common is to use PowerShell's for-display output formatting system (resulting in rich, multi-line representations of objects).

Given that logs are usually line-oriented and should ideally be suited to programmatic processing, Out is therefore not the right verb[1] to use.

Note that PowerShell commands do not write their (regular) output to stdout (standard output) as such, given that PowerShell has a more sophisticated system of 6 output streams - see about_Redirections - where stream number 1, the success output stream, is meant for data only.

Add, following the example of Add-Content, appends to an existing resource while creating it on demand.

However, this logic isn't consistent among built-in cmdlets, as some have only a create-or-replace-by-default form (e.g., Out-File), with an optional -Append switch as an opt-in to appending content.

Based on the above, one option is:

  • Use Add-Statistics and, by default, have it output to the information stream (6), via
    Write-Information (assuming the command is implemented in PowerShell), so it doesn't interfere with data (success-stream) output.

    • Note: Write-Information is silent by default, which you can change via the -InformationAction common parameter or the $InformationPreference preference variable. Alternatively, use Write-Host, which (in PSv5+) also writes to the information stream (6), but its output does display by default.

  • Either add an -OutFile parameter to Add-Statistics to write to a file instead (creating it on demand), or let the caller redirect the information-stream output to a file with something like 6>log.txt (which works even when Write-Information output would be silent, if not redirected).

[1] As stated in the linked documentation, "verb" is used loosely here; some of PowerShell's approved verbs aren't verbs in a strict natural-language grammar sense.

mklement0
  • 382,024
  • 64
  • 607
  • 775
0

I would use something like Invoke-LogStatistics()

stevepowell2000
  • 473
  • 3
  • 10