Compartilhar via


about_Types.ps1xml

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