about_Types.ps1xml

Artículo
04/13/2023

Descripción breve

Explica cómo usar Types.ps1xml archivos para ampliar los tipos de objetos que se usan en PowerShell.

Descripción larga

Los datos de tipo extendido definen propiedades y métodos adicionales ("miembros") de tipos de objeto en PowerShell. Hay dos técnicas para agregar datos de tipo extendido a una sesión de PowerShell.

Types.ps1xml file: archivo XML que define datos de tipo extendido.
Update-TypeData: un cmdlet que vuelve a cargar Types.ps1xml archivos y define los datos extendidos para los tipos de la sesión actual.

En este tema se describen Types.ps1xml los archivos. Para obtener más información sobre el uso del Update-TypeData cmdlet para agregar datos de tipo extendido dinámico a la sesión actual, consulte Update-TypeData.

Acerca de los datos de tipo extendido

Los datos de tipo extendido definen propiedades y métodos adicionales ("miembros") de tipos de objeto en PowerShell. Puede ampliar cualquier tipo compatible con PowerShell y usar las propiedades y los métodos agregados de la misma manera que se usan las propiedades definidas en los tipos de objeto.

Por ejemplo, PowerShell agrega una propiedad DateTime a todos los System.DateTime objetos, como los que devuelve el Get-Date cmdlet.

(Get-Date).DateTime

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

No encontrará la propiedad DateTime en la descripción de la estructura System.DateTime , ya que PowerShell agrega la propiedad y solo está visible en PowerShell.

PowerShell define internamente un conjunto predeterminado de tipos extendidos. Esta información de tipo se carga en cada sesión de PowerShell al iniciarse. La propiedad DateTime forma parte de este conjunto predeterminado. Antes de PowerShell 6, las definiciones de tipo se almacenaban en el Types.ps1xml archivo en el directorio de instalación de PowerShell ($PSHOME).

Adición de datos de tipo extendido a PowerShell

Hay tres orígenes de datos de tipo extendido en sesiones de PowerShell.

PowerShell define los datos de tipo extendido y se carga automáticamente en cada sesión de PowerShell. A partir de PowerShell 6, esta información se compila en PowerShell y ya no se incluye en un Types.ps1xml archivo.
Los Types.ps1xml archivos que exportan los módulos se cargan cuando el módulo se importa en la sesión actual.
Los datos de tipo extendido que se definen mediante el Update-TypeData cmdlet solo se agregan a la sesión actual. No se guarda en un archivo.

En la sesión, los datos de tipo extendido de los tres orígenes se aplican a los objetos de la misma manera y están disponibles en todos los objetos de los tipos especificados.

Cmdlets TypeData

Los siguientes cmdlets se incluyen en el módulo Microsoft.PowerShell.Utility en PowerShell 3.0 y versiones posteriores.

Get-TypeData: obtiene datos de tipo extendidos en la sesión actual.
Update-TypeData: vuelve a Types.ps1xml cargar los archivos. Agrega datos de tipo extendido a la sesión actual.
Remove-TypeData: quita los datos de tipo extendido de la sesión actual.

Para obtener más información sobre estos cmdlets, consulte el tema de ayuda de cada cmdlet.

Archivos Types.ps1xml integrados

Los Types.ps1xml archivos del $PSHOME directorio se agregan automáticamente a cada sesión.

El Types.ps1xml archivo del directorio de instalación de PowerShell ($PSHOME) es un archivo de texto basado en XML que permite agregar propiedades y métodos a los objetos que se usan en PowerShell. PowerShell tiene archivos integrados Types.ps1xml que agregan varios elementos a los tipos de .NET, pero puede crear archivos adicionales Types.ps1xml para ampliar aún más los tipos.

Por ejemplo, de forma predeterminada, los objetos de matriz (System.Array) tienen una propiedad Length que muestra el número de objetos de la matriz. Sin embargo, dado que el nombre Length no describe claramente la propiedad, PowerShell agrega una propiedad de alias denominada Count que muestra el mismo valor. El siguiente XML agrega la propiedad Count al System.Array tipo .

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

Para obtener el nuevo AliasProperty, use un Get-Member comando en cualquier matriz, como se muestra en el ejemplo siguiente.

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

El comando devuelve los siguientes resultados.

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)
# ...

Como resultado, puede usar la propiedad Count o la propiedad Length de matrices en PowerShell. Por ejemplo:

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

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

Creación de nuevos archivos Types.ps1xml

Los .ps1xml archivos instalados con PowerShell están firmados digitalmente para evitar alteraciones, ya que el formato puede incluir bloques de script. Por lo tanto, para agregar una propiedad o un método a un tipo de .NET, cree sus propios Types.ps1xml archivos y, a continuación, agréguelos a la sesión de PowerShell.

