Better backwards compatibility w/ 5.1

[juliusl]

Summary of the new feature / enhancement

There are a lot of changes between PS 5.X and PS 7.X, and some of these changes make keeping scripts backwards compatible difficult,

Some examples,

Invoke-WebRequest

The return type has changed and some useful parsing has been removed. This would be mostly tolerable but currently accessing headers is a pain in 7.1 is a bit painful. For example,

$response = Invoke-WebRequest "https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.manifest"

API's like this would include Last-Modified as a header. In 5.1 this allowed direct access to the datetime via,

$lastModified = $response.BaseResponse.LastModified

In 7.X the return type has changed, so now it would be,

$response = Invoke-WebRequest "https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.manifest"
$lastModified = [DateTime]$response.BaseResponse.Headers.'Last-Modified'[0]

The problem is here, https://learn.microsoft.com/en-us/dotnet/api/microsoft.powershell.commands.webresponseobject.headers?view=powershellsdk-7.2.0#microsoft-powershell-commands-webresponseobject-headers, which is a Dictionary<String, IEnumerable<String>>.

In order to make this backwards compatible, you would need to write code like this,

$lastModified = $response.Headers.'Last-Modified'

if ($PSVersionTable.PSVersion.Major -gt 5) {
    $lastModified = [DateTime]$lastModified[0]
} else {
    $lastModified = [DateTime]$lastModified
}

Set-Content

Previously, byte encoding was an option in the Encoding parameter. So in 5.1, you could do this,

Set-Content "file" ([byte[]][char[]] "$content") -Encoding Byte

But in 7.X, it's now,

Set-Content "file" ([byte[]][char[]] "$content") -AsByteStream

So now to support backwards compatibility, you would need to write,

if ($PSVersionTable.PSVersion.Major -gt 5) {
  Set-Content "file" ([byte[]][char[]] "$content") -AsByteStream
} else {
  Set-Content "file" ([byte[]][char[]] "$content") -Encoding Byte
}

These are just two examples, and others may have some other examples, but as you can see these are very tiny inconsistencies that end up doubling code.

Proposed technical implementation details (optional)

I'm not sure how to address this problem, but I think part of the challenge is being able to collect feedback about specific backwards compat problems.

Other than that perhaps there could be some sort of polyfill solution, or some sort of dedicated module that bridges 5.1 <-> 7.X. Or maybe some code analysis rules added to the powershell language server for vscode.

If nothing else, maybe there needs to be some sort of knowledge base or wiki in this repo that documents these nuances.

I'm pretty sure it is probably too late to change binaries so maybe this is something 8.0 can address (although then there might be backwards compat issues between 7 -> 8).

[mklement0]

As for:

there needs to be some sort of knowledge base or wiki in this repo that documents these nuances.

There's an official page here, and I encourage you to suggest additions / corrections, as warranted: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell

---

Fundamentally, the cross-edition changes fall into the following categories:

• Unavoidable / justifiable changes:

  • Changes in the underlying .NET APIs, in which case PowerShell is just the messenger:

    • Your Invoke-WebRequest example falls into that category.
    • This also extends to cmdlets no longer being available due to the underlying .NET APIs no longer offering the required support, such as the PSScheduledJob module and its cmdlets.

  • Changes that were made for the sake of better cross-platform compatibility:

    • E.g., the CLI now defaulting to -File instead of -Command, and the removal of built-in aliases such as ls that would shadow platform-native utilities (not using aliases altogether in scripts avoids that problem; interactively, use only PowerShell-idiomatic aliases, such as gci).

  • Changes, which - despite being technically breaking - were deemed to be beneficial to a degree that outweighs breaking some code, potentially; in other words: bucket 3 changes.

    • Example: New-Item: When creating symbolic links (symlinks) / reparse points, the -Target path should always be treated as a *literal* path #13136

• Ill-advised changes that could / possibly will be reversed:

  • Getting the default wrong: making a change that is beneficial in principle, but, by making it opt-out, breaking a lot of existing code:

    • Change $PSNativeCommandArgumentPassing to default to Legacy on stable release and Windows on previews #18694 is a prime example.

  • Frivolous changes that needlessly broke a lot of code while adding no value:

    • No longer supporting -Encoding Byte in favor of requiring -AsByteStream is a prime example (it is mentioned in the linked docs page, but that's little consolation).

  • Unacknowledged / neglected regression bugs; e.g.:

    • Breaking --%: Stop-parsing token is broken #18664
    • Breaking string interpolation in native argument-passing: PowerShell 7.3 doesn't pass variable values / cmdlet results arguments to child processes when comma is present #18502

Differences between Windows PowerShell 5.1 and PowerShell 7.x - PowerShell

This article summarizes the differences and breaking changes from Windows PowerShell 5.1 and the current version of PowerShell that is based on .NET Core.

[iSazonov]

The gap between WinPS 5.1 and pwsh is already huge - there are probably hundreds of differences. The distance between them is increasing every day. We can assume that in 2-3 years the compatibility policy will have to be abandoned in fact.

[aguzev]

The PS7 version looks more generic because there is no guarantee that Last-Modified cannot have multiple values. An array of datetime looks like an alternative for the if monster:

PS> [datetime[]]("2022-12-29","2023-01-20")

Thursday, December 29, 2022 12:00:00 AM
Friday, January 20, 2023 12:00:00 AM

PS> [datetime[]]"2022-12-29"

Thursday, December 29, 2022 12:00:00 AM

[juliusl]

In this case Last-Modified is part of rfc9110, so there is somewhat of a guarantee - https://httpwg.org/specs/rfc9110.html#rfc.section.8.8.2

[theJasonHelmick]

Thank you @juliusl for taking the time to report this. PowerShell 7 is not intended to be in complete parity with Windows PowerShell 5.1. There are situations we have decided to not remain compatible. We feel that the your invoke-webrequest issue is something that should be investigated and encourage you to open it as a single issue.

[ghost]

This issue has been marked as answered and has not had any activity for 1 day. It has been closed for housekeeping purposes.