about_Types.ps1xml

Descrição curta

Explica como usar Types.ps1xml arquivos para estender os tipos de objetos 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 Types.ps1xml arquivos e define dados estendidos 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 dinâmicos de tipo estendido à sessão atual, consulte Update-TypeData.

Sobre dados de tipo estendido

Os 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 os métodos adicionados da mesma forma 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 , pois o PowerShell adiciona a propriedade e ela é 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 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 origens são aplicados aos 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 estendido na sessão atual.
Update-TypeData: Recarrega Types.ps1xml arquivos. Adiciona dados de tipo estendido à 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 de 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 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 impedir a adulteração porque a formatação pode incluir scriptblocks. 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 você quiser que seus tipos tenham 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 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 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 a objetos System.IO.FileInfo . A idade de um arquivo é a diferença entre a hora de criação e a hora atual em dias.

Como a propriedade Age é calculada usando um scriptblock, 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>

Executar 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-TypeDatao , consulte Update-TypeData.

Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml

Para testar a alteração, execute um comando Get-ChildItem para obter o arquivo powershell.exe no diretório $PSHOME e, em seguida, redirecione o arquivo para o cmdlet Format-List para listar todas as propriedades do arquivo. Como resultado da alteração, a propriedade Idade 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 marcas de membro a seguir pode estar dentro da <Members> marca.

Propriedade de alias

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>

Método de código

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>

Propriedade do código

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

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

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

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> 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) retornados pelo Get-Service cmdlet. Ele define um conjunto de membros chamado PsStandardMembers que consiste em um conjunto de propriedades padrão e uma propriedade de exibição padrão. Ele define o conjunto de propriedades padrão como as propriedades Status, Name e DisplayName . Ele define a propriedade de exibição padrão como Nome.

<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>
        <NoteProperty>
          <Name>DefaultDisplayProperty</Name>
          <Value>Name</Value>
        </NoteProperty>
      </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.

Propriedade de Observação

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 Êxito.

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

Conjunto de propriedades

Propriedades que recebem 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 tags <Name> .

No Types.ps1xml, <PropertySet> as tags 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 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 de script

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 coloque o scriptblock que retorna o resultado do método.

Por exemplo, os ConvertToDateTime métodos and ConvertFromDateTime 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 do script

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 coloque o scriptblock 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 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 (Software Development Kit) do Windows PowerShell.

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 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 Update-TypeData comando ao seu perfil do PowerShell.

As exceções que ocorrem nas propriedades ou na adição de propriedades a um Update-TypeData comando não relatam erros para StdErro . 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 cmdlet não podem usar a Update-TypeData sintaxe do método.

Assinando um arquivo Types.ps1xml

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

Consulte também

Comentários

Esta página foi útil?

Last updated on 2026-01-18