about_Format.ps1xml

Krátký popis

Počínaje PowerShellem 6 se výchozí zobrazení objektů definují ve zdrojovém kódu PowerShellu.

Můžete vytvořit vlastní soubory Format.ps1xml a změnit zobrazení objektů nebo definovat výchozí zobrazení pro nové typy objektů, které vytvoříte v PowerShellu.

Dlouhý popis

Počínaje PowerShellem 6 se výchozí zobrazení definují ve zdrojovém kódu PowerShellu. Soubory Format.ps1xml z PowerShellu 5.1 a starších verzí v PowerShellu 6 a novějších verzích neexistují.

Zdrojový kód PowerShellu definuje výchozí zobrazení objektů v konzole PowerShellu. Můžete vytvořit vlastní soubory Format.ps1xml a změnit zobrazení objektů nebo definovat výchozí zobrazení pro nové typy objektů, které vytvoříte v PowerShellu.

Když PowerShell zobrazí objekt, použije data v souborech strukturovaného formátování k určení výchozího zobrazení objektu. Data v souborech formátování určují, zda se objekt vykresluje v tabulce nebo v seznamu, a určuje, které vlastnosti se ve výchozím nastavení zobrazují.

Formátování ovlivní jenom zobrazení. Nemá vliv na to, které vlastnosti objektu se předávají potrubím nebo jak se předávají. Format.ps1xml soubory nelze použít k přizpůsobení výstupního formátu pro tabulky hash.

Soubor formátování .ps1xml může definovat čtyři různá zobrazení každého objektu:

Stůl
Seznam
Široký
Zakázkový

Když je například výstup příkazu Get-ChildItem předaný do Format-List příkazu, Format-List použije zobrazení seznamu definované ve zdrojovém kódu k určení, jak zobrazit objekty souborů a složek jako seznam.

Pokud formátovací soubor obsahuje více než jedno zobrazení objektu, Použije PowerShell první zobrazení, které najde.

Ve vlastním souboru Format.ps1xml je zobrazení definováno sadou značek XML popisující název zobrazení, typ objektu, na který se dá použít, záhlaví sloupců a vlastnosti zobrazené v textu zobrazení. Formát v Format.ps1xml souborech se použije těsně před zobrazením dat uživateli.

Vytváření nových souborů Format.ps1xml

Pokud chcete změnit formát zobrazení existujícího zobrazení objektů nebo přidat zobrazení pro nové objekty, vytvořte vlastní Format.ps1xml soubory a pak je přidejte do relace PowerShellu.

Pokud chcete vytvořit soubor Format.ps1xml pro definování vlastního zobrazení, použijte rutiny Get-FormatData a Export-FormatData. K úpravě souboru použijte textový editor. Soubor lze uložit do libovolného adresáře, ke kterému má PowerShell přístup, například do podadresáře $HOME.

Pokud chcete změnit formátování aktuálního zobrazení, vyhledejte zobrazení v souboru formátování a pak pomocí značek změňte zobrazení. Pokud chcete vytvořit zobrazení pro nový typ objektu, vytvořte nové zobrazení nebo použijte existující zobrazení jako model. Značky jsou popsány v další části. Pak můžete odstranit všechna ostatní zobrazení v souboru, aby změny byly zřejmé pro každého, kdo soubor zkoumá.

Po uložení změn pomocí Update-FormatData přidejte nový soubor do relace PowerShellu. Pokud chcete, aby vaše zobrazení mělo přednost před zobrazením definovaným v předdefinovaných souborech, použijte parametr PrependPath. Update-FormatData ovlivňuje pouze aktuální relaci. Pokud chcete provést změnu všech budoucích relací, přidejte do profilu PowerShellu příkaz Update-FormatData.

Příklad: Přidání dat kalendáře do objektů kultury

Tento příklad ukazuje, jak změnit formátování objektů jazykové verze System.Globalization.CultureInfo generovaných cmdletem Get-Culture v aktuální PowerShell relaci. Příkazy v příkladu přidávají vlastnost Kalendář do výchozího zobrazení tabulky objektů dané jazykové oblasti.

