Publish to live

reference/docs-conceptual/developer/ets/errors-exceptions.md

@@ -0,0 +1,60 @@
+---
+title: Errors and exceptions in the Extended Type System
+ms.date: 07/09/2020
+ms.topic: conceptual
+---
+# Errors and exceptions in the Extended Type System
+
+Errors can occur in ETS during the initialization of type data and when accessing a member of an
+**PSObject** object or using one of the utility classes such as **LanguagePrimitives**.
+
+## Runtime errors
+
+With one exception, when casting, all exceptions thrown from ETS during runtime are either an
+**ExtendedTypeSystemException** exception or an exception derived from the
+**ExtendedTypeSystemException** class. This allows script developers to trap these exceptions using
+the `Trap` statement in their script.
+
+## Errors getting member values
+
+All errors that occur when getting the value of an ETS member (property, method, or parameterized
+property) cause a **GetValueException** or **GetValueInvocationException** exception to be thrown.
+When ETS recognizes that an error occurred a **GetValueException** exception is thrown. When the
+underlying getter of a referenced member recognizes that an error occurred, a
+**GetValueInvocationException** exception is thrown that may or may not include the inner exception
+that caused the get invocation error.
+
+## Errors setting member values
+
+All errors that occur when setting the value of an ETS property cause a **SetValueException** or
+**SetValueInvocationException** exception to be thrown. When ETS recognizes that an error occurred a
+**SetValueException** exception is thrown. When the underlying setter of a referenced property
+recognizes that an error occurred, a **SetValueInvocationException** exception is thrown that may or
+may not include the inner exception that caused the set invocation error.
+
+## Errors invoking a method
+
+All errors that occur when invoking an ETS method cause a **MethodException** or
+**MethodInvocationException** exception to be thrown. When ETS recognizes that an error occurred a
+**MethodException** exception is thrown. When the referenced method recognizes that an error
+occurred, a **MethodInvocationException** exception is thrown that may or may not include the inner
+exception that caused the invocation error.
+
+## Casting errors
+
+When an invalid cast is attempted, an **PSInvalidCastException** is thrown. Because this exception
+derives from **System.InvalidCastException**, it is not able to be directly trapped from script. Be
+aware that the entity attempting the cast would need to wrap **PSInvalidCastException** in an
+**PSRuntimeException** for this to be trappable by scripts. If an attempt is made to set the value
+of an **PSPropertySet**, **PSMemberSet**, **PSMethodInfo**, or a member of the
+**ReadOnlyPSMemberInfoCollection`1**, a **NotSupportedException** is thrown.
+
+## Common runtime errors
+
+Any other common runtime errors that occur are of type **ExtendedTypeSystemException** exception
+with no additional specific exception types.
+
+## Initialization errors
+
+Errors may occur when initializing `types.ps1xml`. Typically, these errors are displayed when the
+PowerShell runtime starts. However, they can also be displayed when a module is loaded.

reference/docs-conceptual/developer/ets/members.md

@@ -0,0 +1,43 @@
+---
+title: Extended Type System class members
+ms.date: 07/09/2020
+ms.topic: conceptual
+---
+# Extended Type System class members
+
+ETS refers to a number of different kinds of members whose types are defined by the
+**PSMemberTypes** enumeration. These member types include properties, methods, members, and member
+sets that are each defined by their own CLR type. For example, a **NoteProperty** is defined by its
+own **PSNoteProperty** type. These individual CLR types have both their own unique properties and
+common properties that are inherited from the
+[PSMemberInfo class](/dotnet/api/system.management.automation.psmemberinfo).
+
+## The PSMemberInfo class
+
+The **PSMemberInfo** class serves as a base class for all ETS member types. This class provides the
+following base properties to all member CLR types.
+
+- **Name** property: The name of the member. This name can be defined by the base-object or defined
+  by PowerShell when adapted members or extended members are exposed.
+- **Value** property: The value returned from the particular member. Each member type defines how it
+  handles its member value.
+- **TypeNameOfValue** property: This is the name of the CLR type of the value that is returned by
+  the Value property.
+
+## Accessing members
+
+Collections of members can be accessed through the **Members**, **Methods**, and **Properties**
+properties of the **PSObject** object.
+
+## ETS properties
+
+ETS properties are members that can be treated as a property. Essentially, they can appear on the
+left-hand side of an expression. They include alias properties, code properties, PowerShell
+properties, note properties, and script properties. For more information about these types of
+properties, see [ETS properties](properties.md).
+
+## ETS methods
+
+ETS methods are members that can take arguments, may return results, and cannot appear on the
+left-hand side of an expression. They include code methods, PowerShell methods, and script methods.
+For more information about these types of methods, see [ETS methods](methods.md).

reference/docs-conceptual/developer/ets/membersets.md

@@ -0,0 +1,55 @@
+---
+title: Extended Type System member sets
+ms.date: 07/09/2020
+ms.topic: conceptual
+---
+# ETS member sets
+
+Member sets allow you to partition the members of the **PSObject** object into two subsets so that
+the members of the subsets can be referenced together by their subset name. The two types of subsets
+include property sets and member sets. For example of how PowerShell uses member sets, there is a
+specific property set named **DefaultDisplayPropertySet** that is used to determine, at runtime,
+which properties to display for a given **PSObject** object.
+
+## Property Sets
+
+Property sets can include any number of properties of an **PSObject** type. In general, a property
+set can be used whenever a collection of properties (of the same type) is needed. The property set
+is created by calling the
+`PSPropertySet(System.String,System.Collections.Generic.IEnumerable{System.String})` constructor
+with the name of the property set and the names of the referenced properties. The created
+**PSPropertySet** object can then be used as an alias that points to the properties in the set. The
+[PSPropertySet](/dotnet/api/system.management.automation.pspropertyset) class has the following
+properties and methods.
+
+- **IsInstance** property: Gets a **Boolean** value that indicates the source of the property.
+- **MemberType** property: Gets the type of properties in the property set.
+- **Name** property: Gets the name of the property set.
+- **ReferencedPropertyNames** property: Gets the names of the properties in the property set.
+- **TypeNameOfValue** property: Gets a **PropertySet** enumeration constant that defines this set as
+  a property set.
+- **Value** property: Gets or sets the **PSPropertySet** object.
+- `PSPropertySet.Copy` method: Makes an exact copy of the **PSPropertySet** object.
+- `PSMemberSet.ToString` method: Converts the **PSPropertySet** object to a string.
+
+## Member Sets
+
+Member sets can include any number of extended members of any type. The member set is created by
+calling the
+`PSMemberSet(System.String,System.Collections.Generic.IEnumerable{System.Management.Automation.PSMemberInfo})`
+constructor with the name of the member set and the names of the referenced members. The created
+**PSPropertySet** object can then be used as an alias that points to the members in the set. The
+[PSMemberSet](/dotnet/api/system.management.automation.psmemberset) class has the following
+properties and methods.
+
+- **IsInstance** property: Gets a **Boolean** value that indicates the source of the member.
+- **Members** property: Gets all the members of the member set.
+- **MemberType** property: Gets a **MemberSet** enumeration constant that defines this set as a
+  member set.
+- **Methods** property: Gets the methods included in the member set.
+- **Properties** property: Gets the properties included in the member set.
+- **TypeNameOfValue** property: Gets a **MemberSet** enumeration constant that defines this set as a
+  member set.
+- **Value** property: Gets the **PSMemberSet** object.
+- `PSMemberSet.Copy` method: Makes an exact copy of the **PSMemberSet** object.
+- `PSMemberSet.ToString` method: Converts the **PSMemberSet** object to a string.

reference/docs-conceptual/developer/ets/methods.md

@@ -0,0 +1,81 @@
+---
+title: Extended Type System class methods
+ms.date: 07/09/2020
+ms.topic: conceptual
+---
+# ETS class methods
+
+ETS methods are members that can take arguments, may return results, and cannot appear on the
+left-hand side of an expression. The methods that are available within ETS include code, Windows
+PowerShell, and script methods.
+
+> [!NOTE]
+> From scripts, methods are accessed using the same syntax as other members with the addition of
+> parenthesis at the end of the method name.
+
+## Code Methods
+
+A code method is an extended member that is defined in a CLR language. It provides similar
+functionality to a method defined on a base object; however, a code method may be added dynamically
+to an **PSObject** object. In order for a code method to become available, a developer must write
+the property in some CLR language, compile, and ship the resultant assembly. This assembly must be
+available in the runspace where the code method is desired. Be aware that a code method
+implementation must be thread safe. Access to these methods is done through
+[PSCodeMethod](/dotnet/api/system.management.automation.pscodemethod) objects that provides the
+following public methods and properties.
+
+- `PSCodeMethod.Copy` method: Makes an exact copy of the **PSCodeMethod** object.
+- `PSCodeMethod.Invoke(System.Object[])` method: Invokes the underlying code method.
+- `PSCodeMethod.ToString` method: Converts the **PSCodeMethod** object to a string.
+- `PSCodeMethod.CodeReference` property: Gets the underlying method that the code method is based
+  on.
+- **PSMemberInfo.IsInstance** property: Gets a **Boolean** value that indicates the source of the
+  member.
+- **PSCodeMethod.MemberType** property: Gets an **PSMemberTypes.CodeMethod** enumeration constant
+  that identifies this method as a code method.
+- **PSMemberInfo.Name** property: Gets the name of the underlying code method.
+- **PSCodeMethod.OverloadDefinitions** property: Gets a definition of all the overloads of the
+  underlying code method.
+- **PSCodeMethod.TypeNameOfValue** property: Gets the full name of the code method.
+- **PSMemberInfo.Value** property: Gets the **PSCodeMethod** object.
+
+## Windows PowerShell Methods
+
+A PowerShell method is a CLR method defined on the base object or is made accessible through an
+adapter. Access to these methods is done through **PSMethod** objects that provides the following
+public methods and properties.
+
+- `PSMethod.Copy` method: Makes an exact copy of the **PSMethod** object.
+- `PSMethod.Invoke(System.Object[])` method: Invokes the underlying method.
+- `PSMethod.ToString` method: Converts the **PSMethod** object to a string.
+- **PSMemberInfo.IsInstance** property: Gets a **Boolean** value that indicates the source of the
+  member.
+- **PSMethod.MemberType** property: Gets an **PSMemberTypes.Method** enumeration constant that
+  identifies this method as a PowerShell method.
+- **PSMemberInfo.Name** property: Gets the name of the underlying method.
+- **PSMethod.OverloadDefinitions** property: Gets the definitions of all the overloads of the
+  underlying method.
+- **PSMethod.TypeNameOfValue** property: Gets the ETS type of this method.
+- **PSMemberInfo.Value** property: Gets the **PSMethod** object.
+
+## Script Methods
+
+A script method is an extended member that is defined in the PowerShell language. It provides
+similar functionality to a method defined on a base object; however, a script method may be added
+dynamically to an **PSObject** object. Access to these methods is done through
+[PSScriptMethod](/dotnet/api/system.management.automation.psscriptmethod) objects that provides the
+following public methods and properties.
+
+- `PSScriptMethod.Copy` method: Makes an exact copy of the **PSScriptMethod** object.
+- `PSScriptMethod.Invoke(System.Object[])` method: Invokes the underlying script method.
+- `PSScriptMethod.ToString` method: Converts the **PSScriptMethod** object to a string.
+- **PSMemberInfo.IsInstance** property: Gets a **Boolean** value that indicates the source of the
+  member.
+- **PSScriptMethod.MemberType** property: Gets a **PSMemberTypes.ScriptMethod** enumeration constant
+  that identifies this method as a script method.
+- **PSMemberInfo.Name** property: Gets the name of the underlying code method.
+- **PSScriptMethod.OverloadDefinitions** property: Gets the definitions of all the overloads of the
+  underlying script method.
+- **PSScriptMethod.TypeNameOfValue** property: Gets the ETS type of this method.
+- **PSScriptMethod.Script** property: Gets the script used to invoke the method.
+- **PSMemberInfo.Value** property: Gets the **PSScriptMethod** object.