Make PowerShell 5.1 usage more prominent

[martincostello]

Make requirement to use Windows PowerShell to install zero-code instrumentation for .NET on Windows more prominent.

Also add directive to the script to fail if the wrong version of PowerShell is used.

See open-telemetry/opentelemetry-dotnet-instrumentation#2018.

[Copilot]

Pull Request Overview

This PR makes the usage of Windows PowerShell for installing zero-code instrumentation on .NET more explicit by emphasizing that only the built-in PowerShell 5.1 is supported.

• Added a highlighted alert to warn users against using PowerShell 6.0+ (pwsh).
• Updated the inline comment and introduced the "#Requires -PSEdition Desktop" directive to fail early when an incorrect version is used.

Comments suppressed due to low confidence (2)

content/en/docs/zero-code/dotnet/_index.md:88

• Consider rephrasing the alert message to improve clarity, e.g., 'PowerShell v6.0+ (pwsh) is not supported. Only the built-in Windows PowerShell 5.1 is supported for installing .NET zero-code instrumentation.'

PowerShell v6.0+ (pwsh) is not supported in install .NET zero-code instrumentation - the built-in version of Windows PowerShell must be used.

content/en/docs/zero-code/dotnet/_index.md:94

• Ensure the inline comment aligns with the alert message for consistency, clearly indicating that only Windows PowerShell 5.1 (the built-in edition) should be used.

# PowerShell 5.1 is required

[svrnm]

thanks @martincostello

@open-telemetry/dotnet-instrumentation-approvers please take a look and review/approve

[martincostello]

I can't for the life of me work out what the lint warning is about.

The CI logs don't say, and if I run it locally on my Windows laptop, then no edits are made when I use --write.

[svrnm]

I can't for the life of me work out what the lint warning is about.

The CI logs don't say, and if I run it locally on my Windows laptop, then no edits are made when I use --write.

I see that... it's odd, don't worry about that, that's a maintainer issue.

[chalin]

/fix:format

[opentelemetrybot]

✅ fix:format applied successfully in this run.

[chalin]

Suggested change

	cSpell:ignore: coreutils HKLM iisreset myapp pwsh
	cSpell:ignore: coreutils HKLM iisreset myapp

[chalin]

Suggested change

	{{% alert title="Note" color="warning" %}} PowerShell v6.0+ (pwsh) is not
	supported to install .NET zero-code instrumentation. The built-in version of
	Windows PowerShell must be used. {{% /alert %}}
	On Windows, use the PowerShell module as an Administrator:
	On Windows, use the PowerShell module as an Administrator.
	{{% alert title="Version note" color="warning" %}}
	PowerShell v5.1 is required. In particular, v6.0+ is not yet supported.
	{{% /alert %}}

[martincostello]

There's some nuance here I think your suggested edit misses.

Windows PowerShell is basically v5 forever, there isn't a v6.

PowerShell (Core) (pwsh) started with v6 and is currently at v7.5.

The former is the Desktop edition, the latter is the Core edition.

That's why my original copy explicitly distinguishes between the two by saying Windows PowerShell and clarifying v6 is pwsh.

[chalin]

Suggested change

	# PowerShell 5.1 is required
	#Requires -Version 5.1

[martincostello]

I'm not sure this is needed or not. All I know is it definitely doesn't work on the Core edition. I just removed "or higher" because there is no higher version of the Desktop edition and I'm not sure there ever will be.

[chalin]

@open-telemetry/dotnet-approvers @open-telemetry/dotnet-instrumentation-approvers - can someone validate the version requirements? Thx!