Compartilhar via


about_Format.ps1xml

TÓPICO
    about_Format.ps1xml

DESCRIÇÃO RESUMIDA
    Os arquivos Format.ps1xml no Windows PowerShell definem a 
    exibição padrão de objetos no console do Windows PowerShell. Você 
    pode criar seus próprios arquivos Format.ps1xml para alterar a 
    exibição de objetos ou para definir exibições padrão de novos 
    tipos de objeto criados no Windows PowerShell.

DESCRIÇÃO LONGA
    Os arquivos Format.ps1xml no Windows PowerShell definem a 
    exibição padrão de objetos no Windows PowerShell. Você pode criar 
    seus próprios arquivos Format.ps1xml para alterar a exibição de 
    objetos ou para definir exibições padrão de novos tipos de objeto 
    criados no Windows PowerShell.


    Quando o Windows PowerShell exibe um objeto, ele usa os dados em 
    arquivos de formatação estruturados para determinar a exibição 
    padrão do objeto. Os dados nos arquivos de formatação determinam 
    se o objeto é renderizado em uma tabela ou em uma lista. 
    Determinam também quais propriedades são exibidas por padrão. 


    A formatação afeta somente a exibição. Não afeta quais 
    propriedades do objeto são passadas pelo pipeline ou como são 
    passadas.


    O Windows PowerShell inclui sete arquivos de formatação. Esses 
    arquivos estão localizados no diretório de instalação ($pshome). 
    Cada arquivo define a exibição de um grupo de objetos do 
    Microsoft .NET Framework:


    Certificate.Format.ps1xml
            Objetos no repositório de Certificados, como certificados 
            X.509 e repositórios de certificados.

    DotNetTypes.Format.ps1xml
            Outros tipos do .NET Framework, como objetos CultureInfo, 
            FileVersionInfo e EventLogEntry.

    FileSystem.Format.ps1xml
            Objetos do sistema de arquivos, como arquivos e diretórios.

    Help.Format.ps1xml
            Exibições de ajuda, como exibições detalhadas e 
            completas, parâmetros e exemplos.

    PowerShellCore.format.ps1xml
            Objetos gerados pelos principais cmdlets do Windows 
            PowerShell, como Get-Member e Get-History.

    PowerShellTrace.format.ps1xml
            Objetos de rastreamento, como os gerados pelo cmdlet 
            Trace-Command.

    Registry.format.ps1xml 
            Objetos do Registro, como chaves e entradas.


    Um arquivo de formatação pode definir quatro exibições diferentes 
    de cada objeto: tabela, lista, largo e complexo. Por exemplo, 
    quando a saída de um comando Get-ChildItem é canalizada para um 
    comando Format-List, Format-List usa a exibição no arquivo 
    FileSystem.format.ps1xml para determinar como exibir os objetos 
    de arquivo e pasta como uma lista.


    Em um arquivo Format.ps1xml, uma exibição é definida por um 
    conjunto de marcas XML que descreve o nome da exibição, o tipo de 
    objeto ao qual ela pode ser aplicada, os cabeçalhos de coluna e 
    as propriedades exibidas no corpo da exibição. O formato em 
    arquivos Format.ps1xml é aplicado pouco antes de os dados serem 
    apresentados ao usuário. 

  Criando novos arquivos Format.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. Portanto, para 
      alterar o formato de exibição de uma exibição de objeto 
      existente ou adicionar exibições para novos objetos, crie seus 
      próprios arquivos Format.ps1xml e adicione-os à sua sessão do 
      Windows PowerShell.


      Para criar um novo arquivo, copie um arquivo Format.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.

      Para alterar a formatação de uma exibição atual, localize a 
      exibição no arquivo de formatação e use as marcas para alterar 
      a exibição. Para criar uma exibição para um novo tipo de 
      objeto, crie uma nova exibição ou use uma exibição existente 
      como um modelo. (As marcas são descritas na próxima seção deste 
      tópico.) Você pode excluir todas as outras exibições no arquivo 
      de modo que as alterações sejam óbvias para qualquer pessoa que 
      examine o arquivo.


      Depois de salvar as alterações, use o cmdlet Update-FormatData 
      para adicionar o novo arquivo à sua sessão do Windows 
      PowerShell. Se desejar que sua exibição tenha precedência sobre 
      outra definida nos arquivos internos, use o parâmetro 
      PrependData do cmdlet Update-FormatData. Update-FormatData 
      afeta somente a sessão atual. Para fazer a alteração para todas 
      as sessões futuras, adicione o comando Update-FormatData a seu 
      perfil do Windows PowerShell.


  Exemplo: adicionar dados do calendário a objetos de cultura

      Esse exemplo mostra como alterar a formatação dos objetos de cultura 
      (System.Globalization.CultureInfo) gerados pelo cmdlet Get-Culture.
      Os comandos no exemplo adicionam a propriedade calendar à 
      exibição da tabela padrão de objetos de cultura.


      A primeira etapa é localizar o arquivo Format.ps1xml que contém 
      a exibição atual dos objetos de cultura. O comando 
      Select-String a seguir localiza o arquivo:


      select-string -path $pshome\*format.ps1xml `
              -pattern System.Globalization.CultureInfo


      Esse comando revela que a definição está no arquivo 
      DotNetTypes.Format.ps1xml.


      O próximo comando copia o conteúdo do arquivo para um novo arquivo, 
      MyDotNetTypes.Format.ps1xml.


      copy-item DotNetTypes.Format.ps1xml MyDotNetTypes.Format.ps1xml


      Em seguida, abra o arquivo MyDotNetTypes.Format.ps1xml em 
      qualquer editor de XML ou de texto, como o Bloco de Notas. 
      Localize a seção de objeto System.Globalization.CultureInfo. O 
      XML a seguir define as exibições do objeto CultureInfo.
      O objeto tem apenas uma exibição TableControl.
 

      <View>
          <Name>System.Globalization.CultureInfo</Name>
          <ViewSelectedBy>
             <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
             <TypeName>System.Globalization.CultureInfo</TypeName>
          </ViewSelectedBy>

          <TableControl>
              <TableHeaders>
                  <TableColumnHeader>
                      <Width>16</Width>
                  </TableColumnHeader>
                  <TableColumnHeader>
                      <Width>16</Width>
                  </TableColumnHeader>
                  <TableColumnHeader/>
              </TableHeaders>
              <TableRowEntries>
                  <TableRowEntry>
                      <TableColumnItems>
                          <TableColumnItem>
                              <PropertyName>LCID</PropertyName>
                          </TableColumnItem>
                          <TableColumnItem>
                              <PropertyName>Name</PropertyName>
                          </TableColumnItem>
                          <TableColumnItem>
                              <PropertyName>DisplayName</PropertyName>
                          </TableColumnItem>
                      </TableColumnItems>
                  </TableRowEntry>
               </TableRowEntries>
          </TableControl>
      </View>


      Exclua o restante do arquivo, exceto as marcas <?XML>, 
      <Configuration> e <ViewDefinitions> de abertura e as marcas 
      <ViewDefintions> e <Configuration> de fechamento. Você também 
      precisa excluir a 
      assinatura digital sempre que alterar o arquivo.


      <?xml version="1.0" encoding="utf-8" ?>
      <Configuration>
          <ViewDefinitions>
              <View>
                  <Name>System.Globalization.CultureInfo</Name>
                  <ViewSelectedBy>
                      <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
                      <TypeName>System.Globalization.CultureInfo</TypeName>
                  </ViewSelectedBy>

                  <TableControl>
                      <TableHeaders>
                          <TableColumnHeader>
                              <Width>16</Width>
                          </TableColumnHeader>
                          <TableColumnHeader>
                              <Width>16</Width>
                          </TableColumnHeader>
                          <TableColumnHeader/>
                      </TableHeaders>
                      <TableRowEntries>
                          <TableRowEntry>
                              <TableColumnItems>
                                  <TableColumnItem>
                                      <PropertyName>LCID</PropertyName>
                                  </TableColumnItem>
                                  <TableColumnItem>
                                      <PropertyName>Name</PropertyName>
                                  </TableColumnItem>
                                  <TableColumnItem>
                                      <PropertyName>DisplayName</PropertyName>
                                  </TableColumnItem>
                              </TableColumnItems>
                          </TableRowEntry>
                       </TableRowEntries>
                  </TableControl>
              </View>
          </ViewDefinitions>
      </Configuration>


      Em seguida, crie uma nova coluna para a propriedade Calendar 
      adicionando um novo conjunto de marcas <TableColumnHeader>. O 
      valor da propriedade Calendar pode ser long, para que seja usado 
      um valor de 45 caracteres, da seguinte forma:


                <TableControl>
                    <TableHeaders>
                        <TableColumnHeader>
                            <Width>16</Width>
                        </TableColumnHeader>
                        <TableColumnHeader>
                            <Width>16</Width>
                        </TableColumnHeader>
                 
                        <TableColumnHeader>
                            <Width>45</Width>
                        </TableColumnHeader>

                        <TableColumnHeader/>
                    </TableHeaders>


      Agora, adicione um novo item de coluna nas linhas da tabela, da 
      seguinte forma:


                <TableRowEntries>
                    <TableRowEntry>
                        <TableColumnItems>
                            <TableColumnItem>
                                <PropertyName>LCID</PropertyName>
                            </TableColumnItem>
                            <TableColumnItem>
                                <PropertyName>Name</PropertyName>
                            </TableColumnItem>

                            <TableColumnItem>
                                <PropertyName>Calendar</PropertyName>
                            </TableColumnItem>

                            <TableColumnItem>
                                <PropertyName>DisplayName</PropertyName>
                            </TableColumnItem>
                        </TableColumnItems>
                    </TableRowEntry>
                 </TableRowEntries>



      Depois de salvar o arquivo e fechá-lo, use um comando 
      Update-FormatData, como o mostrado a seguir, para adicionar o 
      novo arquivo de formato à sessão atual. O comando usa o 
      parâmetro PrependData para colocar o novo arquivo em uma ordem 
      de precedência mais alta que a do arquivo original. (Para obter 
      mais informações sobre Update-FormatData, digite "get-help 
      update-formatdata".)


      update-formatdata -prependpath $pshome\MyDotNetTypes.format.ps1xml


      Para testar a alteração, digite "get-culture" e examine a 
      saída, que inclui a propriedade Calendar.


      C:\PS> get-culture

      LCID Name  Calendar                               DisplayName
      ---- ----  --------                               -----------
      1033 en-US System.Globalization.GregorianCalendar English (United States)


  O XML nos arquivos Format.ps1xml

      A seção ViewDefinitions de cada arquivo Format.ps1xml contém as 
      marcas <View> que definem cada exibição. Uma marca <View> 
      típica inclui as seguintes marcas:

    
          <Name>
              Uma marca <Name> identifica o nome da exibição.


          <ViewSelectedBy>
              A marca <ViewSelectedBy> especifica o(s) tipo(s) de 
              objeto ao(s)qual(ais) a exibição se aplica.

    
          <GroupBy>
              Uma marca <GroupBy> especifica como os itens na 
              exibição serão combinados em grupos.


          <TableControl>
          <ListControl>
          <WideControl>
          <ComplexControl>
              Essas marcas contêm as marcas que especificam como cada 
              item será exibido.

    
      A marca <ViewSelectedBy> pode conter uma marca <TypeName> para 
      cada tipo de objeto ao qual a exibição se aplica. Ou contém uma 
      marca <SelectionSetName> que faz referência a um conjunto de 
      seleção definido em outro lugar com o uso de uma marca 
      <SelectionSet>.


      A marca <GroupBy> contém uma marca <PropertyName> que 
      especifica a propriedade do objeto pela qual os itens serão 
      agrupados. Também contém uma marca <Label> que especifica uma 
      cadeia de caracteres a ser usada como um rótulo para cada grupo 
      ou uma marca <ComplexControlName> que faz referência a um 
      controle complexo definido em outro lugar com o uso de uma 
      marca <Control>. A marca <Control> contém uma marca <Name> e 
      uma marca <ComplexControl>. 

    
      A marca <TableControl> normalmente contém marcas <TableHeaders> e 
      <TableRowEntries> que definem a formatação para os títulos e as 
      linhas da tabela. A marca <TableHeaders> normalmente contém marcas 
      <TableColumnHeader> que contêm marcas <Label>, <Width> e <Alignment>. 
      A marca <TableRowEntries> contém marcas <TableRowEntry> para cada 
      linha na tabela. A marca <TableRowEntry> contém uma marca 
      <TableColumnItems> que contém uma marca <TableColumnItem> para cada 
      coluna da linha. Normalmente, a marca <TableColumnItem> contém uma 
      marca <PropertyName> que identifica a propriedade do objeto a ser 
      exibida no local definido ou uma marca <ScriptBlock> que contém 
      o código de script que calcula um resultado a ser exibido no local. 


      Observação: blocos de script também podem ser usados em outros 
              locais onde resultados calculados podem ser úteis. 

    
      A marca <TableColumnItem> também pode conter uma marca 
      <FormatString> que especifica como a propriedade ou os 
      resultados calculados serão exibidos.

    
      A marca <ListControl> normalmente contém uma marca 
      <ListEntries>. A marca <ListEntries> contém uma marca 
      <ListItems>. A marca <ListItems> contém marcas <ListItem>, que 
      contêm marcas <PropertyName>. As marcas <PropertyName> 
      especificam a propriedade do objeto a ser exibida no local 
      especificado na lista. Se a seleção de exibição for definida 
      com o uso de um conjunto de seleção, a marca <ListControl> 
      também poderá conter uma marca <EntrySelectedBy>, que, por sua 
      vez, contém uma ou mais marcas <TypeName>. Essas marcas 
      <TypeName> especificam o tipo de objeto que a marca 
      <ListControl> deve exibir.

    
      A marca <WideControl> normalmente contém uma marca 
      <WideEntries>. A marca <WideEntries> contém uma ou mais marcas 
      <WideEntry>. Uma marca <WideEntry> normalmente contém uma marca 
      <PropertyName> que especifica a propriedade a ser exibida no 
      local especificado na exibição. A marca <PropertyName> pode 
      conter uma marca <FormatString> que especifica como a 
      propriedade deve ser exibida. 

    
      A marca <ComplexControl> contém combinações mais complexas de 
      marcas que outros tipos de exibição. Uma marca <ComplexControl> 
      normalmente contém uma marca <ComplexEntries>. Uma marca 
      <ComplexEntries> contém várias marcas <ComplexEntry>. Uma marca 
      <ComplexEntry> normalmente contém uma marca <ComplexItem>. Essa 
      marca, por sua vez, pode conter várias marcas que especificam o 
      conteúdo e a formatação para o local especificado na exibição, 
      incluindo marcas <Text>, <Indentation>, <ExpressionBinding> e 
      <NewLine>.


  Update-FormatData

      Para carregar seus arquivos Format.ps1xml em uma sessão do 
      Windows PowerShell, use o cmdlet Update-FormatData. Se quiser 
      que as exibições no seu arquivo tenham precedência sobre as do 
      arquivo Format.ps1xml interno, use o parâmetro PrependData de 
      Update-FormatData. Update-FormatData afeta somente a sessão 
      atual. Para fazer a alteração para todas as sessões futuras, 
      adicione o comando Update-FormatData a seu perfil do Windows 
      PowerShell.


  Exibições padrão em Types.ps1xml

      As exibições padrão de alguns tipos de objeto básicos são 
      definidas no arquivo Types.ps1xml no diretório $pshome. Os nós são 
      PsStandardMembers nomeados, e o subnós usam uma das seguintes marcas:


          <DefaultDisplayProperty>
          <DefaultDisplayPropertySet>
          <DefaultKeyPropertySet>


      Para obter mais informações, digite o seguinte comando:

      get-help about_types.ps1xml
 

  Rastreando o uso do arquivo Format.ps1xml

      Para detectar erros no carregamento ou na aplicação de arquivos 
      Format.ps1xml, use o cmdlet Trace-Command com qualquer um dos 
      seguintes componentes de formato como valor do parâmetro Name:


      FormatFileLoading
          UpdateFormatData
          FormatViewBinding


      Para obter mais informações, digite os seguintes comandos:


          get-help trace-command
          get-help get-tracesource   


  Assinando um arquivo Format.ps1xml

      Para proteger os usuários do seu arquivo Format.ps1xml, assine 
      o arquivo usando uma assinatura digital. Para obter 
      informações, digite:

          get-help about_signing


CONSULTE TAMBÉM
    Update-FormatData
    Trace-Command
    Get-TraceSource