Para crear un nuevo archivo, empiece por copiar un archivo existente Types.ps1xml . El nuevo archivo puede tener cualquier nombre, pero debe tener una .ps1xml extensión de nombre de archivo. Puede colocar el nuevo archivo en cualquier directorio accesible para PowerShell, pero resulta útil colocar los archivos en el directorio de instalación de PowerShell ($PSHOME) o en un subdirectorio del directorio de instalación.

Cuando haya guardado el nuevo archivo, use el Update-TypeData cmdlet para agregar el nuevo archivo a la sesión de PowerShell. Si desea que los tipos tengan prioridad sobre los tipos integrados definidos, use el parámetro PrependData del Update-TypeData cmdlet . Update-TypeData afecta solo a la sesión actual. Para realizar el cambio en todas las sesiones futuras, exporte la consola o agregue el Update-TypeData comando al perfil de PowerShell.

Types.ps1xml y Add-Member

Los Types.ps1xml archivos agregan propiedades y métodos a todas las instancias de los objetos del tipo .NET especificado en la sesión de PowerShell afectada. Sin embargo, si necesita agregar propiedades o métodos solo a una instancia de un objeto, use el Add-Member cmdlet .

Para obtener más información, vea Add-Member.

Ejemplo: Agregar un miembro Age a objetos FileInfo

En este ejemplo se muestra cómo agregar una propiedad Age a objetos System.IO.FileInfo . La antigüedad de un archivo es la diferencia entre su hora de creación y la hora actual en días.

Dado que la propiedad Age se calcula mediante un bloque de script, busque una <ScriptProperty> etiqueta que se usará como modelo para la nueva propiedad Age .

Guarde el código XML siguiente en el archivo $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>

Ejecute Update-TypeData para agregar el nuevo Types.ps1xml archivo a la sesión actual. El comando usa el parámetro PrependData para colocar el nuevo archivo en un orden de precedencia superior a las definiciones originales.

Para obtener más información sobre Update-TypeData, vea Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Para probar el cambio, ejecute un Get-ChildItem comando para obtener el archivo PowerShell.exe en el $PSHOME directorio y, a continuación, canalice el archivo al Format-List cmdlet para enumerar todas las propiedades del archivo. Como resultado del cambio, la propiedad Age aparece en la lista.

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

Xml en archivos Types.ps1xml

La definición de esquema completa se puede encontrar en Types.xsd en el repositorio de código fuente de PowerShell en GitHub.

La <Types> etiqueta incluye todos los tipos definidos en el archivo. Solo debe haber una <Types> etiqueta.

Cada tipo de .NET mencionado en el archivo debe representarse mediante una <Type> etiqueta .

Las etiquetas de tipo deben contener las siguientes etiquetas:

<Name>: incluye el nombre del tipo de .NET afectado.

<Members>: incluye las etiquetas de las nuevas propiedades y métodos definidos para el tipo de .NET.

Cualquiera de las siguientes etiquetas de miembro puede estar dentro de la <Members> etiqueta .

AliasProperty

Define un nuevo nombre para una propiedad existente.

La <AliasProperty> etiqueta debe tener una <Name> etiqueta que especifique el nombre de la nueva propiedad y una <ReferencedMemberName> etiqueta que especifique la propiedad existente.

Por ejemplo, la propiedad Count alias es un alias para la propiedad Length de los objetos de matriz.

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

CodeMethod

Hace referencia a un método estático de una clase .NET.

La <CodeMethod> etiqueta debe tener una <Name> etiqueta que especifique el nombre del nuevo método y una <CodeReference> etiqueta que especifique el código en el que se define el método.

Por ejemplo, el método ToString es el nombre de la definición de código 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

Hace referencia a un método estático de una clase .NET.

La <CodeProperty> etiqueta debe tener una <Name> etiqueta que especifique el nombre de la nueva propiedad y una <GetCodeReference> etiqueta que especifique el código en el que se define la propiedad.

Por ejemplo, la propiedad Mode de los objetos es una propiedad de System.IO.DirectoryInfo código definida en el proveedor FileSystem de PowerShell.

<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

Define una colección de miembros (propiedades y métodos).

Las <MemberSet> etiquetas aparecen dentro de las etiquetas principales <Members> . Las etiquetas deben incluir una <Name> etiqueta que rodea el nombre del conjunto de miembros y una etiqueta secundaria <Members> que rodea a los miembros (propiedades y métodos) del conjunto. Cualquiera de las etiquetas que crean una propiedad (como <NoteProperty> o ) o <ScriptProperty>un método (como <Method> o <ScriptMethod>) pueden ser miembros del conjunto.

