about_Types.ps1xml

项目
05/09/2024

简短说明

说明如何使用 Types.ps1xml 文件来扩展 PowerShell 中使用的对象类型。

长说明

扩展类型数据定义其他属性和方法， (“members”) PowerShell 中的对象类型。可通过两种方法将扩展类型数据添加到 PowerShell 会话。

Types.ps1xml file：定义扩展类型数据的 XML 文件。
Update-TypeData：一个 cmdlet，用于重新加载 Types.ps1xml 文件并为当前会话中的类型定义扩展数据。

本主题介绍 Types.ps1xml 文件。有关使用 Update-TypeData cmdlet 将动态扩展类型数据添加到当前会话的详细信息，请参阅 Update-TypeData。

关于扩展类型数据

扩展类型数据定义其他属性和方法， (“members”) PowerShell 中的对象类型。可以扩展 PowerShell 支持的任何类型，并使用添加的属性和方法的方式与使用对象类型上定义的属性的方式相同。

例如，PowerShell 向所有System.DateTime对象添加 DateTime 属性，例如 cmdlet 返回的属性Get-Date。

(Get-Date).DateTime

Sunday, January 29, 2012 9:43:57 AM

在 System.DateTime 结构的说明中找不到 DateTime 属性，因为 PowerShell 添加了属性，并且它仅在 PowerShell 中可见。

PowerShell 在内部定义一组默认的扩展类型。此类型信息在启动时加载到每个 PowerShell 会话中。 DateTime 属性是此默认集的一部分。在 PowerShell 6 之前，类型定义将文件存储在 Types.ps1xml PowerShell 安装目录中， $PSHOME () 。

将扩展类型数据添加到 PowerShell

PowerShell 会话中有三个扩展类型数据源。

扩展类型数据由 PowerShell 定义，并自动加载到每个 PowerShell 会话中。从 PowerShell 6 开始，此信息将编译到 PowerShell 中，不再包含在文件中 Types.ps1xml 。
模块 Types.ps1xml 导入当前会话时，将加载模块导出的文件。
使用 Update-TypeData cmdlet 定义的扩展类型数据仅添加到当前会话。它不会保存在文件中。

在会话中，来自三个源的扩展类型数据以相同的方式应用于对象，并且可用于指定类型的所有对象。

TypeData cmdlet

以下 cmdlet 包含在 PowerShell 3.0 及更高版本的 Microsoft.PowerShell.Utility 模块中。

Get-TypeData：获取当前会话中的扩展类型数据。
Update-TypeData：重新加载 Types.ps1xml 文件。将扩展类型数据添加到当前会话。
Remove-TypeData：从当前会话中删除扩展类型数据。

有关这些 cmdlet 的详细信息，请参阅每个 cmdlet 的帮助主题。

内置 Types.ps1xml 文件

目录中 Types.ps1xml 的文件 $PSHOME 会自动添加到每个会话。

Types.ps1xml PowerShell 安装目录中 ($PSHOME) 的文件是基于 XML 的文本文件，可用于向 PowerShell 中使用的对象添加属性和方法。 PowerShell 具有内置 Types.ps1xml 文件，可将多个元素添加到 .NET 类型，但你可以创建其他 Types.ps1xml 文件来进一步扩展类型。

例如，默认情况下，数组对象 (System.Array) 具有 一个 Length 属性，该属性列出数组中的对象数。但是，由于名称 Length 未明确描述属性，因此 PowerShell 会添加一个名为 Count 的别名属性，该属性显示相同的值。以下 XML 将 Count 属性添加到类型 System.Array 。

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>
        Length
      </ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

若要获取新的 AliasProperty，请在 Get-Member 任何数组上使用命令，如以下示例所示。

Get-Member -InputObject (1,2,3,4)

该命令返回以下结果。

Name       MemberType    Definition
----       ----------    ----------
Count      AliasProperty Count = Length
Address    Method        System.Object& Address(Int32)
Clone      Method        System.Object Clone()
CopyTo     Method        System.Void CopyTo(Array array, Int32 index):
Equals     Method        System.Boolean Equals(Object obj)
Get        Method        System.Object Get(Int32)
# ...

因此，可以使用 PowerShell 中数组的 Count 属性或 Length 属性。例如：

(1, 2, 3, 4).count
4

(1, 2, 3, 4).length
4

创建新的 Types.ps1xml 文件

.ps1xml使用 PowerShell 安装的文件经过数字签名以防止篡改，因为格式设置可能包含脚本块。因此，若要将属性或方法添加到 .NET 类型，请创建自己的 Types.ps1xml 文件，然后将其添加到 PowerShell 会话。

若要创建新文件，请首先复制现有 Types.ps1xml 文件。新文件可以具有任何名称，但它必须具有 .ps1xml 文件扩展名。可以将新文件放置在 PowerShell 可访问的任何目录中，但将文件放在 PowerShell 安装目录 ($PSHOME) 或安装目录的子目录中非常有用。

