PowerShell path conceptions

[iSazonov]

Prerequisites

• Write a descriptive title.
• Search the existing issues.
• I am reporting the documentation problem for version of PowerShell I am using.

Version

5.1, 7.0, 7.1, 7.2

Link to affected document

https://docs.microsoft.com/en-us/powershell/scripting/developer/prog-guide/designing-your-windows-powershell-provider

Description of the documentation error

1. The page also duplicate https://docs.microsoft.com/en-us/powershell/scripting/developer/provider/windows-powershell-provider-overview text in Defining a Drive-Qualified Path, Defining a Provider-Qualified Path, Defining a Provider-Direct Path, Defining a Provider-Direct Path.
   Perhaps it makes sense to have the descriptions in one place and reference from other places.

2. There is a mistake:

   For example, the registry Windows PowerShell provider can use \server\regkeypath as a provider-direct path.

   This doesn't work. If I understand correctly only FileSystem is single in-box provider which supports the provider-direct path formats. It makes sense to point this explicitly and change the example to reflect the fact.

3. Path concepts are described so superficially that they are more misleading than helpful.

   • There is no mention of globbed and literal paths although many commands use them and they are supported in the provider engine API. I also think it is important to have a separate page describing the rules of globbing and escaping for both globbed and literal paths.

   • There is no mention of absolute and relative paths. Specially for PowerShell drives (there is a difference for Windows and Unix). No description is for drive-qualified/provider-qualified/provider-direct paths too.

   • There is no clarification PowerShell Drive vs Windows drive (C:)
     While FileSystem::c:\windows works, FileSystem::Temp:\windows doesn't. Should this work always? Not clear. From first example c:\windows should be provider internal path but really PowerShell handles it as drive-qualified. If we can say FileSystem provider is special case - what is right behavior for other providers? Should the Registry::HKLM:\Software works? If yes FileSystem::Temp:\windows should works too. See below.

   • Defining PowerShell paths is very confuse (Drive-Qualified, Provider-Qualified, Provider-Direct , Provider-Internal)

     From the language spec doc Registry::HKLM:\Software and FileSystem::Temp:\windowsshould work but really it is not how PowerShell works.
     Since PowerShell drive is unambiguously define PowerShell Provider this path format looks redundant. I assume that the design was and is:
     PowerShell path ::= Drive-Qualified | Provider-Qualified | Provider-Direct
     Consequently, c:\windows from FileSystem::c:\windows had to be provider-internal path but it is not because FileSystem::\\?\c:\windows had to works but not.
     Also it is not clear about \\?\c:\windows and \\.\c:\windows. Formally it is Provider-Direct path. Docs say "To allow remote access to your Windows PowerShell provider". So we should consider the path as remote. Really it is local specific Windows paths and they do not work well (or at all). So the definition of Provider-Direct path must be reworded and PowerShell behavior must be fixed.

     It would be great to see real examples for paths in the docs with an explanation of what is what.

   • What are umbrella terms (type, kind, sort, ...) for (1) absolute/relative path, (2) drive-qualified/provider-qualified/provider-direct paths ("PowerShell path is one from types(?) ...."), (3) escaped/unescaped path.

I hope we could make the documentation more useful for developers.

Suggested fix

No response