about_Types.ps1xml

简短说明

介绍如何使用 Types.ps1xml 文件扩展 PowerShell 中使用的对象类型。

长说明

扩展类型数据定义 PowerShell 中对象类型的其他属性和方法 (“成员”) 。 有两种将扩展类型数据添加到 PowerShell 会话的技术。

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

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

关于扩展类型数据

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

例如,PowerShell 会将 DateTime 属性添加到所有 System.DateTime 对象,例如 Get-Date cmdlet 返回的对象。

(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 ,然后将文件传递给 cmdlet 以列出文件 Format-List 的所有属性。 由于更改, Age 属性将显示在列表中。

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

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 的成员集,该集由具有 StatusNameDisplayName 属性的默认属性集组成。

<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> 标记用于定义对象的默认显示的属性集。 可以通过标记标记中的 <Name><MemberSet>PsStandardMembers 值来标识默认显示。

例如,以下 XML 使用三个 ReferencedProperties 创建名为 DefaultDisplayPropertySetPropertySet

<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 文件中的类型,请添加 PrependData 参数 Update-TypeDataUpdate-TypeData 仅影响当前会话。 若要更改所有将来的会话,请导出会话,或将 Update-TypeData 命令添加到 PowerShell 配置文件。

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

"hello".get_Length()

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

对 Types.ps1xml 文件进行签名

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

另请参阅