TÓPICO
about_Format.ps1xml
DESCRIÇÃO RESUMIDA
Os arquivos Format.ps1xml no 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 para definir exibições padrão de novos
tipos de objeto criados no Windows PowerShell.
DESCRIÇÃO LONGA
Os arquivos Format.ps1xml no 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 para definir exibições padrão de novos tipos de objeto
criados no Windows PowerShell.
Quando o Windows 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.
Determinam também quais propriedades são exibidas por padrão.
A formatação afeta somente a exibição. Não afeta quais
propriedades do objeto são passadas pelo pipeline ou como são
passadas.
O 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 repositórios 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
Exibições de ajuda, como exibições detalhadas e
completas, parâmetros e exemplos.
PowerShellCore.format.ps1xml
Objetos gerados pelos principais cmdlets do Windows
PowerShell, como Get-Member e Get-History.
PowerShellTrace.format.ps1xml
Objetos de rastreamento, como os gerados pelo cmdlet
Trace-Command.
Registry.format.ps1xml
Objetos do Registro, como chaves e entradas.
Um arquivo de formatação pode definir quatro exibições diferentes
de cada objeto: tabela, lista, largo e complexo. Por exemplo,
quando a saída de um comando Get-ChildItem é canalizada para um
comando Format-List, Format-List usa a exibição no arquivo
FileSystem.format.ps1xml para determinar como exibir os objetos
de arquivo e pasta como uma lista.
Em um arquivo Format.ps1xml, uma exibição é definida por um
conjunto de marcas XML que descreve o nome da exibição, o tipo de
objeto ao qual ela pode ser aplicada, 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
Os arquivos .ps1xml instalados com o Windows PowerShell são
assinados digitalmente para impedir falsificação, pois a
formatação pode incluir blocos de script. Portanto, para
alterar o formato de exibição de uma exibição de objeto
existente ou adicionar exibições para novos objetos, crie seus
próprios arquivos Format.ps1xml e 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 deve ter
a extensão de nome de arquivo .ps1xml. Você pode colocar o novo
arquivo em qualquer diretório acessível ao 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 uma exibição atual, localize a
exibição no arquivo de formatação e use as marcas para alterar
a exibição. Para criar uma 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 modo que as alterações sejam óbvias para qualquer pessoa que
examine o arquivo.
Depois de salvar as alterações, use o cmdlet Update-FormatData
para adicionar o novo arquivo à sua sessão do Windows
PowerShell. Se desejar que sua exibição tenha precedência sobre
outra definida nos arquivos internos, use o parâmetro
PrependData do cmdlet Update-FormatData. Update-FormatData
afeta somente a sessão atual. Para fazer a alteração para todas
as sessões futuras, adicione o comando Update-FormatData a seu
perfil do Windows PowerShell.
Exemplo: adicionar dados do calendário a objetos de cultura
Esse 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 calendar à
exibição da tabela padrão de objetos de cultura.
A primeira etapa é localizar 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 está no arquivo
DotNetTypes.Format.ps1xml.
O próximo comando copia o conteúdo do arquivo para 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 XML ou de texto, como o Bloco de Notas.
Localize a seção de objeto System.Globalization.CultureInfo. O
XML a seguir define as exibições do objeto CultureInfo.
O objeto tem apenas uma 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 <?XML>,
<Configuration> e <ViewDefinitions> de abertura e as marcas
<ViewDefintions> e <Configuration> de fechamento. Você também
precisa excluir a
assinatura digital sempre que 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 Calendar
adicionando um novo conjunto de marcas <TableColumnHeader>. O
valor da propriedade Calendar pode ser long, para que seja usado
um valor de 45 caracteres, da seguinte forma:
<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 da tabela, da
seguinte forma:
<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 salvar o arquivo e fechá-lo, use um comando
Update-FormatData, como o mostrado a seguir, para adicionar o
novo arquivo de formato à sessão atual. O comando usa o
parâmetro PrependData para colocar o novo arquivo em uma ordem
de precedência mais alta que a do 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 examine a
saída, que inclui a propriedade Calendar.
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 exibição. Uma marca <View>
típica inclui as seguintes marcas:
<Name>
Uma marca <Name> identifica o nome da exibição.
<ViewSelectedBy>
A marca <ViewSelectedBy> especifica o(s) tipo(s) de
objeto ao(s)qual(ais) a exibição se aplica.
<GroupBy>
Uma marca <GroupBy> especifica como os itens na
exibição serão combinados em grupos.
<TableControl>
<ListControl>
<WideControl>
<ComplexControl>
Essas marcas contêm as marcas que especificam como cada
item será exibido.
A marca <ViewSelectedBy> pode conter uma marca <TypeName> para
cada tipo de objeto ao qual a exibição se aplica. Ou contém uma
marca <SelectionSetName> que faz referência a um conjunto de
seleção definido em outro lugar com o uso de uma marca
<SelectionSet>.
A marca <GroupBy> contém uma marca <PropertyName> que
especifica a propriedade do objeto pela qual os itens serão
agrupados. 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 <ComplexControlName> que faz referência a um
controle complexo definido em outro lugar com o uso de uma
marca <Control>. A marca <Control> contém uma marca <Name> e
uma marca <ComplexControl>.
A marca <TableControl> normalmente contém marcas <TableHeaders> e
<TableRowEntries> que definem a formatação para os títulos e as
linhas da tabela. A marca <TableHeaders> normalmente contém marcas
<TableColumnHeader> que contêm marcas <Label>, <Width> e <Alignment>.
A marca <TableRowEntries> contém marcas <TableRowEntry> para cada
linha na tabela. A marca <TableRowEntry> contém uma marca
<TableColumnItems> que contém uma marca <TableColumnItem> para cada
coluna da 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 <ScriptBlock> que contém
o código de script que calcula um resultado a ser exibido no local.
Observação: blocos de script também podem ser usados em outros
locais onde resultados calculados podem ser úteis.
A marca <TableColumnItem> também pode conter uma marca
<FormatString> que 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 marcas <ListItem>, que
contêm marcas <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
com o uso de um conjunto de seleção, a marca <ListControl>
também poderá conter uma marca <EntrySelectedBy>, que, por sua
vez, contém uma ou mais marcas <TypeName>. Essas marcas
<TypeName> especificam o tipo de objeto que a marca
<ListControl> deve exibir.
A marca <WideControl> normalmente contém uma marca
<WideEntries>. A marca <WideEntries> contém uma ou mais marcas
<WideEntry>. Uma marca <WideEntry> normalmente contém uma marca
<PropertyName> que especifica a propriedade a ser exibida no
local especificado na exibição. A marca <PropertyName> pode
conter uma marca <FormatString> que especifica como a
propriedade deve ser exibida.
A marca <ComplexControl> contém combinações mais complexas de
marcas que outros tipos de exibição. Uma marca <ComplexControl>
normalmente contém uma marca <ComplexEntries>. Uma marca
<ComplexEntries> contém várias marcas <ComplexEntry>. Uma marca
<ComplexEntry> normalmente contém uma marca <ComplexItem>. Essa
marca, por sua vez, pode conter várias marcas que especificam o
conteúdo e a formatação para o local especificado na exibição,
incluindo marcas <Text>, <Indentation>, <ExpressionBinding> e
<NewLine>.
Update-FormatData
Para carregar seus arquivos Format.ps1xml em uma sessão do
Windows PowerShell, use o cmdlet Update-FormatData. Se quiser
que as exibições no seu arquivo tenham precedência sobre as do
arquivo Format.ps1xml interno, use o parâmetro PrependData de
Update-FormatData. Update-FormatData afeta somente a sessão
atual. Para fazer a alteração para todas as sessões futuras,
adicione o comando Update-FormatData a seu perfil do Windows
PowerShell.
Exibições padrão em Types.ps1xml
As exibições padrão de alguns tipos de objeto básicos são
definidas no arquivo Types.ps1xml no diretório $pshome. Os nós são
PsStandardMembers nomeados, e o 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 o uso do arquivo Format.ps1xml
Para detectar erros no carregamento ou na 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
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 do seu arquivo Format.ps1xml, assine
o arquivo usando uma assinatura digital. Para obter
informações, digite:
get-help about_signing
CONSULTE TAMBÉM
Update-FormatData
Trace-Command
Get-TraceSource