about_Format.ps1xml
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0
TÓPICO
about_Format.ps1xml
DESCRIÇÃO BREVE
Os arquivos Format.ps1xml em Windows PowerShell® definem a exibição padrão de objetos no console do Windows 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 objetos que você cria no Windows PowerShell.
DESCRIÇÃO LONGA
Os arquivos Format.ps1xml em Windows PowerShell definem a exibição padrão de objetos no Windows 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 objetos que você cria no Windows PowerShell.
Quando o Windows PowerShell exibe um objeto, ele usa os dados de 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 é processado 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. Ela não afeta quais propriedades do objeto são passadas pelo pipeline ou como elas são passadas. Arquivos Format.ps1xml não podem ser usados para personalizar o formato de saída para tabelas de hash.
Windows 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:
Certificate.Format.ps1xml
Objetos no repositório de certificados, como certificados X.509 e armazenamentos de certificados.
DotNetTypes.Format.ps1xml
Outros tipos do .NET Framework, como objetos CultureInfo, FileVersionInfo e EventLogEntry.
FileSystem.Format.ps1xml
Objetos do sistema de arquivos, como arquivos e diretórios.
Help.Format.ps1xml
Modos de exibição de ajuda, como exibições detalhadas e completas, parâmetros e exemplos.
PowerShellCore.format.ps1xml
Objetos gerados pelos cmdlets principais do Windows PowerShell, como Get-Member e Get-History.
PowerShellTrace.format.ps1xml
Objetos de rastreamento, como os gerados pelo cmdlet do Trace-Command.
Registry.format.ps1xml
Objetos de Registro, como chaves e entradas.
Um arquivo de formatação pode definir quatro exibições diferentes de cada objeto: tabela, lista, todo e 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 no arquivo FileSystem.format.ps1xml 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 Windows PowerShell aplica a primeira exibição que encontrar.
Em um arquivo Format.ps1xml, uma exibição é definida por um conjunto de marcas XML que descrevem o nome da exibição, o tipo de objeto para o qual ela pode ser aplicada, os cabeçalhos de coluna e as propriedades que são exibidas no corpo da exibição. O formato de arquivos Format.ps1xml é aplicado antes de os dados serem apresentados ao usuário.
Criação de novos arquivos Format.ps1xml
Os arquivos .ps1xml instalados com Windows PowerShell são assinados digitalmente para evitar a violação porque a formatação pode incluir blocos de script. Portanto, para alterar o formato de exibição de uma exibição de objetos existentes ou adicionar exibições para novos objetos, crie seus próprios arquivos Format.ps1xml e, em seguida, adicione-os à sua sessão do Windows PowerShell.
Para criar um novo arquivo, copie um arquivo Format.ps1xml existente. O novo arquivo pode ter qualquer nome, mas ele deve ter uma extensão de nome de arquivo .ps1xml. Você pode colocar o novo arquivo em qualquer diretório que seja acessível a Windows PowerShell, mas é útil colocar os arquivos no diretório de instalação do Windows 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 a exibição no arquivo de formatação e, em seguida, use as marcas para alterar o modo de exibição. Para criar um modo de exibição para um novo tipo de objeto, crie uma nova exibição ou use uma exibição existente como um modelo. (As marcas são descritas na próxima seção deste tópico.) Você pode excluir todas as outras exibições no arquivo de forma que as alterações sejam óbvias para qualquer pessoa que examinar o arquivo.
Quando você salvar as alterações, use o cmdlet Update-FormatData para adicionar o novo arquivo na sessão do Windows PowerShell. Se você quiser que a exibição tenha precedência sobre uma exibição definida nos arquivos internos, use o parâmetro PrependData de Update-FormatData. Update-FormatData afeta apenas a sessão atual. Para fazer a alteração em todas as futuras sessões, adicione o comando Update-FormatData ao seu perfil do Windows 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 cmdlet Get-Culture. Os comandos no exemplo adicionam a propriedade de calendário na exibição do modo de exibição de tabela padrão de objetos de cultura.
A primeira etapa é encontrar o arquivo Format.ps1xml que contém a exibição atual dos objetos de cultura. O comando Select-String a seguir localiza o arquivo:
select-string -path $pshome\*format.ps1xml `
-pattern System.Globalization.CultureInfo
Esse comando revela que a definição é no arquivo DotNetTypes.Format.ps1xml.
O próximo comando copia o conteúdo do arquivo em um novo arquivo, MyDotNetTypes.Format.ps1xml.
copy-item DotNetTypes.Format.ps1xml MyDotNetTypes.Format.ps1xml
Em seguida, abra o arquivo MyDotNetTypes.Format.ps1xml em qualquer editor de texto ou XML, como o Bloco de notas. Localize a seção de objeto System.Globalization.CultureInfo. O XML a seguir define os modos de exibição do objeto CultureInfo. O objeto tem apenas um modo de 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>
<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 marcas de abertura <?XML>, <Configuration> e <ViewDefinitions> e marcas <ViewDefintions> e <Configuration>. Você também deve excluir a assinatura digital sempre que você alterar o arquivo.
<?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>
Em seguida, crie uma nova coluna para a propriedade de calendário, adicionando um novo conjunto de marcas <TableColumnHeader>. O valor da propriedade de calendário pode ser longo, portanto, um valor de 45 caracteres é usado da seguinte maneira:
<TableControl>
<TableHeaders>
<TableColumnHeader>
<Width>16</Width>
</TableColumnHeader>
<TableColumnHeader>
<Width>16</Width>
</TableColumnHeader>
<TableColumnHeader>
<Width>45</Width>
</TableColumnHeader>
<TableColumnHeader/>
</TableHeaders>
Agora, adicione um novo item de coluna nas linhas de tabela, da seguinte maneira:
<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>
Depois de salvá-lo e fechá-lo, use um comando Update-FormatData, como o comando a seguir, para adicionar o novo arquivo de formato na sessão atual. O comando usa o parâmetro PrependData para colocar o novo arquivo em uma ordem de precedência mais alta que o arquivo original. (Para obter mais informações sobre Update-FormatData, digite "get-help update-formatdata").
update-formatdata -prependpath $pshome\MyDotNetTypes.format.ps1xml
Para testar a alteração, digite "get-culture" e, em seguida, examine a saída, que inclui a propriedade de calendário.
C:\PS> get-culture
LCID Name Calendar DisplayName
---- ---- -------- -----------
1033 en-US System.Globalization.GregorianCalendar English (United States)
O XML nos arquivos Format.ps1xml
A seção ViewDefinitions de cada arquivo Format.ps1xml contém as marcas <View> que definem cada modo de exibição. Uma marca <View> típica inclui as seguintes marcas:
<Nome>
A marca <Name> identifica o nome da exibição.
<ViewSelectedBy>
A marca <ViewSelectedBy> especifica o tipo de objeto ou tipos aos quais se aplica o modo de exibição.
<GroupBy>
A marca <GroupBy> especifica como os itens na exibição serão combinados em grupos.
<TableControl>
<ListControl>
<WideControl>
<CustomControl>
Essas marcas contêm as marcas que especificam h<DefaultDisplayProperty>ow cada item que será exibido.
A marca <ViewSelectedBy> pode conter uma marca <TypeName> para cada tipo de objeto ao qual se aplica o modo de exibição. Ou ela pode conter uma marca <SelectionSetName> que faz referência a um conjunto de seleção definido em outro local, usando uma marca <SelectionSet>.
A marca <GroupBy> contém uma marca <PropertyName> especifica a propriedade do objeto pela qual os itens devem ser agrupados. Ela também contém uma marca <Label> que especifica uma cadeia de caracteres a ser usada como um rótulo para cada grupo ou uma marca <CustomControlName> que faz referência a um controle personalizado definido em outro local usando uma marca <Control>. A marca <Control> contém uma marca <Name> e uma marca <CustomControl>.
A marca <TableControl> normalmente contém as marcas <TableHeaders> e <TableRowEntries> que definem a formatação de cabeçalhos e linhas da tabela. A marca <TableHeaders> normalmente contém as marcas <TableColumnHeader> que contêm as marcas <Label>, <Width> e <Alignment>. A marca <TableRowEntries> contém as marcas <TableRowEntry> para cada linha na tabela. A marca <TableRowEntry> contém uma marca <TableColumnItems> que contém uma marca <TableColumnItem> para cada coluna na linha. Normalmente, a marca <TableColumnItem> contém uma marca <PropertyName> que identifica a propriedade do objeto a ser exibido no local definido, ou uma marca <ScriptBlock> que contém o código de script que calcula um resultado que será exibido no local.
Observação: Blocos de script também podem ser usados em outros locais onde os resultados calculados podem ser úteis.
A marca <TableColumnItem> também pode conter uma marca <FormatString> especifica como a propriedade ou os resultados calculados serão exibidos.
A marca <ListControl> normalmente contém uma marca <ListEntries>. A marca <ListEntries> contém uma marca <ListItems>. A marca <ListItems> contém as marcas <ListItem>, que contêm as marcas <PropertyName>. As marcas <PropertyName> especificam a propriedade do objeto a ser exibido no local especificado na lista. Se a seleção de exibição é definida usando um conjunto de seleção, a marca <ListControl> também pode conter uma marca <EntrySelectedBy> que contém uma ou mais marcas <TypeName>. Essas marcas <TypeName> especificam o tipo de objeto que a marca <ListControl> é destinada a exibir.
A marca <WideControl> normalmente contém uma marca <WideEntries>. A marca <WideEntries> contém uma ou mais marcas <WideEntry>. A marca <WideEntry> normalmente contém uma marca <PropertyName> que especifica a propriedade a ser exibida no local especificado no modo de exibição. A marca <PropertyName> pode conter uma marca <FormatString> que especifica como a propriedade será exibida.
A marca <CustomControl> permite que você use um bloco de script para definir um formato. Uma marca <CustomControl> normalmente contém uma marca <CustomEntries> que contém várias marcas <CustomEntry>. Cada marca <CustomEntry> contém uma marca <CustomItem> que pode conter uma variedade de marcas que especificam o conteúdo e a formatação do local especificado no modo de exibição, incluindo as marcas <Text>, <Indentation>, <ExpressionBinding> e <NewLine>.
Update-FormatData
Para carregar os arquivos Format.ps1xml em uma sessão do Windows PowerShell, o cmdlet Update-FormatData. Se você quiser que as exibições em seu arquivo tenham precedência sobre as exibições no arquivo Format.ps1xml interno, use o parâmetro PrependData de Update-FormatData. Update-FormatData afeta apenas a sessão atual. Para fazer a alteração em todas as futuras sessões, adicione o comando Update-FormatData ao seu perfil do Windows PowerShell.
Exibições padrão em Types.ps1xml
As exibições padrão de alguns tipos de objetos básicos são definidas no arquivo Types.ps1xml no diretório $pshome. Os nós são nomeados PsStandardMembers, e os subnós usam uma das seguintes marcas:
<DefaultDisplayProperty>
<DefaultDisplayPropertySet>
<DefaultKeyPropertySet>
Para obter mais informações, digite o seguinte comando:
get-help about_types.ps1xml
Rastreando uso do arquivo Format.ps1xml
Para detectar erros no carregamento ou aplicação dos arquivos Format.ps1xml, use o cmdlet Trace-Command com qualquer um dos seguintes componentes de formato como o valor do parâmetro Name:
FormatFileLoading
UpdateFormatData
FormatViewBinding
Para obter mais informações, digite os seguintes comandos:
get-help trace-command
get-help get-tracesource
Assinando um arquivo Format.ps1xml
Para proteger os usuários de seu arquivo Format.ps1xml, assine o arquivo usando uma assinatura digital. Para obter mais informações, digite:
get-help about_signing
CONSULTE TAMBÉM
Update-FormatData
Trace-Command
Get-TraceSource