保存新文件后，使用 Update-TypeData cmdlet 将新文件添加到 PowerShell 会话。如果希望类型优先于定义的内置类型，请使用 cmdlet 的 Update-TypeDataPrependData 参数。 Update-TypeData 仅影响当前会话。若要对将来的所有会话进行更改，请导出控制台，或将 Update-TypeData 命令添加到 PowerShell 配置文件。

Types.ps1xml 和 Add-Member

这些文件 Types.ps1xml 将属性和方法添加到受影响的 PowerShell 会话中指定 .NET 类型的对象的所有实例。但是，如果只需要向对象的一个实例添加属性或方法，请使用 Add-Member cmdlet。

有关详细信息，请参阅 Add-Member。

示例：将 Age 成员添加到 FileInfo 对象

此示例演示如何将 Age 属性添加到 System.IO.FileInfo 对象。文件的有效期是文件的创建时间与当前时间（以天为单位）之间的差值。

由于 Age 属性是使用脚本块计算的，因此请查找要 <ScriptProperty> 用作新 Age 属性的模型的标记。

将以下 XML 代码保存到文件 $PSHOME\MyTypes.ps1xml。

<?xml version="1.0" encoding="utf-8" ?>
<Types>
  <Type>
    <Name>System.IO.FileInfo</Name>
    <Members>
      <ScriptProperty>
        <Name>Age</Name>
        <GetScriptBlock>
          ((Get-Date) - ($this.CreationTime)).Days
        </GetScriptBlock>
      </ScriptProperty>
    </Members>
  </Type>
</Types>

运行 Update-TypeData 以将新 Types.ps1xml 文件添加到当前会话。该命令使用 PrependData 参数将新文件置于高于原始定义的优先顺序。

有关的详细信息 Update-TypeData，请参阅 Update-TypeData。

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

若要测试更改，请运行 Get-ChildItem 命令以获取目录中的 PowerShell.exe 文件 $PSHOME ，然后通过管道将文件传递给 Format-List cmdlet 以列出文件的所有属性。由于更改， Age 属性将显示在列表中。

Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age

Types.ps1xml 文件中的 XML

可以在 GitHub 上的 PowerShell 源代码存储库中的 Types.xsd 中找到完整的架构定义。

标记 <Types> 包含文件中定义的所有类型。应只有一个 <Types> 标记。

文件中提到的每个 .NET 类型都应由标记 <Type> 表示。

类型标记必须包含以下标记：

<Name>：将受影响的 .NET 类型的名称括起来。

<Members>：包含为 .NET 类型定义的新属性和方法的标记。

以下任何成员标记都可以位于标记内 <Members> 。

AliasProperty

定义现有属性的新名称。

标记 <AliasProperty> 必须具有一个 <Name> 指定新属性名称的标记和一个 <ReferencedMemberName> 指定现有属性的标记。

例如， Count 别名属性是数组对象的 Length 属性的别名。

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>Length</ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

CodeMethod

引用 .NET 类的静态方法。

标记 <CodeMethod> 必须具有一个 <Name> 标记，该标记指定新方法的名称，以及一个 <CodeReference> 指定在其中定义方法的代码的标记。

例如， ToString 方法是 Microsoft.PowerShell.ToStringCodeMethods 代码定义的名称。

  <Type>
    <Name>System.Xml.XmlNode</Name>
    <Members>
      <CodeMethod>
        <Name>ToString</Name>
        <CodeReference>
          <TypeName>Microsoft.PowerShell.ToStringCodeMethods</TypeName>
          <MethodName>XmlNode</MethodName>
        </CodeReference>
      </CodeMethod>
    </Members>
  </Type>

CodeProperty

引用 .NET 类的静态方法。

标记 <CodeProperty> 必须具有一个 <Name> 标记，该标记指定新属性的名称，以及一个 <GetCodeReference> 指定在其中定义属性的代码的标记。

例如，对象的 Mode 属性 System.IO.DirectoryInfo 是在 PowerShell FileSystem 提供程序中定义的代码属性。

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <CodeProperty>
      <Name>Mode</Name>
      <GetCodeReference>
        <TypeName>
          Microsoft.PowerShell.Commands.FileSystemProvider
        </TypeName>
        <MethodName>Mode</MethodName>
      </GetCodeReference>
    </CodeProperty>
  </Members>
</Type>

MemberSet

定义成员集合 (属性和方法) 。

标记 <MemberSet> 显示在主 <Members> 标记中。标记必须围绕成员集的名称括起一个 <Name> 标记，以及一个将成员括起来的辅助 <Members> 标记， () 集中的属性和方法。创建属性 (（如 <NoteProperty> 或 <ScriptProperty>) ）或方法 (（如 <Method> 或 <ScriptMethod>) ）的任何标记都可以是该集的成员。

