Compartilhar via

about_Format.ps1xml

  • Artigo

Descrição breve

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

Descrição longa

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

Quando o PowerShell exibe um objeto, ele usa os dados em arquivos de formatação estruturada 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 e determinam quais propriedades são exibidas por padrão.

A formatação afeta apenas a exibição. Isso não afeta quais propriedades de objeto são passadas pelo pipeline ou como elas são passadas. Format.ps1xml Os arquivos não podem ser usados para personalizar o formato de saída para tabelas de hash.

O 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:

  1. Certificate.Format.ps1xml

    Objetos no repositório de certificados, como certificados X.509 e repositórios de certificados.

  2. DotNetTypes.Format.ps1xml

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

  3. FileSystem.Format.ps1xml

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

  4. Help.Format.ps1xml

    Visualizações de ajuda, como exibições detalhadas e completas, parâmetros e exemplos.

  5. PowerShellCore.Format.ps1xml

    Objetos gerados por cmdlets principais do PowerShell, como Get-Member e Get-History.

  6. PowerShellTrace.Format.ps1xml

    Objetos de rastreamento, como aqueles gerados pelo Trace-Command cmdlet.

  7. Registry.Format.ps1xml

    Objetos do Registro, como chaves e entradas.

Um arquivo de formatação pode definir quatro modos de exibição diferentes de cada objeto:

  • Tabela
  • Lista
  • Largo
  • Personalizado

Por exemplo, quando a saída de um Get-ChildItem comando é canalizada para um Format-List comando, Format-List o usa a exibição no FileSystem.Format.ps1xml arquivo para determinar como exibir os objetos de arquivo e pasta como uma lista.

Quando um arquivo de formatação inclui mais de uma exibição de um objeto, o PowerShell aplica a primeira exibição encontrada.

Em um Format.ps1xml arquivo, uma exibição é definida por um conjunto de marcas XML que descrevem 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 nos Format.ps1xml arquivos é aplicado imediatamente antes de os dados serem apresentados ao usuário.

Criando novos arquivos Format.ps1xml

Os .ps1xml arquivos instalados com o PowerShell são assinados digitalmente para evitar adulteração porque a formatação pode incluir blocos de script. Para alterar o formato de exibição de um modo de exibição de objeto existente ou adicionar modos de exibição para novos objetos, crie seus próprios Format.ps1xml arquivos e adicione-os à sua sessão do PowerShell.

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

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

Depois de salvar as alterações, use o Update-FormatData cmdlet para adicionar o novo arquivo à sua sessão do PowerShell. Se você quiser que seu modo de exibição tenha precedência sobre um modo de exibição definido nos arquivos internos, use o parâmetro PrependPath . Update-FormatData afeta apenas a sessão atual. Para fazer a alteração em todas as sessões futuras, adicione o Update-FormatData comando ao seu perfil do PowerShell.

Exemplo: Adicionando dados de calendário a objetos de cultura

Este exemplo mostra como alterar a formatação dos objetos de cultura System.Globalization.CultureInfo gerados pelo Get-Culture cmdlet na sessão atual do PowerShell. Os comandos no exemplo adicionam a propriedade Calendar à exibição de exibição de tabela padrão de objetos de cultura.

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

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.Globalization.CultureInfo"
}

Select-String @Parms

C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:113:
     <Name>System.Globalization.CultureInfo</Name>
C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:115:
<TypeName>System.Globalization.CultureInfo</TypeName>

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

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

Copy-Item $PSHome\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml

Abra o arquivo em qualquer editor XML ou de texto, como o MyDotNetTypes.Format.ps1xml Visual Studio Code. 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>
    </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 tags de abertura<?xml>, , e <ViewDefinitions> e as tags closing <ViewDefinitions> and <Configuration> <Configuration>. Se houver uma assinatura digital, exclua-a do seu arquivo personalizado Format.ps1xml.

O MyDotNetTypes.Format.ps1xml arquivo agora deve ser semelhante ao seguinte exemplo:

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

Crie uma nova coluna para a propriedade Calendar adicionando um novo conjunto de <TableColumnHeader> tags. O valor da propriedade Calendar pode ser longo, portanto, especifique um valor de 45 caracteres como o <Width>.

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

