Need to normalize PowerShell notices

[reinhart1010]

A couple of months ago I noticed that we have three versions of PowerShell notices.

First, my original proposal (modified from android/ commands that can only be run under adb) as back as #6621 (used in 31 commands and subsequent translations):

# Example-Command

> Command Description.
> Note: This command can only be used through PowerShell.

The second, simplified version (5 commands and translations):

# Example-Command

> Command Description.
> This command can only be run under PowerShell.

And the third one (5 commands and translations),

# Example-Command

> A PowerShell utility (or external module) to ...

This relatively recent format has been placed in windows/add-appxpackage, windows/pswindowsupdate, windows/remove-appxpackage, and subsequent translations.

I think it's OK to document external PowerShell modules like the PSWindowsUpdate and to have clear separation between a tldr page for PowerShell Modules and Cmdlets (treated as "commands" as in here). But unlike Unix-based command-line utilities (like git) that prefers prefixes or subcommands (like git blame and git pull), PowerShell modules prefers to name Cmdlets with common suffixes (like Get-DataSet, Write-DataSet, Delete-DataSet).

So my question here is how to decide:

1. Normalize PowerShell notices for pages documenting a specific Module?
   • When the module name is long, should we refer to the shortened/common instead of long ones (like DataModule instead of Com.Example.DataModule)? How about alias pages?
2. Normalize PowerShell notices for pages documenting a specific Cmdlet or Function?
   • Every Cmdlet and Function is guaranteed to belong to a module, like Invoke-WebRequest belongs to Microsoft.PowerShell.Utility.
3. Document conflicting commands between PowerShell and non-PowerShell modules?
   • Very common example: PowerShell add aliases on top of classic Command Prompt commands (e.g., rmdir becomes an alias of Remove-Item).
   • Possible rare scenario: An optional PowerShell module adding aliases on top of classic Command Prompt commands.
   • Or just move powershell to a separate platform (see Let's document: PowerShell #6621)?
4. How to declare that a given Module has its Cmdlets?
   • Some subcommands such as Get-DataSet have their own usage documentation.

[Managor]

I'm very out of touch with windows, but separating powershell into its own platform does seem like an attractive solution. I want to hear ideas on what the downsides would be.

[ivanbaluta]

I'm very out of touch with windows, but separating powershell into its own platform does seem like an attractive solution. I want to hear ideas on what the downsides would be.

I see client compatibility as the main problem. It looks like a big headache.

[SpikeTheDragon40k]

I'm very out of touch with windows, but separating powershell into its own platform does seem like an attractive solution. I want to hear ideas on what the downsides would be.

I see client compatibility as the main problem. It looks like a big headache.

I also see it turning into a bit of a compatibility nightmare, though maybe that’s just me too being out of practice with Windows.

[Managor]

Right, it would necessitate client spec changes and I have no idea how easy it is to differentiate between powershell and cmd.

[ivanbaluta]

I got curious about how to reliably distinguish powershell from cmd. The most robust method seems to be checking the parent process.
The algorithm:

1. get the current PID.
2. find the parent PID.
3. get the executable name of the parent.

For tlrc:
This doesn't look too difficult to implement (though I'm not very familiar with Rust). It seems we would need to use the sysinfo crate. We can check the parent executable name against:

• cmd: cmd.exe
• PowerShell (Legacy): powershell.exe
• PowerShell Core: pwsh.exe

For the Python client:
It is a bit trickier. We would either need to add psutil as a dependency (which is heavy), or use the ctypes module to call Windows APIs directly, but that would require writing some low-level code.