Sobre Types.ps1xml

Artigo
06/21/2023

Descrição breve

Explica como usar Types.ps1xml arquivos para estender os tipos de objetos usados no PowerShell.

Descrição longa

Dados de tipo estendido definem propriedades e métodos adicionais ("membros") de tipos de objeto no PowerShell. Há duas técnicas para adicionar dados de tipo estendido a uma sessão do PowerShell.

Types.ps1xml arquivo: um arquivo XML que define dados de tipo estendido.
Update-TypeData: um cmdlet que recarrega Types.ps1xml arquivos e define dados estendidos para tipos na sessão atual.

Este tópico descreve arquivos Types.ps1xml . Para obter mais informações sobre como usar o Update-TypeData cmdlet para adicionar dados de tipo estendido dinâmicos à sessão atual, consulte Update-TypeData.

Sobre dados de tipo estendido

Dados de tipo estendido definem propriedades e métodos adicionais ("membros") de tipos de objeto no PowerShell. Você pode estender qualquer tipo compatível com o PowerShell e usar as propriedades e métodos adicionados da mesma forma que você usa as propriedades definidas nos tipos de objeto.

Por exemplo, o PowerShell adiciona uma propriedade DateTime a todos os System.DateTime objetos, como os que o Get-Date cmdlet retorna.

(Get-Date).DateTime

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

Você não encontrará a propriedade DateTime na descrição da estrutura System.DateTime , pois o PowerShell adiciona a propriedade e ela fica visível apenas no PowerShell.

O PowerShell define internamente um conjunto padrão de tipos estendidos. Essas informações de tipo são carregadas em todas as sessões do PowerShell na inicialização. A propriedade DateTime faz parte desse conjunto padrão. Antes do PowerShell 6, as definições de tipo eram armazenadas no Types.ps1xml arquivo no diretório de instalação do PowerShell ($PSHOME).

Adicionando dados de tipo estendido ao PowerShell

Há três fontes de dados de tipo estendido nas sessões do PowerShell.

O definido pelo PowerShell e é carregado automaticamente em todas as sessões do PowerShell. A partir do PowerShell 6, essas informações são compiladas no PowerShell e não são mais enviadas em um Types.ps1xml arquivo.
Os Types.ps1xml arquivos que os módulos exportam são carregados quando o módulo é importado para a sessão atual.
Dados de tipo estendido definidos usando o Update-TypeData cmdlet são adicionados somente à sessão atual. Ele não é salvo em um arquivo.

Na sessão, os dados de tipo estendido das três fontes são aplicados a objetos da mesma maneira e estão disponíveis em todos os objetos dos tipos especificados.

Os cmdlets TypeData

Os cmdlets a seguir são incluídos no módulo Microsoft.PowerShell.Utility no PowerShell 3.0 e posterior.

Get-TypeData: obtém dados de tipo estendidos na sessão atual.
Update-TypeData: recarrega Types.ps1xml arquivos. Adiciona dados de tipo estendidos à sessão atual.
Remove-TypeData: remove dados de tipo estendidos da sessão atual.

Para obter mais informações sobre esses cmdlets, consulte o tópico de ajuda para cada cmdlet.

Arquivos Types.ps1xml internos

Os Types.ps1xml arquivos no $PSHOME diretório são adicionados automaticamente a cada sessão.

O Types.ps1xml arquivo no diretório de instalação do PowerShell ($PSHOME) é um arquivo de texto baseado em XML que permite adicionar propriedades e métodos aos objetos usados no PowerShell. O PowerShell tem arquivos internos Types.ps1xml que adicionam vários elementos aos tipos .NET, mas você pode criar arquivos adicionais Types.ps1xml para estender ainda mais os tipos.

Por exemplo, por padrão, objetos de matriz (System.Array) têm uma propriedade Length que lista o número de objetos na matriz. No entanto, como o comprimento do nome não descreve claramente a propriedade, o PowerShell adiciona uma propriedade de alias chamada Count que exibe o mesmo valor. O XML a seguir adiciona a propriedade Count ao System.Array tipo.

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

Para obter o novo AliasProperty, use um Get-Member comando em qualquer matriz, conforme mostrado no exemplo a seguir.

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

O comando retorna os seguintes 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, você pode usar a propriedade Count ou a propriedade Length de matrizes no PowerShell. Por exemplo:

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

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

Criando novos arquivos Types.ps1xml

Os .ps1xml arquivos instalados com o PowerShell são assinados digitalmente para evitar a adulteração porque a formatação pode incluir blocos de script. Portanto, para adicionar uma propriedade ou método a um tipo .NET, crie seus próprios Types.ps1xml arquivos e adicione-os à sessão do PowerShell.

