about_Types.ps1xml

Artigo
03/19/2024

Descrição breve

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

Descrição longa

Os 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 file: um arquivo XML que define dados de tipo estendido.
Update-TypeData: Um cmdlet que recarrega arquivos e define dados estendidos Types.ps1xml para tipos na sessão atual.

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

Sobre dados de tipo estendidos

Os dados de tipo estendido definem propriedades e métodos adicionais ("membros") de tipos de objeto no PowerShell. Você pode estender qualquer tipo com suporte do PowerShell e usar as propriedades e métodos adicionados da mesma maneira que usa as propriedades definidas nos tipos de objeto.

Por exemplo, o PowerShell adiciona uma propriedade DateTime a todos os System.DateTime objetos, como aqueles 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, porque o PowerShell adiciona a propriedade e ela fica visível somente no PowerShell.

O PowerShell define internamente um conjunto padrão de tipos estendidos. Essas informações de tipo são carregadas em cada sessão 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 em sessões do PowerShell.

Os dados de tipo estendido são definidos pelo PowerShell e carregados automaticamente em cada sessão 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.
Os 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 estã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 estendido 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, os objetos de matriz (System.Array) têm uma propriedade Length que lista o número de objetos na matriz. No entanto, como o nome Length não descreve claramente a propriedade, o PowerShell adiciona uma propriedade 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 adulteração, pois 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 à sua 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 extensão de nome de .ps1xml 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.

Depois de salvar o novo arquivo, use o Update-TypeData cmdlet para adicionar o novo arquivo à sua sessão do PowerShell. Se desejar que seus tipos tenham precedência sobre os tipos internos definidos, use o Update-TypeData parâmetro PrependData do 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 comando ao seu perfil do Update-TypeData 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 somente 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 a objetos System.IO.FileInfo . A idade de um arquivo é a diferença entre seu tempo de criação e o tempo atual em dias.

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

Salve o seguinte código XML 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 do 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, canalize 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> tag inclui todos os tipos definidos no arquivo. Deve haver apenas uma <Types> tag.

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

As tags de tipo devem conter as seguintes tags:

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

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

Qualquer uma das seguintes tags de membro pode estar dentro da <Members> tag.

AliasProperty

Define um novo nome para uma propriedade existente.

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

Por exemplo, a propriedade Count alias é 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> tag deve ter uma <Name> tag que especifique o nome do novo método e uma <CodeReference> tag que especifique o código no qual o método é definido.

Por exemplo, o método ToString é o nome da definição 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

Faz referência a um método estático de uma classe .NET.

A <CodeProperty> tag deve ter uma <Name> tag que especifique o nome da nova propriedade e uma <GetCodeReference> tag que especifique 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 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>

Conjunto de Membros

Define uma coleção de membros (propriedades e métodos).

As <MemberSet> tags aparecem dentro das tags primárias <Members> . As tags devem incluir uma <Name> tag ao redor do nome do conjunto de membros e uma tag secundária <Members> que circunda 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>) podem ser membros do conjunto.

Em 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> tags) é sempre PsStandardMembers, e os nomes das propriedades (o <Name> valor da tag) 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 de chave 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 dos serviços (System.ServiceProcess.ServiceController objetos) 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.

ObservaçãoPropriedade

Define uma propriedade com um valor estático.

A <NoteProperty> tag deve ter uma <Name> tag que especifique o nome da nova propriedade e uma <Value> tag 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 Success.

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

Conjunto de propriedades

Propriedades que usam 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> tag deve ter uma <Name> tag que especifique o nome do conjunto de propriedades e uma <ReferencedProperty> tag que especifique as propriedades. Os nomes das propriedades são incluídos na <Name> tag .

No 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> tag de uma <MemberSet> tag .

Por exemplo, o XML a seguir cria um PropertySet chamado DefaultDisplayPropertySet com três 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>

Método Script

Define um método cujo valor é a saída de um script.

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

Por exemplo, os ConvertToDateTimeConvertFromDateTime e métodos de objetos de gerenciamento (System.System.Management.ManagementObject) são métodos de script que usam os ToDateTime métodos estáticos e ToDmtfDateTime da System.Management.ManagementDateTimeConverter 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>

Propriedade Script

Define uma propriedade cujo valor é a saída de um script.

A <ScriptProperty> tag deve ter uma <Name> tag que especifique o nome da nova propriedade e uma <GetScriptBlock> tag 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 que resulta do uso da propriedade FullName do método estático GetVersionInfo dos 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 Windows PowerShell Software Development Kit (SDK).

Update-TypeData

Para carregar seus Types.ps1xml arquivos em uma sessão do PowerShell, execute o Update-TypeData cmdlet. Se desejar que os tipos no arquivo tenham precedência sobre os 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 comando ao seu perfil do Update-TypeData PowerShell.

As exceções que ocorrem em propriedades ou na adição de propriedades a um Update-TypeData comando não relatam erros ao 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 .NET, você pode contornar a supressão de exceções usando a sintaxe do método em vez disso, como mostrado no exemplo a seguir:

"hello".get_Length()

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

Assinando um arquivo Types.ps1xml

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