about_Format.ps1xml

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 arquivos para alterar a exibição de objetos ou definir exibições padrão para novos tipos de objeto Format.ps1xml que você cria 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 arquivos para alterar a exibição de objetos ou definir exibições padrão para novos tipos de objeto Format.ps1xml que você cria 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 apenas a exibição. Ele 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 exibições diferentes de cada objeto:

  • Tabela
  • Lista
  • Ampla
  • Personalizado

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

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

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

Criando novos arquivos XML Format.ps1

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

Para criar um Format.ps1xml arquivo para definir uma exibição personalizada, 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 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, em seguida, use as marcas para alterar a 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 modelo. As marcas são descritas na próxima seção. Você pode excluir todas as outras exibições no arquivo para que as alterações sejam óbvias para qualquer pessoa que examina 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 a exibição tenha precedência sobre uma exibição 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 Update-FormatData comando 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 Get-Culture cmdlet na sessão atual do PowerShell. Os comandos no exemplo adicionam a propriedade Calendar à exibição de tabela padrão exibir 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 CultureInfo.Format.ps1xml arquivo em qualquer XML ou editor de texto, como Visual Studio Code. O XML a seguir define as exibições do objeto CultureInfo .

O CultureInfo.Format.ps1xml arquivo deve ser semelhante ao 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 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 calendário nas linhas da tabela usando <TableColumnItem> as <PropertyName marcas e:

<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 posicionar 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 de esquema completa 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 <View> marca típica inclui as seguintes marcas:

  • <Name> Identifica o nome da exibição.
  • <ViewSelectedBy> Especifica o tipo de objeto ou 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.

Marca de ViewSelectedBy

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

Marca GroupBy

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

TableControlTag

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

Observação

Blocos de script também podem ser usados em outros locais em que os resultados calculados podem ser úteis.

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

Marca ListControl

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

Marca de WideControl

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

Marca de CustomControl

A <CustomControl> marca permite que você use um bloco de script para definir um formato. Uma <CustomControl> marca normalmente contém uma <CustomEntries> marca que contém várias <CustomEntry> marcas. 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 as <Text> marcas,, e <Indentation> <ExpressionBinding> <NewLine> .

Rastreando o uso de arquivo XML Format.ps1

Para detectar erros no carregamento ou aplicativo 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-tracename.

Assinando um arquivo XML Format.ps1

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 de XML 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.

Para criar a exibição personalizada, use Get-FormatData os Export-FormatData cmdlets e para gerar um .ps1xml arquivo. Em seguida, .ps1xml edite o 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 .ps1xml o arquivo for criado, use o Update-FormatData cmdlet 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, a exibição personalizada deve usar o formato de tabela; caso contrário, Format-Table falha.

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

Observação

Embora você possa obter o XML de formatação do código-fonte para criar uma exibição personalizada, pode ser necessário mais desenvolvimento para obter o resultado desejado.

No comando a seguir, há uma alternativa para o parâmetro PowerShellVersion para garantir que todas as informações de Get-FormatData formatação local são retornadas. Use -PowerShellVersion $PSVersionTable.PSVersion em vez de uma versão específica do PowerShell.

Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo |
   Export-FormatData -Path ./Mygciview.Format.ps1xml
Update-FormatData -AppendPath ./Mygciview.Format.ps1xml
<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>mygciview</Name>
      <ViewSelectedBy>
        <TypeName>System.IO.DirectoryInfo</TypeName>
        <TypeName>System.IO.FileInfo</TypeName>
      </ViewSelectedBy>
      <GroupBy>
        <PropertyName>PSParentPath</PropertyName>
      </GroupBy>
      <TableControl>
        <TableHeaders>
          <TableColumnHeader>
            <Label>Mode</Label>
            <Width>7</Width>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>LastWriteTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>CreationTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Length</Label>
            <Width>14</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Name</Label>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
        </TableHeaders>
        <TableRowEntries>
          <TableRowEntry>
            <Wrap />
            <TableColumnItems>
              <TableColumnItem>
                <PropertyName>ModeWithoutHardLink</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>LastWriteTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>CreationTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Length</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Name</PropertyName>
              </TableColumnItem>
            </TableColumnItems>
          </TableRowEntry>
        </TableRowEntries>
      </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

Consulte também

Export-FormatData

Get-FormatData

Get-TraceSource

Referência XML de esquema de formato

Trace-Command

Update-FormatData

Escrever um arquivo de formatação do PowerShell