Nejprve získejte data formátu ze souboru zdrojového kódu a vytvořte soubor Format.ps1xml, který obsahuje aktuální zobrazení kulturních objektů.

New-Item -Path $HOME\Format -ItemType Directory -Force

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

Otevřete soubor CultureInfo.Format.ps1xml v libovolném XML nebo textovém editoru, například v editoru Visual Studio Code. Následující XML definuje zobrazení CultureInfo objektu.

Soubor CultureInfo.Format.ps1xml by měl vypadat jako v následující ukázce:

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

Vytvořte nový sloupec pro vlastnost Kalendář tím, že přidáte novou sadu značek <TableColumnHeader>. Hodnota vlastnosti Calendar může být dlouhá, proto zadejte hodnotu 45 znaků jako <Width>.

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

Přidejte novou položku sloupce pro Kalendář v řádcích tabulky pomocí značek <TableColumnItem> a <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>

Uložte a zavřete soubor. Pomocí Update-FormatData přidejte nový formátový soubor do aktuální relace PowerShellu.

Tento příklad používá parametr PrependPath k umístění nového souboru do vyššího pořadí priorit než původní soubor. Další informace naleznete v tématu Update-FormatData.

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

Pokud chcete změnu otestovat, zadejte Get-Culture a zkontrolujte výstup, který obsahuje vlastnost Kalendář.

Get-Culture

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

Xml v souborech Format.ps1xml

Úplnou definici schématu najdete v Format.xsd v úložišti zdrojového kódu PowerShellu na GitHubu.

Oddíl ViewDefinitions každého souboru Format.ps1xml obsahuje <View> značky, které definují každé zobrazení. Typická značka <View> obsahuje následující značky:

<Name> identifikuje název zobrazení.
<ViewSelectedBy> určuje typ objektu nebo typy, na které se zobrazení vztahuje.
<GroupBy> určuje, jak budou položky v zobrazení sloučeny ve skupinách.
<TableControl>, <ListControl>, <WideControl>a <CustomControl> obsahují značky, které určují způsob zobrazení jednotlivých položek.

Značka ViewSelectedBy

Značka <ViewSelectedBy> může obsahovat značku <TypeName> pro každý typ objektu, na který se zobrazení vztahuje. Nebo může obsahovat značku <SelectionSetName>, která odkazuje na sadu výběru definovanou jinde pomocí značky <SelectionSet>.

Značka GroupBy

Značka <GroupBy> obsahuje značku <PropertyName>, která určuje vlastnost objektu, podle kterých se mají položky seskupit. Obsahuje také značku <Label>, která určuje řetězec, který se má použít jako popisek pro každou skupinu, nebo značku <CustomControlName>, která odkazuje na vlastní ovládací prvek definovaný jinde pomocí značky <Control>. Značka <Control> obsahuje značku <Name> a značku <CustomControl>.

TableControlTag

Značka <TableControl> obvykle obsahuje značky <TableHeaders> a <TableRowEntries>, které definují formátování hlav a řádků tabulky. Značka <TableHeaders> obvykle obsahuje značky <TableColumnHeader>, které obsahují značky <Label>, <Width>a <Alignment>. Značka <TableRowEntries> obsahuje značky <TableRowEntry> pro každý řádek v tabulce. Značka <TableRowEntry> obsahuje značku <TableColumnItems>, která dále obsahuje značku <TableColumnItem> pro jednotlivé sloupce v rámci řádku. Značka <TableColumnItem> obvykle obsahuje značku <PropertyName>, která identifikuje vlastnost objektu, která se má zobrazit v definovaném umístění, nebo značku <ScriptBlock> obsahující kód skriptu, který vypočítá výsledek, který se má zobrazit v umístění.

Poznámka

Bloky skriptů se dají použít i jinde v místech, kde můžou být užitečné počítané výsledky.

Značka <TableColumnItem> může také obsahovat značku <FormatString>, která určuje způsob zobrazení vlastnosti nebo počítaných výsledků.

Značka ListControl

Značka <ListControl> obvykle obsahuje značku <ListEntries>. Značka <ListEntries> obsahuje značku <ListEntry>. Značka <ListEntry> obsahuje značku <ListItems>. Značka <ListItems> obsahuje značky <ListItem>, které obsahují značky <PropertyName>. Značky <PropertyName> určují vlastnost objektu, která se má zobrazit v zadaném umístění v seznamu. Pokud je výběr zobrazení definovaný pomocí sady výběrů, mohou značky <ListControl> a <ListEntry> obsahovat také <EntrySelectedBy> značku, která obsahuje jednu nebo více značek <TypeName>. Tyto <TypeName> značky určují typ objektu, který má značka <ListControl> zobrazit.

Značka WideControl

Značka <WideControl> obvykle obsahuje značku <WideEntries>. Značka <WideEntries> obsahuje jednu nebo více značek <WideEntry>. Značka <WideEntry> obsahuje jednu značku <WideItem>.

Značka <WideItem> musí obsahovat značku <PropertyName> nebo značku <ScriptBlock>. Značka <PropertyName> určuje vlastnost, která se má zobrazit v zadaném umístění v zobrazení. Značka <ScriptBlock> určuje skript pro vyhodnocení a zobrazení v zadaném umístění v zobrazení.

Značka <WideItem> může obsahovat značku <FormatString>, která určuje způsob zobrazení vlastnosti.

Značka CustomControl

Značka <CustomControl> umožňuje definovat formát pomocí bloku skriptu. Značka <CustomControl> obvykle obsahuje <CustomEntries> značku, která obsahuje více značek <CustomEntry>. Každá značka <CustomEntry> obsahuje značku <CustomItem>, která může obsahovat různé značky, které určují obsah a formátování zadaného umístění v zobrazení, včetně <Text>, <Indentation>, <ExpressionBinding>a značek <NewLine>.

Použití souboru Tracing Format.ps1xml

K detekci chyb při načítání nebo aplikaci souborů Format.ps1xml použijte rutinu Trace-Command s některou z následujících komponent formátu jako hodnotu parametru Name:

FormatFileLoading
FormatViewBinding

Pro více informací viz Trace-Command a Get-TraceSource.

Podepsání souboru Format.ps1xml

Pokud chcete chránit uživatele Format.ps1xml souboru, podepište ho pomocí digitálního podpisu. Další informace najdete v tématu about_Signing.

Ukázkový KÓD XML pro vlastní zobrazení Format-Table

Následující ukázka XML vytvoří vlastní zobrazení Format-Table pro objekty System.IO.DirectoryInfo a System.IO.FileInfo, které byly vytvořeny Get-ChildItem. Vlastní zobrazení má název MyGciView a přidá do tabulky sloupec CreationTime.

K vytvoření vlastního zobrazení použijte rutiny Get-FormatData a Export-FormatData k vygenerování souboru .ps1xml. Potom upravte soubor .ps1xml a vytvořte kód pro vlastní zobrazení. Soubor .ps1xml lze uložit do libovolného adresáře, ke kterému má PowerShell přístup. Například podsložka $HOME.

Po vytvoření souboru .ps1xml použijte rutinu Update-FormatData k zahrnutí zobrazení do aktuální relace PowerShellu. Alternativně, pokud potřebujete zobrazení dostupné ve všech relacích PowerShellu, přidejte do profilu PowerShellu příkaz pro aktualizaci.

V tomto příkladu musí vlastní zobrazení použít formát tabulky, jinak Format-Table selže.

Pomocí Format-Table s parametrem View zadejte název vlastního zobrazení, MyGciViewa naformátujte výstup tabulky pomocí sloupce CreationTime. Příklad toho, jak je příkaz spuštěn, naleznete v tématu Format-Table.