about_Format.ps1xml

Breve descrição

A partir do PowerShell 6, as exibições padrão para objetos são definidas no código-fonte do PowerShell.

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

Descrição longa

A partir do PowerShell 6, as exibições padrão são definidas no código-fonte do PowerShell. Os arquivos Format.ps1xml do PowerShell 5.1 e versões anteriores não existem no PowerShell 6 e versões posteriores.

O código-fonte do PowerShell define a exibição padrão de objetos no console do PowerShell. Você pode criar seus próprios arquivos de Format.ps1xml para alterar a exibição de objetos ou para 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 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 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 através do pipeline ou como são passadas. Format.ps1xml arquivos não podem ser usados para personalizar o formato de saída para tabelas de hash.

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

Tabela
Lista
Amplo
Personalizado

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

Quando um arquivo de formatação inclui mais de um modo de exibição de um objeto, o PowerShell aplica o primeiro modo de exibição encontrado.

Em um ficheiro Format.ps1xml personalizado, uma vista é definida por um conjunto de tags XML que descrevem o nome da vista, o tipo de objeto ao qual pode ser aplicada, as cabeçalhos de coluna e as propriedades mostradas no corpo da vista. O formato nos ficheiros Format.ps1xml é aplicado imediatamente antes dos dados serem apresentados ao utilizador.

Criando novos arquivos Format.ps1xml

Para alterar o formato de exibição de um modo de exibição de objeto existente ou para adicionar modos de exibição para novos objetos, crie seus próprios arquivos de Format.ps1xml e adicione-os à sua sessão do PowerShell.

Para criar um arquivo para definir uma exibição personalizada, use os Get-FormatData e cmdlets Export-FormatData. Use um editor de texto para editar o arquivo. O arquivo pode ser salvo em qualquer diretório que o PowerShell possa acessar, como um subdiretório do $HOME.

Para alterar a formatação de uma vista atual, localize a vista no ficheiro de formatação e, em seguida, utilize as etiquetas para alterar a vista. Para criar um modo de exibição para um novo tipo de objeto, crie um novo modo de exibição ou use um modo de exibição existente como modelo. As tags são descritas na próxima seção. Em seguida, você pode excluir todos os outros modos de exibição 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 para adicionar o novo arquivo à sua sessão do PowerShell. Se quiser que a sua vista tenha precedência sobre uma vista definida 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 comando Update-FormatData ao seu perfil do PowerShell.

Exemplo: Adicionar 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 cmdlet Get-Culture na sessão atual do PowerShell. Os comandos no exemplo adicionam a propriedade Calendar à exibição de tabela padrão de objetos de cultura.

Para começar, obtenha os dados de formato do ficheiro de código fonte e crie um ficheiro Format.ps1xml que contenha a visualização atual dos objetos culturais.

New-Item -Path $HOME\Format -ItemType Directory -Force

Get-FormatData -TypeName System.Globalization.CultureInfo |
  Export-FormatData -LiteralPath $HOME\Format\CultureInfo.Format.ps1xml

Abra o arquivo CultureInfo.Format.ps1xml em qualquer editor XML ou de texto, como o Visual Studio Code. O XML a seguir define as exibições do objeto CultureInfo.

O arquivo CultureInfo.Format.ps1xml deve se parecer com o exemplo a seguir:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>System.Globalization.CultureInfo</Name>
      <ViewSelectedBy>
        <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 Calendário adicionando um novo conjunto de 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 tags <TableColumnItem> 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 maior do que o arquivo original. Para obter mais informações, consulte Update-FormatData.

Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml

Para testar a alteração, digite Get-Culture e verifique 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 ficheiro Format.ps1xml contém as etiquetas <View> que definem cada exibição. Uma tag <View> típica inclui as seguintes tags:

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

Etiqueta ViewSelectedBy

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

AgruparPor tag

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

TableControlTag

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

Observação

Blocos de script também podem ser usados noutros locais onde resultados calculados podem ser úteis.

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

Tag ListControl

A tag <ListControl> normalmente contém uma tag <ListEntries>. A tag <ListEntries> contém uma tag <ListEntry>. A tag <ListEntry> contém uma tag <ListItems>. A etiqueta <ListItems> contém etiquetas <ListItem>, que contêm etiquetas <PropertyName>. As tags <PropertyName> 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 tags <ListControl> e <ListEntry> também poderão conter uma tag <EntrySelectedBy> que contenha uma ou mais tags <TypeName>. Essas <TypeName> tags especificam o tipo de objeto que a tag <ListControl> pretende exibir.

Tag WideControl

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

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

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

Etiqueta CustomControl

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

Rastreando o uso do arquivo Format.ps1xml

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

Carregamento de Ficheiro de Formato
FormatViewBinding

Para obter mais informações, consulte Trace-Command e 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 mais informações, consulte about_Signing.

XML de exemplo para um modo de exibição personalizado Format-Table

O exemplo XML a seguir cria um modo de exibição Format-Table personalizado para os objetos System.IO.DirectoryInfo e System.IO.FileInfo criados por Get-ChildItem. O modo de exibição personalizado é chamado MyGciView e adiciona a coluna CreationTime à tabela.

Para criar o modo de exibição personalizado, use os cmdlets Get-FormatData e Export-FormatData para gerar um arquivo .ps1xml. Em seguida, edite o arquivo .ps1xml para criar o código para sua exibição personalizada. O arquivo .ps1xml pode ser armazenado em qualquer diretório que o PowerShell possa acessar. Por exemplo, um subdiretório de $HOME.

Depois que o arquivo .ps1xml for criado, use o cmdlet Update-FormatData para incluir a exibição na sessão atual do PowerShell. Ou adicione o comando update ao seu perfil do PowerShell se precisar da exibição disponível em todas as sessões do PowerShell.

Neste exemplo, o modo de exibição personalizado deve usar o formato de tabela, caso contrário, Format-Table falhará.

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