Para criar um novo arquivo, comece copiando um arquivo existente Types.ps1xml . O novo arquivo pode ter qualquer nome, mas deve ter uma .ps1xml extensão de nome de arquivo. Você pode colocar o novo arquivo em qualquer diretório acessível ao PowerShell, mas é útil colocar os arquivos no diretório de instalação do PowerShell ($PSHOME) ou em um subdiretório do diretório de instalação.

Quando você tiver salvo o novo arquivo, use o Update-TypeData cmdlet para adicionar o novo arquivo à sessão do PowerShell. Se você quiser que seus tipos têm precedência sobre os tipos internos definidos, use o parâmetro PrependData do Update-TypeData cmdlet. Update-TypeData afeta apenas a sessão atual. Para fazer a alteração em todas as sessões futuras, exporte o console ou adicione o Update-TypeData comando ao seu perfil do PowerShell.

Types.ps1xml e Add-Member

Os Types.ps1xml arquivos adicionam propriedades e métodos a todas as instâncias dos objetos do tipo .NET especificado na sessão do PowerShell afetada. No entanto, se você precisar adicionar propriedades ou métodos apenas a uma instância de um objeto, use o Add-Member cmdlet.

Para obter mais informações, consulte Add-Member.

Exemplo: adicionando um membro Age a objetos FileInfo

Este exemplo mostra como adicionar uma propriedade Age aos objetos System.IO.FileInfo . A idade de um arquivo é a diferença entre o tempo de criação e a hora atual em dias.

Como a propriedade Age é calculada usando um bloco de script, localize uma <ScriptProperty> marca para usar como modelo para a nova propriedade Age .

Salve o código XML a seguir no arquivo $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>

Execute Update-TypeData para adicionar o novo Types.ps1xml arquivo à sessão atual. O comando usa o parâmetro PrependData para colocar o novo arquivo em uma ordem de precedência maior que as definições originais.

Para obter mais informações sobre Update-TypeData, consulte Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Para testar a alteração, execute um Get-ChildItem comando para obter o arquivo PowerShell.exe no diretório e, em $PSHOME seguida, redirecione o arquivo para o Format-List cmdlet para listar todas as propriedades do arquivo. Como resultado da alteração, a propriedade Age aparece na lista.

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

O XML em arquivos Types.ps1xml

A definição completa do esquema pode ser encontrada em Types.xsd no repositório de código-fonte do PowerShell no GitHub.

A <Types> marca inclui todos os tipos definidos no arquivo. Deve haver apenas uma <Types> marca.

Cada tipo .NET mencionado no arquivo deve ser representado por uma <Type> marca.

As marcas de tipo devem conter as seguintes marcas:

<Name>: inclui o nome do tipo .NET afetado.

<Members>: coloca as marcas para as novas propriedades e métodos definidos para o tipo .NET.

Qualquer uma das marcas de membro a seguir pode estar dentro da <Members> marca.

<AliasProperty>: define um novo nome para uma propriedade existente.

A <AliasProperty> marca deve ter uma <Name> marca que especifica o nome da nova propriedade e uma <ReferencedMemberName> marca que especifica a propriedade existente.

Por exemplo, a propriedade de alias Count é um alias para a propriedade Length de objetos de matriz.

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

<CodeMethod>: faz referência a um método estático de uma classe .NET.

A <CodeMethod> marca deve ter uma <Name> marca que especifica o nome do novo método e uma <GetCodeReference> marca que especifica o código no qual o método é definido.

Por exemplo, a propriedade Mode de System.IO.DirectoryInfo objetos é uma propriedade de código definida no provedor do 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>

<CodeProperty>: faz referência a um método estático de uma classe .NET.

A <CodeProperty> marca deve ter uma <Name> marca que especifica o nome da nova propriedade e uma <GetCodeReference> marca que especifica o código no qual a propriedade é definida.

Por exemplo, a propriedade Mode de System.IO.DirectoryInfo objetos é uma propriedade de código definida no provedor do 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>: define uma coleção de membros (propriedades e métodos).

As <MemberSet> marcas aparecem dentro das marcas primárias <Members> . As marcas devem incluir uma <Name> marca em torno do nome do conjunto de membros e uma marca secundária <Members> que envolve os membros (propriedades e métodos) no conjunto. Qualquer uma das marcas que criam uma propriedade (como <NoteProperty> ou <ScriptProperty>) ou um método (como <Method> ou <ScriptMethod>) pode ser membro do conjunto.

