TÓPICO
about_Types.ps1xml
DESCRIÇÃO RESUMIDA
Explica como os arquivos Types.ps1xml permitem estender os tipos
do Microsoft .NET Framework dos objetos usados no Windows PowerShell.
DESCRIÇÃO LONGA
O arquivo Types.ps1xml no diretório de instalação do Windows
PowerShell ($pshome) é um arquivo de texto baseado em XML que
permite acrescentar propriedades e métodos aos objetos usados no
Windows PowerShell. O Windows PowerShell tem um arquivo
Types.ps1xml interno que acrescenta vários elementos aos tipos do
.NET Framework, mas você pode criar arquivos Types.ps1xml
adicionais para estender ainda mais os tipos.
Por exemplo, os objetos de matriz (System.Array) têm por padrão
uma propriedade Length que lista o número de objetos na matriz.
Porém, como o nome " length" não descreve claramente a
propriedade, o Windows PowerShell adiciona uma propriedade de
alias denominada "Count" que exibe o mesmo valor. O XML a seguir
acrescenta a propriedade Count ao tipo System.Array.
<Type>
<Name>System.Array</Name>
<Members>
<AliasProperty>
<Name>Count</Name>
<ReferencedMemberName>
Length
</ReferencedMemberName>
</AliasProperty>
</Members>
</Type>
Para obter a nova AliasProperty, use um comando Get-Member em
qualquer matriz, como mostrado no exemplo a seguir.
Get-Member -inputobject (1,2,3,4)
O comando retorna os resultados a seguir.
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 das matrizes no Windows PowerShell. Por exemplo:
C:\PS> (1, 2, 3, 4).count
4
C:\PS> (1, 2, 3, 4).length
4
Criando novos arquivos Types.ps1xml
Os arquivos .ps1xml instalados com o Windows PowerShell são
assinados digitalmente para impedir falsificação, pois a
formatação pode incluir blocos de script. Assim, para adicionar
uma propriedade ou um método a um tipo do .NET Framework, crie
seus próprios arquivos Types.ps1xml, e então adicione-os ao seu
console do Windows PowerShell.
Para criar um novo arquivo, comece copiando um arquivo
Types.ps1xml existente. O novo arquivo pode ter qualquer nome,
mas deve ter a extensão de nome de arquivo .ps1xml. Você pode
colocar o novo arquivo em qualquer diretório acessível ao
Windows PowerShell, mas é útil colocar os arquivos no diretório
de instalação do Windows PowerShell ($pshome) ou em um
subdiretório do diretório de instalação.
Depois de salvar o novo arquivo, use o cmdlet Update-TypeData
para adicioná-lo ao seu console do Windows PowerShell. Se
quiser que seus tipos tenham precedência sobre os definidos no
arquivo interno, use o parâmetro PrependData do cmdlet
Update-TypeData. Update-TypeData afeta somente o console atual.
Para fazer a alteração em todos os consoles futuros, exporte o
console ou adicione o comando Update-TypeData ao seu perfil do
Windows PowerShell.
Types.ps1xml e Add-Member
Os arquivos Types.ps1xml adicionam propriedades e métodos a
todas as instâncias dos objetos do tipo do .NET Framework
especificado no console do Windows PowerShell afetado. No
entanto, se você precisar adicionar propriedades ou métodos a
apenas uma instância de um objeto, use o cmdlet Add-Member.
Para obter mais informações, consulte Add-Member.
Exemplo: acrescentando um membro Age a objetos FileInfo
Este exemplo mostra como adicionar uma propriedade Age a
objetos de arquivo (System.IO.FileInfo). A idade de um arquivo
é a diferença entre sua hora de criação e a hora atual em dias.
É mais fácil usar o arquivo Types.ps1xml original como modelo
para o novo arquivo. O comando a seguir copia o arquivo
original para um arquivo chamado MyTypes.ps1xml no diretório
$pshome.
copy-item Types.ps1xml MyTypes.ps1xml
Em seguida, abra o arquivo Types.ps1xml em qualquer editor de
XML ou de texto, como o Bloco de Notas. Como a propriedade Age
é calculada usando um bloco de script, encontre uma marca
<ScriptProperty> para usar como modelo para a nova propriedade Age.
Copie o XML entre as marcas <Type> e </Type> do código para
criar a propriedade de script. Depois, exclua o restante do
arquivo, exceto as marcas <?xml> e <Types> de abertura e a
marca </Types> de fechamento. Você precisa também excluir a
assinatura digital para impedir a ocorrência de erros.
Comece com a propriedade de script modelo, como a propriedade
de script a seguir, que foi copiada do arquivo Types.ps1xml
original.
<?xml version="1.0" encoding="utf-8" ?>
<Types>
<Type>
<Name>System.Guid</Name>
<Members>
<ScriptProperty>
<Name>Guid</Name>
<GetScriptBlock>$this.ToString()</GetScriptBlock>
</ScriptProperty>
</Members>
</Type>
</Types>
Depois, altere o nome do tipo do .NET Framework, o nome da
propriedade e o valor do bloco de script, a fim de criar uma
propriedade Age para objetos de arquivo.
<?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>
Depois de salvar e fechar o arquivo, use um comando
Update-TypeData, como o mostrado a seguir, para adicionar o
novo arquivo Types.ps1xml ao console atual. O comando usa o
parâmetro PrependData para colocar o novo arquivo em uma ordem
de precedência mais alta do que o arquivo original (para obter
mais informações sobre Update-TypeData, consulte Update-TypeData).
update-typedata -prependpath $pshome\MyTypes.ps1xml
Para testar a alteração, use um comando Get-ChildItem para
obter o arquivo PowerShell.exe no diretório $pshome, e então
canalize o arquivo para o cmdlet Format-List para listar todas
as propriedades do arquivo. Como resultado da alteração, a
propriedade Age aparece na lista.
get-childitem $pshome\powershell.exe | format-list -property *
PSPath : Microsoft.PowerShell.Core\FileSystem::C:\WINDOWS...
PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\WINDOWS...
PSChildName : powershell.exe
PSDrive : C
PSProvider : Microsoft.PowerShell.Core\FileSystem
PSIsContainer : False
Age : 16
VersionInfo : File: C:\WINDOWS\system32\WindowsPow...
InternalName: POWERSHELL
OriginalFilename: PowerShell.EXE
...
Você também pode exibir a propriedade Age do arquivo usando o
comando a seguir.
(get-childitem $pshome\powershell.exe).age
16
O XML nos arquivos Types.ps1xml
A marca <Types> inclui todos os tipos definidos no arquivo.
Deve haver apenas um par de marcas <Types>.
Cada tipo do .NET Framework mencionado no arquivo deve ser
representado por um par de marcas <Type>.
As marcas de tipo devem conter as seguintes marcas:
<Name>: um par de marcas <Name> incluindo o nome do tipo do
.NET Framework afetado.
<Members>: um par de marcas <Members> incluindo as marcas das
novas propriedades e métodos definidos para o tipo do
.NET Framework.
Qualquer uma das marcas de membro a seguir pode estar entre as
marcas <Members>.
<AliasProperty>: define um novo nome para uma propriedade existente.
A marca <AliasProperty> precisa ter um par de marcas <Name>
especificando o nome da nova propriedade, e um par de marcas
<ReferencedMemberName> especificando 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 do .NET Framework.
A marca <CodeMethod> deve ter um par de marcas <Name>
especificando o nome do novo método, e um par de marcas
<GetCodeReference> especificando o código no qual o método é
definido.
Por exemplo, a propriedade Mode de diretórios (objetos
System.IO.DirectoryInfo) é uma propriedade de código
definida no provedor FileSystem do Windows 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>
<CodeProperty>: faz referência a um método estático de uma classe do .NET Framework.
A marca <CodeProperty> deve ter um par de marcas <Name>
especificando o nome da nova propriedade, e um par de marcas
<GetCodeReference> especificando o código no qual a
propriedade é definida.
Por exemplo, a propriedade Mode de diretórios (objetos
System.IO.DirectoryInfo) é uma propriedade de código
definida no provedor FileSystem do Windows 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 uma coleção de membros (propriedades e métodos).
As marcas <MemberSet> aparecem dentro das marcas <Members>
principais. As marcas precisam incluir um par de marcas
<Name> em torno do nome do conjunto de membros e um par de
marcas <Members> secundárias em torno dos membros
(propriedades e métodos) no conjunto. Qualquer marca que
crie uma propriedade (como <NoteProperty> ou <ScriptProperty>)
ou um método (como <Method> ou <ScriptMethod>) pode ser membro do conjunto.
Nos arquivos Types.ps1xml, a marca <MemberSet> é usada para
definir as exibições padrão dos objetos do .NET Framework no Windows
PowerShell. Nesse caso, o nome do conjunto de membros (o
valor entre as marcas <Name>) é sempre "PsStandardMembers",
e os nomes das propriedades (o valor da marca <Name>) são um
dos seguintes:
- DefaultDisplayProperty: uma propriedade única de um objeto.
- DefaultDisplayPropertySet: uma ou mais propriedades de
um objeto.
- DefaultKeyPropertySet: uma ou mais propriedades
principais de um objeto. Uma propriedade principal
identifica instâncias de valores de propriedade, como o
número de ID dos itens em um histórico de sessão.
Por exemplo, o XML a seguir define a exibição padrão de
serviços (objetos System.ServiceProcess.ServiceController)
retornados pelo cmdlet Get-Service. Ele define um conjunto
de membros denominado "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 marca <NoteProperty> precisa ter um par de marcas <Name>
especificando o nome da nova propriedade, e um par de marcas
<Value> especificando o valor da propriedade.
Por exemplo, o XML a seguir cria uma propriedade Status para
diretórios (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>
<ParameterizedProperty>: propriedades que usam argumentos e
retornam um valor.
<Properties>: uma coleção de propriedades do objeto.
<Property>: uma propriedade do objeto base.
<PropertySet>: define uma coleção de propriedades do objeto.
A marca <PropertySet> precisa ter um par de marcas <Name>
especificando o nome do conjunto de propriedades, e um par
de marcas <ReferencedProperty> especificando as
propriedades. Os nomes das propriedades ficam entre pares de
marcas <Name>.
Em Types.ps1xml, as marcas <PropertySet> 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 marca <Name> de uma marca <MemberSet>.
Por exemplo, o XML a seguir cria uma propriedade Status para
diretórios (objetos System.IO.DirectoryInfo). O valor da
propriedade Status é sempre "Success".
<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 marca <ScriptMethod> deve ter um par de marcas <Name>
especificando o nome do novo método, e um par de marcas
<Script> incluindo o bloco de script que retorna o resultado
do método.
Por exemplo, os métodos ConvertToDateTime e ConvertFromDateTi
me de objetos de gerenciamento (System.System.Management.Mana
gementObject) são métodos de script que usam os métodos
estáticos ToDateTime e ToDmtfDateTime da classe
System.Management.ManagementDateTimeConverter.
<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 marca <ScriptProperty> deve ter um par de marcas <Name>
especificando o nome da nova propriedade, e um par de marcas
<GetScriptBlock> incluindo o bloco de script que retorna o
valor da propriedade.
Por exemplo, a propriedade VersionInfo de arquivos (objetos
System.IO.FileInfo) é uma propriedade de script resultante
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 SDK (Software
Development Kit) do Windows PowerShell na biblioteca do MSDN
(Microsoft Developer Network) em https://go.microsoft.com/fwlink/
?LinkId=144538.
Update-TypeData
Para carregar seus arquivos Types.ps1xml em um console do
Windows PowerShell, use o cmdlet Update-TypeData. Se quiser que
os tipos no seu arquivo tenham precedência sobre aqueles no
arquivo Types.ps1xml interno, use o parâmetro PrependData de
Update-TypeData. Update-TypeData afeta somente o console atual.
Para fazer a alteração em todos os consoles futuros, exporte o
console ou adicione o comando Update-TypeData ao seu perfil do
Windows PowerShell.
Assinando um arquivo Types.ps1xml
Para proteger os usuários do seu arquivo Types.ps1xml, você
pode assiná-lo usando uma assinatura digital. Para obter mais
informações, consulte about_Signing.
CONSULTE TAMBÉM
about_Signing
Copy-Item
Get-Member
Update-TypeData