Add a new conceptual help topic to cover the ETS (Extended Type System) systematically and comprehensively

[mklement0]

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.

• how I can define extended members myself (Update-TypeData in-session vs. *.types.ps1xml files 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-TypeData at 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

[sdwheeler]

@mklement0 I look forward to your PR.

[doctordns]

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]

@doctordns We need to document ETS for both Windows PowerShell and PowerShell core.

I don't think that the doc propose by @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]

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]

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]

a page on the structure of a type.ps1XML

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.

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.

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.ps1xml files 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.ps1xml files allowed you to study them to learn how to create your own.

The right way to address this is to provide an Export-TypeData cmdlet, analogous to the extant Export-FormatData - see @ThomasNieto's feature request at PowerShell/PowerShell#11593

[sdwheeler]

I did add this documentation to the SDK back in July. https://docs.microsoft.com/powershell/scripting/developer/ets/overview

[mklement0]

That's good to know, @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]

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]

@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]

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]

@JosephColvin It is not deprecated. The information in the legacy SDK still applies.

[JosephColvin]

Thank you Sean for letting me know. Joseph Colvin IT Coordinator Warwick Public School<https://www.warwick.k12.nd.us/>

…

________________________________ From: Sean Wheeler ***@***.***> Sent: Wednesday, July 12, 2023 1:23 PM To: MicrosoftDocs/PowerShell-Docs ***@***.***> Cc: Joseph Colvin ***@***.***>; Mention ***@***.***> Subject: Re: [MicrosoftDocs/PowerShell-Docs] Add a new conceptual help topic to cover the ETS (Extended Type System) systematically and comprehensively (#6763) @JosephColvin<https://github.com/JosephColvin> It is not deprecated. The information in the legacy SDK still applies. — Reply to this email directly, view it on GitHub<#6763 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AZVVWZ2PAHMWHTGSGE3Q5KLXP3TQ3ANCNFSM4STXVJTA>. You are receiving this because you were mentioned.Message ID: ***@***.***>