En Types.ps1xml los archivos, la <MemberSet> etiqueta se usa para definir las vistas predeterminadas de los objetos .NET en PowerShell. En este caso, el nombre del conjunto de miembros (el valor dentro de las <Name> etiquetas) siempre es PsStandardMembers y los nombres de las propiedades (el valor de la <Name> etiqueta) son uno de los siguientes:

DefaultDisplayProperty: una sola propiedad de un objeto.
DefaultDisplayPropertySet: una o varias propiedades de un objeto.
DefaultKeyPropertySet: una o varias propiedades clave de un objeto. Una propiedad de clave identifica instancias de valores de propiedad, como el número de identificadores de elementos de un historial de sesión.

Por ejemplo, el siguiente XML define la presentación predeterminada de servicios (System.ServiceProcess.ServiceController objetos) devueltos por el Get-Service cmdlet . Define un conjunto de miembros denominado PsStandardMembers que consta de una propiedad predeterminada establecida con las propiedades Status, Name y 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>: hace referencia a un método nativo del objeto subyacente.

<Methods>: colección de los métodos del objeto .

NoteProperty

Define una propiedad con un valor estático.

La <NoteProperty> etiqueta debe tener una <Name> etiqueta que especifique el nombre de la nueva propiedad y una <Value> etiqueta que especifique el valor de la propiedad.

Por ejemplo, el siguiente XML crea una propiedad Status para objetos System.IO.DirectoryInfo . El valor de la propiedad Status siempre es Correcto.

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

PropertySet

Propiedades que toman argumentos y devuelven un valor.

<Properties>: colección de las propiedades del objeto .

<Property>: propiedad del objeto base.

<PropertySet>: define una colección de propiedades del objeto .

La <PropertySet> etiqueta debe tener una <Name> etiqueta que especifique el nombre del conjunto de propiedades y una <ReferencedProperty> etiqueta que especifique las propiedades. Los nombres de las propiedades se incluyen entre <Name> etiquetas.

En Types.ps1xml, <PropertySet> las etiquetas se usan para definir conjuntos de propiedades para la presentación predeterminada de un objeto. Puede identificar las pantallas predeterminadas por el valor PsStandardMembers en la <Name> etiqueta de una <MemberSet> etiqueta.

Por ejemplo, el siguiente XML crea un PropertySet denominado DefaultDisplayPropertySet con tres ReferencedProperties.

<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

Define un método cuyo valor es la salida de un script.

La <ScriptMethod> etiqueta debe tener una <Name> etiqueta que especifique el nombre del nuevo método y una <Script> etiqueta que incluya el bloque de script que devuelve el resultado del método.

Por ejemplo, los ConvertToDateTime métodos y ConvertFromDateTime de los objetos de administración (System.System.Management.ManagementObject) son métodos de script que usan los ToDateTime métodos estáticos y ToDmtfDateTime de la System.Management.ManagementDateTimeConverter clase .

<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

Define una propiedad cuyo valor es la salida de un script.

La <ScriptProperty> etiqueta debe tener una <Name> etiqueta que especifique el nombre de la nueva propiedad y una <GetScriptBlock> etiqueta que incluya el bloque de script que devuelve el valor de propiedad.

Por ejemplo, la propiedad VersionInfo del objeto System.IO.FileInfo es una propiedad de script que resulta de usar la propiedad FullName del método estático GetVersionInfo de objetos System.Diagnostics.FileVersionInfo .

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

Para obtener más información, consulte el Kit de desarrollo de software (SDK) de Windows PowerShell.

Update-TypeData

Para cargar los Types.ps1xml archivos en una sesión de PowerShell, ejecute el Update-TypeData cmdlet . Si desea que los tipos del archivo tengan prioridad sobre los tipos del archivo integrado Types.ps1xml , agregue el parámetro PrependData de Update-TypeData. Update-TypeData afecta solo a la sesión actual. Para realizar el cambio en todas las sesiones futuras, exporte la sesión o agregue el Update-TypeData comando al perfil de PowerShell.

Las excepciones que se producen en las propiedades o desde la adición de propiedades a un Update-TypeData comando, no notifican errores a StdErr. Esto es para suprimir las excepciones que se producirían en muchos tipos comunes durante la aplicación del formato y la generación del resultado. Si obtiene propiedades de .NET, puede solucionar la supresión de excepciones mediante la sintaxis del método en su lugar, como se muestra en el ejemplo siguiente:

"hello".get_Length()

Tenga en cuenta que la sintaxis del método solo se puede usar con propiedades de .NET. Las propiedades agregadas mediante la ejecución del cmdlet no pueden usar la sintaxis del Update-TypeData método.

Firma de un archivo Types.ps1xml

Para proteger a los usuarios del Types.ps1xml archivo, puede firmar el archivo mediante una firma digital. Para obtener más información, consulte about_Signing.