PR Summary

Always use the v5.1 $using: logic when dealing with any connection type that is not based on the WSManConnectionInfo. This allows the caller to use the more advanced $using features like vars with special names, $using vars inside sub scopes and more. WSMan based connections might still communicate with older versions but as the oldest supported version is v3 on Server 2012 we don't need to keep the default as v2 to support some of the newer features.

PR Context

There are three different ways that Invoke-Command deals with $using: inside a ScriptBlock:

• V2 - replaces the ScriptBlock text to change $using:var to $__using_var and modifies the param block to pass in that variable
• V3/4 - builds an array containing the $using:var and passes it to the remote pipeline through --%
• V5+ - like the above but uses a hashtable and has better support for $using: in child scopes

The V2 method is quite rudimentary, it fails when using a variable with an invalid char in like -, or in a very improbable scenario someone named their var as $__using_var themselves. The - problem is typically encountered when you try to inject a function into the scriptblock, for example this fails today

Function Test-Function { 'foo' }

Invoke-Command -HostName server {
    ${function:Test-Function} = ${using:function:Test-Function}
    
    Test-Function
}

At line:1 char:29
+ param($__using_function_Test-Function)
+                             ~
Missing ')' in function parameter list.

At line:1 char:38
+ param($__using_function_Test-Function)
+                                      ~
Unexpected token ')' in expression or statement.

At line:3 char:55
+     ${function:Test-Function} = $__using_function_Test-Function
+                                                       ~~~~~~~~~
Unexpected token '-Function' in expression or statement.

The workaround is to store the function in an intermediate var or define the function without - in the name:

Function Test-Function { 'foo' }

$testFunction = ${function:Test-Function}
Invoke-Command -HostName server {
    ${function:Test-Function} = ${using:testFunction}
    
    Test-Function
}

# or

Function Function { 'foo' }

Invoke-Command -HostName server {
    ${function:Test-Function} = ${using:function:Function}
    
    Test-Function
}

The V3/4, V5 logic works just fine with vars with special chars in the name

Function Test-Function { 'foo' }

$s = New-PSSession -UseWindowsPowerShell
Invoke-Command -Session $s {
    ${function:Test-Function} = ${using:function:Test-Function}
    
    Test-Function
}
$s | Remove-PSSession

The current logic for determining what logic to use is as follows

• If the connection info is NewProcessConnectionInfo use V5
  • This only applies to Start-Job or if using -Session $s where the $s is from New-PSSession -UseWindowsPowerShell
• If not an explicit PSSession through the -Session parameter use V2
• If the PSSession supports disconnection operations
  • Use the PSVersionTable.PSVersion to determine the version
  • Only WSMan on Windows satisfies this check
• All other scenarios default to V2

This means that V3/4, V5 is only used when the PSSession from New-PSSession -UseWindowsPowerShell or New-PSSession -ComputerName ... is given to Invoke-Command -Session .... The more common scenarios like Invoke-Command -ComputerName ... or Invoke-Command -HostName ... will always use the old V2 logic and thus cannot use the newer $using: features.

This PR simplifies the checks to set the baseline to V3/4 for a WSMan based connection and treat the rest of the connection types as V5. This is because only the WSMan connection was supported before 5.1 and can guarantee the target is PowerShell 5.1 or newer. The baseline for WSMan was set to V3/4 as V2 was last in box with Windows 7/Server 2008/08 R2 which is end of life. V3/4 is also strictly end of life but considering it's still supported in Azure I didn't think it was time to drop that just yet.

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• 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
  • None - Strictly speaking it can break V2 targets when you use $using:
  • OR
  • Experimental feature(s) needed
    • Experimental feature name(s):
• User-facing changes
  • Not Applicable
  • OR
  • Documentation needed
    - [ ] Issue filed:
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • 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: