about_Format.ps1xml

Artikel
10/04/2023

Kort beskrivning

Från och med PowerShell 6 definieras standardvyerna för objekt i PowerShell-källkoden.

Du kan skapa egna Format.ps1xml filer för att ändra visning av objekt eller för att definiera standardvisning för nya objekttyper som du skapar i PowerShell.

Lång beskrivning

Från och med PowerShell 6 definieras standardvyerna i PowerShell-källkoden. Filerna Format.ps1xml från PowerShell 5.1 och tidigare versioner finns inte i PowerShell 6 eller senare versioner.

PowerShell-källkoden definierar standardvisningen av objekt i PowerShell-konsolen. Du kan skapa egna Format.ps1xml filer för att ändra visning av objekt eller för att definiera standardvisning för nya objekttyper som du skapar i PowerShell.

När PowerShell visar ett objekt används data i strukturerade formateringsfiler för att fastställa standardvisningen av objektet. Data i formateringsfilerna avgör om objektet återges i en tabell eller i en lista och avgör vilka egenskaper som visas som standard.

Formateringen påverkar endast visningen. Det påverkar inte vilka objektegenskaper som skickas i pipelinen eller hur de skickas. Format.ps1xml filer kan inte användas för att anpassa utdataformatet för hash-tabeller.

En .ps1xml formateringsfil kan definiera fyra olika vyer för varje objekt:

Register
List
Bred
Anpassat

När till exempel utdata från ett Get-ChildItem kommando skickas till ett Format-List kommando Format-List använder listvyn som definierats i källkoden för att avgöra hur fil- och mappobjekten ska visas som en lista.

När en formateringsfil innehåller mer än en vy av ett objekt använder PowerShell den första vyn som hittas.

I en anpassad Format.ps1xml fil definieras en vy av en uppsättning XML-taggar som beskriver namnet på vyn, vilken typ av objekt som den kan tillämpas på, kolumnrubrikerna och egenskaperna som visas i brödtexten i vyn. Formatet i Format.ps1xml filer tillämpas precis innan data visas för användaren.

Skapa nya Format.ps1xml-filer

Om du vill ändra visningsformatet för en befintlig objektvy eller lägga till vyer för nya objekt skapar du egna Format.ps1xml filer och lägger sedan till dem i PowerShell-sessionen.

Om du vill skapa en Format.ps1xml fil för att definiera en anpassad vy använder du cmdletarna Get-FormatData och Export-FormatData . Använd en textredigerare för att redigera filen. Filen kan sparas i valfri katalog som PowerShell kan komma åt, till exempel en underkatalog till $HOME.

Om du vill ändra formateringen för en aktuell vy letar du upp vyn i formateringsfilen och använder sedan taggarna för att ändra vyn. Om du vill skapa en vy för en ny objekttyp skapar du en ny vy eller använder en befintlig vy som modell. Taggarna beskrivs i nästa avsnitt. Du kan sedan ta bort alla andra vyer i filen så att ändringarna är uppenbara för alla som undersöker filen.

När du har sparat ändringarna använder du Update-FormatData för att lägga till den nya filen i PowerShell-sessionen. Om du vill att vyn ska ha företräde framför en vy som definierats i de inbyggda filerna använder du parametern PrependPath . Update-FormatData påverkar endast den aktuella sessionen. Om du vill göra ändringen i alla framtida sessioner lägger du till kommandot i Update-FormatData din PowerShell-profil.

Exempel: Lägga till kalenderdata i kulturobjekt

Det här exemplet visar hur du ändrar formateringen för kulturobjekten System.Globalization.CultureInfo som genereras av cmdleten Get-Culture i den aktuella PowerShell-sessionen. Kommandona i exemplet lägger till egenskapen Kalender i standardtabellvyns visning av kulturobjekt.

Börja med att hämta formatdata från källkodsfilen och skapa en Format.ps1xml fil som innehåller den aktuella vyn av kulturobjekten.

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

CultureInfo.Format.ps1xml Öppna filen i valfri XML- eller textredigerare, till exempel Visual Studio Code. Följande XML definierar vyerna för CultureInfo-objektet .

Filen CultureInfo.Format.ps1xml bör se ut som följande exempel:

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

Skapa en ny kolumn för egenskapen Kalender genom att lägga till en ny uppsättning <TableColumnHeader> taggar. Värdet för egenskapen Kalender kan vara långt, så ange ett värde på 45 tecken som <Width>.

<TableHeaders>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>45</Width>
  </TableColumnHeader>
  <TableColumnHeader/>
</TableHeaders>

Lägg till ett nytt kolumnobjekt för Kalender i tabellraderna med hjälp av taggarna <TableColumnItem> och <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>

Spara och stäng filen. Använd Update-FormatData för att lägga till den nya formatfilen i den aktuella PowerShell-sessionen.

I det här exemplet används parametern PrependPath för att placera den nya filen i högre prioritetsordning än den ursprungliga filen. Mer information finns i Update-FormatData.

Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml

Om du vill testa ändringen skriver Get-Culture och granskar du utdata som innehåller egenskapen Kalender .

Get-Culture

LCID  Name   Calendar                                DisplayName
----  ----   --------                                -----------
1033  en-US  System.Globalization.GregorianCalendar  English (United States)

XML-filen i Format.ps1xml-filer

Den fullständiga schemadefinitionen finns i Format.xsd i PowerShell-källkodslagringsplatsen på GitHub.

Avsnittet ViewDefinitions för varje Format.ps1xml fil innehåller taggarna <View> som definierar varje vy. En typisk <View> tagg innehåller följande taggar:

<Name> identifierar namnet på vyn.
<ViewSelectedBy> anger den objekttyp eller de typer som vyn gäller för.
<GroupBy> anger hur objekt i vyn ska kombineras i grupper.
<TableControl>, <ListControl>, <WideControl>och <CustomControl> innehåller taggarna som anger hur varje objekt ska visas.

ViewSelectedBy-tagg

Taggen <ViewSelectedBy> kan innehålla en <TypeName> tagg för varje objekttyp som vyn gäller för. Eller så kan den innehålla en <SelectionSetName> tagg som refererar till en markeringsuppsättning som definieras någon annanstans med hjälp av en <SelectionSet> tagg.

GroupBy-tagg

Taggen <GroupBy> innehåller en <PropertyName> tagg som anger objektegenskapen som objekt ska grupperas efter. Den innehåller också antingen en <Label> tagg som anger en sträng som ska användas som en etikett för varje grupp eller en <CustomControlName> tagg som refererar till en anpassad kontroll som definierats någon annanstans med hjälp av en <Control> tagg. Taggen <Control> innehåller en <Name> tagg och en <CustomControl> tagg.

TableControlTag

Taggen <TableControl> innehåller <TableHeaders> vanligtvis taggar och <TableRowEntries> taggar som definierar formateringen för tabellens huvuden och rader. Taggen <TableHeaders> innehåller <TableColumnHeader> vanligtvis taggar som innehåller <Label>, <Width>och <Alignment> taggar. Taggen <TableRowEntries> innehåller <TableRowEntry> taggar för varje rad i tabellen. Taggen <TableRowEntry> innehåller en <TableColumnItems> tagg som innehåller en <TableColumnItem> tagg för varje kolumn i raden. Taggen <TableColumnItem> innehåller vanligtvis antingen en <PropertyName> tagg som identifierar objektegenskapen som ska visas på den definierade platsen eller en <ScriptBlock> tagg som innehåller skriptkod som beräknar ett resultat som ska visas på platsen.

Kommentar

Skriptblock kan också användas någon annanstans på platser där beräknade resultat kan vara användbara.

Taggen <TableColumnItem> kan också innehålla en <FormatString> tagg som anger hur egenskapen eller de beräknade resultaten ska visas.

ListControl-tagg

Taggen <ListControl> innehåller vanligtvis en <ListEntries> tagg. Taggen <ListEntries> innehåller en <ListEntry> tagg. Taggen <ListEntry> innehåller en <ListItems> tagg. Taggen <ListItems> innehåller <ListItem> taggar som innehåller <PropertyName> taggar. Taggarna <PropertyName> anger den objektegenskap som ska visas på den angivna platsen i listan. Om visningsmarkeringen definieras med hjälp av en markeringsuppsättning kan taggarna <ListControl> och <ListEntry> även innehålla en <EntrySelectedBy> tagg som innehåller en eller flera <TypeName> taggar. De här <TypeName> taggarna anger den objekttyp som taggen <ListControl> är avsedd att visa.

WideControl-tagg

Taggen <WideControl> innehåller vanligtvis en <WideEntries> tagg. Taggen <WideEntries> innehåller en eller flera <WideEntry> taggar. En <WideEntry> tagg innehåller en <WideItem> tagg.

En <WideItem> tagg måste innehålla antingen en <PropertyName> tagg eller en <ScriptBlock> tagg. En <PropertyName> tagg anger den egenskap som ska visas på den angivna platsen i vyn. En <ScriptBlock> tagg anger ett skript som ska utvärderas och visas på den angivna platsen i vyn.

En <WideItem> tagg kan innehålla en <FormatString> tagg som anger hur egenskapen ska visas.

CustomControl-tagg

Med <CustomControl> taggen kan du använda ett skriptblock för att definiera ett format. En <CustomControl> tagg innehåller vanligtvis en <CustomEntries> tagg som innehåller flera <CustomEntry> taggar. Varje <CustomEntry> tagg innehåller en <CustomItem> tagg som kan innehålla en mängd olika taggar som anger innehåll och formatering för den angivna platsen i vyn, inklusive <Text>, <Indentation>, <ExpressionBinding>och <NewLine> taggar.

Tracing Format.ps1xml-filanvändning

Om du vill identifiera fel vid inläsning eller program av Format.ps1xml filer använder du cmdleten Trace-Command med någon av följande formatkomponenter som värdet för parametern Namn :

FormatFileLoading
FormatViewBinding

Mer information finns i Trace-Command och Get-TraceSource.

Signera en Format.ps1xml-fil

Om du vill skydda användarna av filen Format.ps1xml signerar du filen med en digital signatur. Mer information finns i about_Signing.

Exempel-XML för en anpassad vy för Format-Table

Följande XML-exempel skapar en Format-Table anpassad vy för System.IO.DirectoryInfo- och System.IO.FileInfo-objekt som skapats av Get-ChildItem. Den anpassade vyn heter mygciview och lägger till kolumnen CreationTime i tabellen.

Om du vill skapa den anpassade vyn använder du Get-FormatData cmdletarna och Export-FormatData för att generera en .ps1xml fil. .ps1xml Redigera sedan filen för att skapa koden för den anpassade vyn. Filen .ps1xml kan lagras i valfri katalog som PowerShell kan komma åt. Till exempel en underkatalog till $HOME.

.ps1xml När filen har skapats använder du cmdleten Update-FormatData för att inkludera vyn i den aktuella PowerShell-sessionen. Du kan också lägga till uppdateringskommandot i PowerShell-profilen om du behöver vyn tillgänglig i alla PowerShell-sessioner.

I det här exemplet måste den anpassade vyn använda tabellformatet, annars Format-Table misslyckas.

Använd Format-Table med parametern Visa för att ange den anpassade vyns namn, mygciview och formatera tabellens utdata med kolumnen CreationTime . Ett exempel på hur kommandot körs finns i Format-Table.