Tee object can now store received error records to a variable.

[JamesWTruher]

This addresses an aspect of issue #5184

PR Summary

This adds the parameter -ErrorRecordVariable (Alias ERV) to Tee-Object if Tee-Object receives an ErrorRecord in the input stream and -ErrorRecordVariable is included, Tee-Object will assign those error records to the variable. This enables the following scenario:

PS> Get-Item $PSHOME,doesnotexist 2>&1 | Tee-Object -var out -ERV ee

    Directory: /Users/james/src/github/forks/jameswtruher/PowerShell-1/src/powershell-unix/bin/Debug/net9.0/osx-x64

UnixMode         User Group         LastWriteTime         Size Name
--------         ---- -----         -------------         ---- ----
drwxr-xr-x      james staff        5/1/2024 11:34         9024 publish

PS> $out

    Directory: /Users/james/src/github/forks/jameswtruher/PowerShell-1/src/powershell-unix/bin/Debug/net9.0/osx-x64

UnixMode         User Group         LastWriteTime         Size Name
--------         ---- -----         -------------         ---- ----
drwxr-xr-x      james staff        5/1/2024 11:34         9024 publish

PS> $ee
Get-Item: Cannot find path '/Users/james/src/github/forks/jameswtruher/PowerShell-1/src/Microsoft.PowerShell.Commands.Utility/commands/utility/doesnotexist' because it does not exist.
PS>

It works with file, literalfile, and variable parameter sets. This works with native executables as well, as when stderr is written, we create an error record. Errors created by Tee-Object are emitted in the normal way, it is only the input object which is inspected and handled by this new behavior. Note: the 2>&1 is required to ensure that the error stream is emitted into the output stream

PR Context

PR Checklist

• [x] PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• [x] Summarized changes
• [x] Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• [x] This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• Breaking changes
  • [x] None
  • OR
  • [ ] Experimental feature(s) needed
    • [ ] Experimental feature name(s):
• User-facing changes
  • [ ] Not Applicable
  • OR
  • [x] Documentation needed
    • [ ] Issue filed:
• Testing - New and feature
  • [ ] N/A or can only be tested interactively
  • OR
  • [x] Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • [x] I have considered the user experience from a tooling perspective and don't believe tooling will be impacted.
  • OR
  • [ ] I have considered the user experience from a tooling perspective and opened an issue in the relevant tool repository. This may include:
    • [ ] Impact on PowerShell Editor Services which is used in the PowerShell extension for VSCode (which runs in a different PS Host).
      • [ ] Issue filed:
    • [ ] Impact on Completions (both in the console and in editors) - one of PowerShell's most powerful features.
      • [ ] Issue filed:
    • [ ] Impact on PSScriptAnalyzer (which provides linting & formatting in the editor extensions).
      • [ ] Issue filed:
    • [ ] Impact on EditorSyntax (which provides syntax highlighting with in VSCode, GitHub, and many other editors).
      • [ ] Issue filed:

[Jaykul]

From the example, you seem to have eaten the error!?

Tee-Object should still pass through errors, surely.

[Jaykul]

Incidentally, is it even possible to get output in -OutVariable or -ErrorVariable from this command?

I mean, even when I do, say | Tee-Object -File Variable:\Foo or | Tee -File NoSuchDrive:\log.txt I do not get an error.

It's weird to me that it has two parameters for output and error variables, but the one we all EXPECT ... does not work. It's pretty confusing.

[SteveL-MSFT]

Incidentally, is it even possible to get output in -OutVariable or -ErrorVariable from this command?

I mean, even when I do, say | Tee-Object -File Variable:\Foo or | Tee -File NoSuchDrive:\log.txt I do not get an error.

It's weird to me that it has two parameters for output and error variables, but the one we all EXPECT ... does not work. It's pretty confusing.

If you redirect stderr to stdout and pipe to Tee-Object, you'll get both into the output stream and can do whatever you want. We thought the ask was to be able to handle stderr separately thus the new variable to de-multiplex it. Certainly you could do this yourself just by looking at the type of object and this was a convenience feature.

[mklement0]

@SteveL-MSFT, while I can appreciate what this PR is trying to achieve, I think it is ultimately the wrong way to go about it, especially given that it requires modifying the call that provides the input (2>&1) in order to work meaningfully.

• 20381 is a great extension to how > and >> work, but it is currently limited to consuming the targeted stream; that is, unlike with the common -*Variable parameters, the stream isn't passed through.

• Extending the 2> variable:foo syntax to optionally support pass-through - which you yourself suggested and as previously discussed, where I floated the idea of 2>| variable:foo - strikes me as the better alternative to extending Tee-Object.