about_Types.ps1xml
Breve descrição
Explica como usar Types.ps1xml
arquivos para estender os tipos de objetos usados no PowerShell.
Descrição longa
Os dados de tipo estendidos definem propriedades e métodos adicionais ("membros") de tipos de objeto no PowerShell. Há duas técnicas para adicionar dados de tipo estendidos a uma sessão do PowerShell.
-
Types.ps1xml
file: um arquivo XML que define dados de tipo estendidos. -
Update-TypeData
: Um cmdlet que recarrega arquivos e define dados estendidosTypes.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 estendidos dinâmicos à sessão atual, consulte Update-TypeData.
Sobre dados de tipo estendidos
Os dados de tipo estendidos definem propriedades e métodos adicionais ("membros") de tipos de objeto no PowerShell. Você pode estender qualquer tipo suportado pelo PowerShell e usar as propriedades e 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, porque o PowerShell adiciona a propriedade e ela é 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 estendidos ao PowerShell
Há três fontes de dados de tipo estendido em sessões do PowerShell.
Os dados de tipo estendidos 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 estendidos 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 estendidos 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 arquivosTypes.ps1xml
. 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 da Ajuda para cada cmdlet.
Arquivos Types.ps1xml integrados
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 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 afetada do PowerShell. 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 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
o , 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
142
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 .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>
: Encerra as tags 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 especifica o nome do novo método e uma <CodeReference>
tag que especifica 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 está definida.
Por exemplo, a 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>
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 tags que criam uma propriedade (como <NoteProperty>
ou <ScriptProperty>
) ou um método (como <Method>
ou <ScriptMethod>
) pode 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 <Name>
das tags) é sempre PsStandardMembers, e os nomes das propriedades (o valor da <Name>
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 principais de um objeto. Uma propriedade key 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 Name.
<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.
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 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>
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>
ScriptMethod
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 ConvertToDateTime
métodos e ConvertFromDateTime
de objetos de gerenciamento (System.System.Management.ManagementObject
) são métodos de script que usam os ToDateTime
métodos e ToDmtfDateTime
estáticos 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>
ScriptProperty
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 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 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 para StdErr
. Isso é para suprimir exceções que ocorreriam em muitos tipos comuns durante a formatação e 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 sintaxe do Update-TypeData
método.
Assinando um arquivo Types.ps1xml
Para proteger os usuários do seu Types.ps1xml
arquivo, você pode assiná-lo usando uma assinatura digital. Para obter mais informações, consulte about_Signing.