Repository navigation
Add a new conceptual help topic to cover the ETS (Extended Type System) systematically and comprehensively #6763
Description
Summary of the new document or enhancement
As a user, I want to know:
-
how PowerShell itself decorates .NET types with additional properties (members), both at the type level (as PowerShell does with the built-in type data) and at the instance level (as PowerShell's provider cmdlets do, e.g.
Get-Content).- In addition to adding arbitrary new members, so-called extended members - the engine itself also provides so-called adapted members at the type level, for select types (e.g.,
[xml], WMI/CMI classes, COM classes, and dictionaries (hashtables)). Adapted members surface entities from different object frameworks as if they were regular .NET type members, for simplicity and unified access. (A simple example is the ability to treat the entries of a dictionary as if they were properties; e.g.,@{ foo = 1 }.foo, as an alternative to@{ foo = 1 }['foo'].)
Note that it looks like the AD (Active Directory) provider, as an external module, uses the same technique, but I'm unclear on whether there are public APIs that would allow user code in general to do the same.
- In addition to adding arbitrary new members, so-called extended members - the engine itself also provides so-called adapted members at the type level, for select types (e.g.,
-
how I can define extended members myself (
Update-TypeDatain-session vs.*.types.ps1xmlfiles as part of modules, at the type level;Add-Member/.psobject.Properties.Add()at the instance level) -
that creating
[pscustomobject]instances is also an application of the ETS, namely the construction of an object solely composed of ETS instance members, without any underlying .NET object. -
how I can dynamically add arbitrary ETS type names to objects (instances), for various reasons: to add members to it, to reflect the original type after deserialization (as done by PowerShell itself), to associate an object with formatting data (e.g.,
@{ Name = 'NotReallyAType'; IsPublic=$false; PSTypeName = 'System.RunTimeType' }or
($o = [pscustomobject] @{ foo = 'bar' }).pstypenames.Insert(0, 'CustomType')) -
what type of ETS members I can define and how I can detect ETS members (
Get-TypeDataat the type level,Get-Member -Type AliasProperty, CodeProperty, NoteProperty, ScriptProperty, ScriptMethod, CodeMethod(others?) at both the type and the instance level) -
how precedence is resolved between ETS members and .NET native members of the same name (ETS instance members shadow ETS type members, which in turn shadow native members).
-
that ETS members are PowerShell-specific and aren't visible to .NET methods (but instance members are preserved when they pass through .NET APIs)
about_Types.ps1xml partially covers this, but is primarily focused on creating persistent ETS additions via *.types.ps1xml files.
Details of requested document:
- Proposed title:
about_Types_Extended - Propose location in the TOC:
- Target audience: users
- Purpose or scenario:
or
Proposed changes/additions to existing article: - List of related articles to link to:
about_Types.ps1xml
Activity
sdwheeler commentedon Oct 16, 2020
Michael Klement (@mklement0) I look forward to your PR.
doctordns commentedon Oct 19, 2020
Oddly enough, I am working on some .NET and ETS related content for a book I am working on I have long wanted to have better documentation on PowerShell's ETS feature. I regard it as one of the great hidden success stories - making objects who were designed by people who worked in different buildings and didn't communicate look totally consistent was a boon to IT Pros. It was, in my view, one way the team delivered on the Sacred Vow. Sadly, the AD team just wasn't on the bus so we have the Name property on the ADComputer object, with no ComputerName alias - but I digress.
Since the decision to move the ps1XML files inside the code, this great feature is somewhat less visible than before. So I strongly concur with the need to add documentation. I am happy to assist with the creation.
Documenting the ETS would probably need multiple pages: An intro page, details on the *-TypeData cmdlets, a page on the structure of a type.ps1XML file and maybe a How-To page showing how you can do it. Perhaps, as a first step, we could agree on the set of docs that are needed and their broad scope.
Would this be a PowerShell 7.x and upwards set of docs, or should the set be extended to Windows PowerShell? If the coverage is for both, the Windows PowerShell docs might need to be a little different as the type.ps1xml files still exist there.
sdwheeler commentedon Oct 19, 2020
Thomas Lee (@doctordns) We need to document ETS for both Windows PowerShell and PowerShell core.
I don't think that the doc propose by Michael Klement (@mklement0) really fits as an about_ topic. There is too much to cover for that format. I see this going in the Deep Dive section of the docs.
I agree that we would need to break this up over several articles. We need a good introduction of concepts., definitely need how-to articles, and we need to update or improve the existing cmdlet docs. There is also some coverage in the SDK docs that needs to be rewritten and expanded.
doctordns commentedon Oct 19, 2020
I think an about_Extensible_Type_System would be useful. A single page that sets out what the ETS is, the cmdlets you can use to play, and a few examples. Then, as you suggest, add the other content into a deep dive section. WIth maybe a how-to do something useful in a How-To Section (Hot to add a ComputerName alias to ADComputerObject?).
mklement0 commentedon Oct 19, 2020
Precisely: This is not an either-or situation: if we cant' fit everything into a single about_* topic, we can link to other, more detailed topics.
But it is of prime importance to have an about_* topic at least as a high-level entry point that provides a systematic overview, with links to additional topics, as needed.
mklement0 commentedon Oct 19, 2020
about_Types.ps1xml covers this, though I haven't looked at how comprehensively it does it.
Some of what is in there currently could be moved into the new about_* topic.
That they are no longer used by PowerShell itself is an implementation detail that is already mentioned in about_Types.ps1xml, and I think that's sufficient.
As an aside:
Given that authoring one's own
*.types.ps1xmlfiles still matters in PowerShell Core, primarily for inclusion in modules, this implementation change had an indirect effect, however:In Windows PowerShell, the availability of the in-box
*.types.ps1xmlfiles allowed you to study them to learn how to create your own.The right way to address this is to provide an
Export-TypeDatacmdlet, analogous to the extantExport-FormatData- see Thomas Nieto (@ThomasNieto)'s feature request at PowerShell/PowerShell#11593sdwheeler commentedon Oct 19, 2020
I did add this documentation to the SDK back in July. https://docs.microsoft.com/powershell/scripting/developer/ets/overview
mklement0 commentedon Oct 20, 2020
That's good to know, Sean Wheeler (@sdwheeler), but that article is both very technical and abstract.
It is focused on PSObject, which is mostly hidden (abstracted away) from PowerShell users and script authors, which is generally a good thing (except when the abstraction leaks; see PowerShell/PowerShell#5579).
By contrast, the bullet points in the OP above are focused on practical use of the ETS from a PowerShell user / scripter perspective.
mklement0 commentedon Oct 20, 2020
Also, your article appears underneath the "Legacy PowerShell SDK" node in the documentation hierarchy, and none of the regular help topics seem to link to it (neither about_Types.ps1xml nor Update-TypeData, ...), nor vice versa.
sdwheeler commentedon Oct 20, 2020
Michael Klement (@mklement0) I don't disagree. We need the content described in the OP. I am just pointing out content that you may not have been aware of. It was in the original SDK years ago but was lost. I found it and got it restored. It can be supporting information for the proposed articles.
JosephColvin commentedon Jul 12, 2023
Can someone clarify if ETS needs to be deprecated or has been dropped as the information I keep finding is from older versions of PowerShell or is under the legacy section?
sdwheeler commentedon Jul 12, 2023
JosephColvin It is not deprecated. The information in the legacy SDK still applies.
JosephColvin commentedon Jul 12, 2023