Nos Types.ps1xml arquivos, a <MemberSet> marca é usada para definir as exibições padrão dos objetos .NET no PowerShell. Nesse caso, o nome do conjunto de membros (o valor dentro das <Name> marcas) é sempre PsStandardMembers, e os nomes das propriedades (o valor da <Name> marca) são um dos seguintes:

DefaultDisplayProperty: uma única propriedade de um objeto.
DefaultDisplayPropertySet: uma ou mais propriedades de um objeto.
DefaultKeyPropertySet: uma ou mais propriedades principais de um objeto. Uma propriedade de chave identifica instâncias de valores de propriedade, como o número de ID de itens em um histórico de sessão.

Por exemplo, o XML a seguir define a exibição padrão de serviços (System.ServiceProcess.ServiceController objetos) que são retornados pelo Get-Service cmdlet. Ele define um conjunto de membros chamado PsStandardMembers que consiste em um conjunto de propriedades padrão com as propriedades Status, Name e 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>: faz referência a um método nativo do objeto subjacente.

<Methods>: uma coleção dos métodos do objeto.

<NoteProperty>: define uma propriedade com um valor estático.

A <NoteProperty> marca deve ter uma <Name> marca que especifique o nome da nova propriedade e uma <Value> marca que especifique o valor da propriedade.

Por exemplo, o XML a seguir cria uma propriedade Status para objetos System.IO.DirectoryInfo . O valor da propriedade Status é sempre êxito.

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

<ParameterizedProperty>: propriedades que pegam argumentos e retornam um valor.

<Properties>: uma coleção das propriedades do objeto.

<Property>: uma propriedade do objeto base.

<PropertySet>: define uma coleção de propriedades do objeto.

A <PropertySet> marca deve ter uma <Name> marca que especifique o nome do conjunto de propriedades e uma <ReferencedProperty> marca que especifique as propriedades. Os nomes das propriedades são colocados entre marcas <Name> .

Em Types.ps1xml, <PropertySet> as marcas são usadas para definir conjuntos de propriedades para a exibição padrão de um objeto. Você pode identificar as exibições padrão pelo valor PsStandardMembers na <Name> marca de uma <MemberSet> marca.

Por exemplo, o XML a seguir cria uma propriedade Status para o System.IO.DirectoryInfo objeto. O valor da propriedade Status é sempre êxito.

<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 um método cujo valor é a saída de um script.

A <ScriptMethod> marca deve ter uma <Name> marca que especifique o nome do novo método e uma <Script> marca que inclua o bloco de script que retorna o resultado do método.

Por exemplo, os métodos e os ConvertToDateTime métodos de objetos de gerenciamento (System.System.Management.ManagementObject) são métodos de script que usam os métodos estáticos e ToDmtfDateTime estáticos ToDateTime da System.Management.ManagementDateTimeConverterConvertFromDateTime classe.

<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 uma propriedade cujo valor é a saída de um script.

A <ScriptProperty> marca deve ter uma <Name> marca que especifique o nome da nova propriedade e uma <GetScriptBlock> marca que inclua o bloco de script que retorna o valor da propriedade.

Por exemplo, a propriedade VersionInfo do objeto System.IO.FileInfo é uma propriedade de script resultante do uso da propriedade FullName do 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 obter mais informações, consulte o SDK (Windows PowerShell Software Development Kit).

Update-TypeData

Para carregar seus Types.ps1xml arquivos em uma sessão do PowerShell, execute o Update-TypeData cmdlet. Se você quiser que os tipos em seu arquivo têm precedência sobre tipos no arquivo interno Types.ps1xml , adicione o parâmetro PrependData de Update-TypeData. Update-TypeData afeta apenas a sessão atual. Para fazer a alteração em todas as sessões futuras, exporte a sessão ou adicione o Update-TypeData comando ao seu perfil do PowerShell.

As exceções que ocorrem nas propriedades ou da adição de propriedades a um Update-TypeData comando não relatam erros para StdErr. Isso é para suprimir exceções que podem ocorrer em muitos tipos comuns durante a formatação e a saída. Se você estiver obtendo propriedades do .NET, poderá contornar a supressão de exceções usando a sintaxe do método, conforme mostrado no exemplo a seguir:

"hello".get_Length()

Observe que a sintaxe do método só pode ser usada com propriedades .NET. As propriedades adicionadas pela execução do Update-TypeData cmdlet não podem usar a sintaxe do método.

Assinando um arquivo Types.ps1xml

Para proteger os usuários do arquivo Types.ps1xml , você pode assinar o arquivo usando uma assinatura digital. Para obter mais informações, consulte about_Signing.