Adicione um novo item de coluna para Calendário nas linhas da tabela usando as <TableColumnItem> tags e <PropertyName :

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

Salve e feche o arquivo. Use Update-FormatData para adicionar o novo arquivo de formato à sessão atual do PowerShell.

Este exemplo usa o parâmetro PrependPath para colocar o novo arquivo em uma ordem de precedência mais alta do que o arquivo original. Para obter mais informações, consulte Update-FormatData.

Update-FormatData -PrependPath $PSHOME\MyDotNetTypes.Format.ps1xml

Para testar a alteração, digite Get-Culture e revise a saída que inclui a propriedade Calendar .

Get-Culture

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

O XML em arquivos Format.ps1xml

A definição completa do esquema pode ser encontrada em Format.xsd no repositório de código-fonte do PowerShell no GitHub.

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

  • <Name> identifica o nome da exibição.
  • <ViewSelectedBy> Especifica o tipo ou tipos de objeto aos quais a exibição se aplica.
  • <GroupBy> Especifica como os itens na exibição serão combinados em grupos.
  • <TableControl>, <ListControl>, <WideControl>e <CustomControl> contêm as tags que especificam como cada item será exibido.

Marca ViewSelectedBy

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

Tag GroupBy

A <GroupBy> tag contém uma <PropertyName> tag que especifica a propriedade do objeto pela qual os itens devem ser agrupados. Ele também contém uma <Label> marca que especifica uma cadeia de caracteres a ser usada como um rótulo para cada grupo ou uma <CustomControlName> marca que faz referência a um controle personalizado definido em outro lugar usando uma <Control> marca. A <Control> tag contém uma <Name> tag e uma <CustomControl> tag.

TableControlTag

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

Observação

Os blocos de script também podem ser usados em outros locais onde os resultados calculados podem ser úteis.

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

Marca ListControl

A <ListControl> tag normalmente contém uma <ListEntries> tag. A <ListEntries> tag contém uma <ListEntry> tag. A <ListEntry> tag contém uma <ListItems> tag. A <ListItems> tag contém <ListItem> tags, que contêm <PropertyName> tags. As <PropertyName> tags especificam a propriedade do objeto a ser exibida no local especificado na lista. Se a seleção de exibição for definida usando um conjunto de seleção, as <ListControl> tags and <ListEntry> também poderão conter uma <EntrySelectedBy> tag que contenha uma ou mais <TypeName> tags. Essas <TypeName> tags especificam o tipo de objeto que a <ListControl> tag deve exibir.

Marca WideControl

A <WideControl> tag normalmente contém uma <WideEntries> tag. A <WideEntries> tag contém uma ou mais <WideEntry> tags. Uma <WideEntry> tag contém uma <WideItem> tag.

Uma <WideItem> tag deve incluir uma <PropertyName> tag ou uma <ScriptBlock> tag. Uma <PropertyName> tag especifica a propriedade a ser exibida no local especificado na vista. Uma <ScriptBlock> tag especifica um script a ser avaliado e exibido no local especificado na exibição.

Uma <WideItem> tag pode conter uma <FormatString> tag que especifica como exibir a propriedade.

Marca CustomControl

A <CustomControl> tag permite que você use um bloco de script para definir um formato. Uma <CustomControl> tag normalmente contém uma <CustomEntries> tag que contém várias <CustomEntry> tags. Cada <CustomEntry> marca contém uma <CustomItem> marca que pode conter uma variedade de marcas que especificam o conteúdo e a formatação do local especificado na exibição, incluindo <Text>, <Indentation>, <ExpressionBinding>, e <NewLine> marcas.

Exibições padrão em Types.ps1xml

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

  • <DefaultDisplayProperty>
  • <DefaultDisplayPropertySet>
  • <DefaultKeyPropertySet>

Para obter mais informações, consulte about_Types.ps1xml.

Rastreamento do uso do arquivo Format.ps1xml

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

  • FormatFileLoading
  • FormatViewBinding

Para obter mais informações, consulte Trace-Command e Get-TraceSource.

Assinando um arquivo Format.ps1xml

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

XML de exemplo para uma exibição personalizada Format-Table

