about_Format.ps1xml

Artigo
10/04/2023

Descrição breve

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

A partir do PowerShell 6, as exibições padrão são definidas no código-fonte do PowerShell. Os Format.ps1xml arquivos 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 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 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 somente 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.

Um .ps1xml 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 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 arquivo personalizado Format.ps1xml , um modo de exibição é definido por um conjunto de marcas XML que descrevem o nome do modo de exibição, o tipo de objeto ao qual ele pode ser aplicado, os cabeçalhos de coluna e as propriedades exibidas no corpo do modo de exibição. O formato em Format.ps1xml arquivos é aplicado imediatamente antes dos 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 para 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 Format.ps1xml arquivo para definir um modo de exibição personalizado, use 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 do $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 um modo de exibição existente como um 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 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 comando ao seu perfil do Update-FormatData 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 Get-Culture cmdlet na sessão atual do PowerShell. Os comandos no exemplo adicionam a propriedade Calendar à exibição de tabela padrão de exibição de objetos de cultura.

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

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

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

O CultureInfo.Format.ps1xml arquivo deve se parecer com o 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 adicionando um novo conjunto de <TableColumnHeader> marcas. 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 o Calendário nas linhas da tabela usando as <TableColumnItem> marcas 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 $HOME\Format\CultureInfo.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 modo de exibição. Uma tag típica <View> inclui as seguintes tags:

<Name> Identifica o nome do modo de exibição.
<ViewSelectedBy> Especifica o(s) tipo(s) de objeto ao qual 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 marcas que especificam como cada item será exibido.

Marca ViewSelectedBy

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

Tag GroupBy

A <GroupBy> tag contém uma <PropertyName> tag que especifica a propriedade de 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> tag normalmente contém <TableHeaders> marcas e <TableRowEntries> marcas 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> marcas para cada linha na tabela. A <TableRowEntry> tag contém uma <TableColumnItems> tag que contém uma <TableColumnItem> tag para cada coluna na linha. Normalmente, a <TableColumnItem> tag contém uma <PropertyName> tag que identifica a propriedade object a ser exibida no local definido ou uma tag que contém código <ScriptBlock> 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 lugares em 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.

Tag 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 object 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> marcas e <ListEntry> também poderão conter uma <EntrySelectedBy> marca que contenha uma ou mais <TypeName> marcas. Essas <TypeName> marcas especificam o tipo de objeto que a <ListControl> marca deve exibir.

Tag 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 no modo de exibição. Uma <ScriptBlock> tag especifica um script a ser avaliado e exibido no local especificado no modo de 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> tag contém uma <CustomItem> tag que pode conter uma variedade de tags que especificam o conteúdo e a formatação do local especificado no modo de exibição, incluindo <Text>, <Indentation>, <ExpressionBinding>e <NewLine> tags.

Rastreamento Format.ps1xml uso do arquivo

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 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 uma Format-Table exibição personalizada para os objetos System.IO.DirectoryInfo e System.IO.FileInfo criados pelo 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 Get-FormatData cmdlets e Export-FormatData para gerar um .ps1xml arquivo. Em seguida, edite o .ps1xml arquivo para criar o código para sua exibição personalizada. O .ps1xml arquivo pode ser armazenado em qualquer diretório que o PowerShell possa acessar. Por exemplo, um subdiretório de $HOME.

Depois que o .ps1xml arquivo for criado, use o Update-FormatData cmdlet para incluir o modo de 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.

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