在 Types.ps1xml 文件中， <MemberSet> 标记用于在 PowerShell 中定义 .NET 对象的默认视图。在这种情况下，成员集 (标记) 中的值 <Name> 的名称始终为 PsStandardMembers， (标记) 值 <Name> 的属性的名称为下列值之一：

DefaultDisplayProperty：对象的单个属性。
DefaultDisplayPropertySet：对象的一个或多个属性。
DefaultKeyPropertySet：对象的一个或多个键属性。键属性标识属性值的实例，例如会话历史记录中项的 ID 号。

例如，以下 XML 定义 cmdlet 返回Get-Service的服务 (System.ServiceProcess.ServiceController 对象) 的默认显示。它定义名为 PsStandardMembers 的成员集，该成员集由具有 Status、 Name 和 DisplayName 属性的默认属性集组成。

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

<Method>：引用基础对象的本机方法。

<Methods>：对象的方法的集合。

NoteProperty

定义具有静态值的属性。

标记 <NoteProperty> 必须具有一个 <Name> 指定新属性名称的标记和一个 <Value> 指定属性值的标记。

例如，以下 XML 为 System.IO.DirectoryInfo 对象创建 Status 属性。 Status 属性的值始终为 Success。

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <NoteProperty>
      <Name>Status</Name>
      <Value>Success</Value>
    </NoteProperty>
  </Members>
</Type>

PropertySet

采用参数并返回值的属性。

<Properties>：对象的属性的集合。

<Property>：基对象的属性。

<PropertySet>：定义对象的属性集合。

标记 <PropertySet> 必须具有一个 <Name> 指定属性集名称的标记和一个 <ReferencedProperty> 指定属性的标记。属性的名称包含在标记中 <Name> 。

在 Types.ps1xml中， <PropertySet> 标记用于定义对象的默认显示的属性集。可以通过标记的标记<MemberSet>中的<Name>值 PsStandardMembers 来标识默认显示。

例如，以下 XML 使用三个 ReferencedProperties 创建名为 DefaultDisplayPropertySet 的 PropertySet。

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

ScriptMethod

定义一个方法，其值为脚本的输出。

标记 <ScriptMethod> 必须具有指定 <Name> 新方法名称的标记，以及 <Script> 包含返回方法结果的脚本块的标记。

例如， ConvertToDateTime 管理对象的和 ConvertFromDateTime 方法 (System.System.Management.ManagementObject) 是使用 ToDateTime 类的和 ToDmtfDateTime 静态方法的 System.Management.ManagementDateTimeConverter 脚本方法。

<Type>
 <Name>System.Management.ManagementObject</Name>
 <Members>
 <ScriptMethod>
   <Name>ConvertToDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDateTime($args[0])
   </Script>
 </ScriptMethod>
 <ScriptMethod>
   <Name>ConvertFromDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($args[0])
   </Script>
 </ScriptMethod>
 </Members>
</Type>

ScriptProperty

定义一个属性，其值为脚本的输出。

标记 <ScriptProperty> 必须具有指定 <Name> 新属性名称的标记，以及 <GetScriptBlock> 包含返回属性值的脚本块的标记。

例如，System.IO.FileInfo 对象的 VersionInfo 属性是通过使用 System.Diagnostics.FileVersionInfo 对象的 GetVersionInfo 静态方法的 FullName 属性产生的脚本属性。

<Type>
  <Name>System.IO.FileInfo</Name>
  <Members>
    <ScriptProperty>
      <Name>VersionInfo</Name>
      <GetScriptBlock>
      [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName)
      </GetScriptBlock>
    </ScriptProperty>
  </Members>
</Type>

有关详细信息，请参阅 Windows PowerShell 软件开发工具包 (SDK) 。

Update-TypeData

若要将文件加载 Types.ps1xml 到 PowerShell 会话中，请 Update-TypeData 运行 cmdlet。如果希望文件中的类型优先于内置Types.ps1xml文件中的类型，请添加的 Update-TypeDataPrependData 参数。 Update-TypeData 仅影响当前会话。若要对将来的所有会话进行更改，请导出会话，或将 Update-TypeData 命令添加到 PowerShell 配置文件。

属性中发生的异常，或者向命令添加属性 Update-TypeData 时发生的异常不会向 StdErr报告错误。这是为了取消显示在格式设置和输出期间在许多常见类型中发生的异常。如果获取 .NET 属性，则可以改用方法语法来解决异常的抑制，如以下示例所示：

"hello".get_Length()

请注意，方法语法只能与 .NET 属性一起使用。通过运行 Update-TypeData cmdlet 添加的属性无法使用方法语法。

对 Types.ps1xml 文件进行签名

若要保护文件的用户 Types.ps1xml ，可以使用数字签名对文件进行签名。有关详细信息，请参阅 about_Signing。

通过