O exemplo a seguir cria uma Format-Table exibição personalizada para os objetos System.IO.DirectoryInfo e System.IO.FileInfo criados pelo Get-ChildItem. A exibição personalizada é chamada mygciview e adiciona a coluna CreationTime à tabela.

A exibição personalizada é criada a partir de uma versão editada do FileSystem.Format.ps1xml arquivo armazenado no $PSHOME PowerShell 5.1.

Depois que o arquivo personalizado .ps1xml for salvo, use Update-FormatData para incluir a exibição em uma sessão do PowerShell. Para este exemplo, a exibição personalizada deve usar o formato de tabela, caso contrário, Format-Table falhará.

Use Format-Table com o parâmetro View para especificar o nome da exibição personalizada e formatar a saída da tabela. Para obter um exemplo de como o comando é executado, consulte Format-Table.

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.IO.DirectoryInfo"
}
Select-String @Parms
Copy-Item $PSHome\FileSystem.format.ps1xml .\MyFileSystem.Format.ps1xml
Update-FormatData -PrependPath $PSHOME\Format\MyFileSystem.Format.ps1xml

Observação

Para ajustar o exemplo XML dentro das limitações de largura de linha, foi necessário compactar algum recuo e usar quebras de linha dentro do código.

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
    <SelectionSets>
        <SelectionSet>
            <Name>FileSystemTypes</Name>
            <Types>
                <TypeName>System.IO.DirectoryInfo</TypeName>
                <TypeName>System.IO.FileInfo</TypeName>
            </Types>
        </SelectionSet>
    </SelectionSets>
<Controls>
<Control>
<Name>FileSystemTypes-GroupingFormat</Name>
<CustomControl>
 <CustomEntries>
  <CustomEntry>
    <CustomItem>
    <Frame>
    <LeftIndent>4</LeftIndent>
    <CustomItem>
    <Text AssemblyName="System.Management.Automation"
    BaseName="FileSystemProviderStrings"
    ResourceId="DirectoryDisplayGrouping"/>
    <ExpressionBinding>
     <ScriptBlock>
      $_.PSParentPath.Replace("Microsoft.PowerShell.Core\FileSystem::", "")
     </ScriptBlock>
    </ExpressionBinding>
    <NewLine/>
    </CustomItem>
    </Frame>
    </CustomItem>
    </CustomEntry>
 </CustomEntries>
</CustomControl>
</Control>
</Controls>
<ViewDefinitions>
    <View>
    <Name>mygciview</Name>
    <ViewSelectedBy>
        <SelectionSetName>FileSystemTypes</SelectionSetName>
    </ViewSelectedBy>
    <GroupBy>
      <PropertyName>PSParentPath</PropertyName>
      <CustomControlName>FileSystemTypes-GroupingFormat</CustomControlName>
    </GroupBy>
        <TableControl>
            <TableHeaders>
                <TableColumnHeader>
                    <Label>Mode</Label>
                    <Width>7</Width>
                    <Alignment>left</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>LastWriteTime</Label>
                    <Width>25</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>CreationTime</Label>
                    <Width>25</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>Length</Label>
                    <Width>14</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader/>
            </TableHeaders>
            <TableRowEntries>
                <TableRowEntry>
                    <Wrap/>
                    <TableColumnItems>
                        <TableColumnItem>
                            <PropertyName>Mode</PropertyName>
                        </TableColumnItem>
                        <TableColumnItem>
                            <ScriptBlock>
                                [String]::Format("{0,10}  {1,8}",
                                    $_.LastWriteTime.ToString("d"),
                                    $_.LastWriteTime.ToString("t"))
                            </ScriptBlock>
                        </TableColumnItem>
                        <TableColumnItem>
                            <ScriptBlock>
                                [String]::Format("{0,10}  {1,8}",
                                    $_.CreationTime.ToString("d"),
                                    $_.LastWriteTime.ToString("t"))
                            </ScriptBlock>
                        </TableColumnItem>
                        <TableColumnItem>
                        <PropertyName>Length</PropertyName>
                        </TableColumnItem>
                        <TableColumnItem>
                            <PropertyName>Name</PropertyName>
                        </TableColumnItem>
                    </TableColumnItems>
                </TableRowEntry>
            </TableRowEntries>
        </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

Confira também