about_Format.ps1xml

Descrição curta

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 Format.ps1xml para alterar a exibição de objetos ou 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 Format.ps1xml 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 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 determina quais propriedades são exibidas por padrão.

A formatação afeta somente a exibição. Isso não afeta quais propriedades do objeto são passadas pelo 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 exibições diferentes de cada objeto:

Tabela
Lista
Largo
Personalizado

Por exemplo, quando a saída de um comando Get-ChildItem é canalizada para um comando Format-List, Format-List usa a exibição de lista definida 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 uma exibição de um objeto, o PowerShell aplica a primeira exibição encontrada.

Em um arquivo Format.ps1xml personalizado, uma exibição é definida por um conjunto de marcas XML que especificam o nome da exibição, o tipo de objeto a que pode ser aplicado, 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

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

Para definir uma exibição personalizada, crie um arquivo Format.ps1xml usando os cmdlets Get-FormatData e 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 de $HOME.

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 um modo de exibição para um novo tipo de objeto, crie um novo modo de exibição ou use uma exibição existente como modelo. As marcações 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 para adicionar o novo arquivo à sessão do PowerShell. Se você quiser que sua visualização tenha precedência sobre uma 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 arquivo de código-fonte e crie um arquivo Format.ps1xml que contenha a exibição atual dos objetos de cultura.

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 de texto ou XML, como o Visual Studio Code. O XML a seguir define as exibições do objeto CultureInfo.

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

<?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 Calendar ao adicionar um novo conjunto de tags <TableColumnHeader>. 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 Calendar 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 analise 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 arquivo Format.ps1xml contém as tags de <View> que definem cada exibição. Uma etiqueta de <View> típica inclui as seguintes etiquetas:

<Name> identifica o nome da exibição.
<ViewSelectedBy> especifica o tipo de objeto ou os tipos 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 marcas que especificam como cada item será exibido.

Etiqueta "ViewSelectedBy"

A marca <ViewSelectedBy> pode conter uma marca de <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>.

Marcação GroupBy

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

TableControlTag

A marca <TableControl> normalmente contém marcas <TableHeaders> e <TableRowEntries> que definem a formatação para as linhas e as cabeças da tabela. A tag <TableHeaders> normalmente contém tags <TableColumnHeader> que contêm as tags <Label>, <Width>e <Alignment>. A tag <TableRowEntries> contém tags <TableRowEntry> para cada linha na tabela. A marcação <TableRowEntry> contém uma marcação <TableColumnItems> que contém uma marcação <TableColumnItem> para cada coluna na 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 de <ScriptBlock> que contém código de script que calcula um resultado que deve ser exibido no local.

Nota

Os scriptblocks também podem ser usados em outros locais em que os resultados calculados podem ser úteis.

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

Marcação ListControl

A etiqueta <ListControl> normalmente contém uma etiqueta <ListEntries>. A tag <ListEntries> contém uma tag <ListEntry>. A tag <ListEntry> contém uma tag <ListItems>. A marcação <ListItems> contém marcações <ListItem>, que contêm marcações <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 usando um conjunto de seleção, as marcas <ListControl> e <ListEntry> também poderão conter uma marca de <EntrySelectedBy> que contém uma ou mais marcas de <TypeName>. Essas marcas <TypeName> especificam o tipo de objeto que a marca <ListControl> destina-se a exibir.

Etiqueta WideControl

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

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

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

Etiqueta CustomControl

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

Uso do arquivo Tracing Format.ps1xml

Para detectar erros no carregamento ou 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
FormatViewBinding

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

Assinando um arquivo Format.ps1xml

Para proteger os usuários do arquivo Format.ps1xml, 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 XML a seguir cria uma exibição personalizada Format-Table para os objetos System.IO.DirectoryInfo e System.IO.FileInfo criados por Get-ChildItem. A exibição personalizada é nomeada MyGciView e adiciona a coluna CreationTime à tabela.

Para criar a exibição personalizada, use os cmdlets Get-FormatData e Export-FormatData para gerar um arquivo .ps1xml. Em seguida, edite seu arquivo de .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 o modo de exibição na sessão atual do PowerShell. Ou adicione o comando de atualização ao seu perfil do PowerShell se você precisar da exibição disponível em todas as sessões do PowerShell.

Para este exemplo, a vista 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, MyGciView e formatar a saída da tabela com a coluna CreationTime. Para obter um exemplo de como o comando é executado, consulte Format-Table.