about_Format.ps1xml

Krótki opis

Począwszy od programu PowerShell 6, domyślne widoki obiektów są zdefiniowane w kodzie źródłowym programu PowerShell.

Możesz utworzyć własne pliki Format.ps1xml, aby zmienić wyświetlanie obiektów lub zdefiniować domyślne wyświetlanie nowych typów obiektów tworzonych w programie PowerShell.

Długi opis

Począwszy od programu PowerShell 6, widoki domyślne są definiowane w kodzie źródłowym programu PowerShell. Pliki Format.ps1xml z programu PowerShell 5.1 i starszych wersji nie istnieją w programie PowerShell 6 i nowszych wersjach.

Kod źródłowy programu PowerShell definiuje domyślne wyświetlanie obiektów w konsoli programu PowerShell. Możesz utworzyć własne pliki Format.ps1xml, aby zmienić wyświetlanie obiektów lub zdefiniować domyślne wyświetlanie nowych typów obiektów tworzonych w programie PowerShell.

Gdy program PowerShell wyświetla obiekt, używa danych w plikach formatowania strukturalnego w celu określenia domyślnego wyświetlania obiektu. Dane w plikach formatowania określają, czy obiekt jest renderowany w tabeli, czy na liście, i określa, które właściwości są wyświetlane domyślnie.

Formatowanie ma wpływ tylko na wyświetlanie. Nie ma to wpływu na właściwości obiektu przekazywane potoku lub sposób ich przekazywania. Format.ps1xml plików nie można używać do dostosowywania formatu danych wyjściowych dla tabel skrótów.

Plik formatowania .ps1xml może definiować cztery różne widoki każdego obiektu:

Stół
Lista
Szeroki
Zwyczaj

Na przykład gdy dane wyjściowe polecenia Get-ChildItem są przesyłane potokowo do polecenia Format-List, Format-List używa widoku listy zdefiniowanego w kodzie źródłowym, aby określić sposób wyświetlania obiektów plików i folderów jako listy.

Gdy plik formatowania zawiera więcej niż jeden widok obiektu, program PowerShell stosuje pierwszy widok, który znajduje.

W niestandardowym pliku Format.ps1xml widok jest definiowany przez zestaw tagów XML opisujących nazwę widoku, typ obiektu, do którego można zastosować, nagłówki kolumn i właściwości wyświetlane w treści widoku. Format w plikach Format.ps1xml jest stosowany tuż przed przedstawieniem danych użytkownikowi.

Tworzenie nowych plików Format.ps1xml

Aby zmienić format wyświetlania istniejącego widoku obiektu lub dodać widoki dla nowych obiektów, utwórz własne pliki Format.ps1xml, a następnie dodaj je do sesji programu PowerShell.

Aby utworzyć plik Format.ps1xml w celu zdefiniowania widoku niestandardowego, użyj poleceń cmdlet Get-FormatData i Export-FormatData. Edytowanie pliku za pomocą edytora tekstów. Plik można zapisać w dowolnym katalogu, do którego program PowerShell może uzyskać dostęp, na przykład podkatalogu $HOME.

Aby zmienić formatowanie bieżącego widoku, znajdź widok w pliku formatowania, a następnie użyj tagów, aby zmienić widok. Aby utworzyć widok dla nowego typu obiektu, utwórz nowy widok lub użyj istniejącego widoku jako modelu. Tagi są opisane w następnej sekcji. Następnie można usunąć wszystkie inne widoki w pliku, aby zmiany zostały oczywiste dla każdego, kto bada plik.

Po zapisaniu zmian użyj Update-FormatData, aby dodać nowy plik do sesji programu PowerShell. Jeśli widok ma mieć pierwszeństwo przed widokiem zdefiniowanym we wbudowanych plikach, użyj parametru PrependPath. Update-FormatData dotyczy tylko bieżącej sesji. Aby wprowadzić zmianę we wszystkich przyszłych sesjach, dodaj polecenie Update-FormatData do profilu programu PowerShell.

Przykład: dodawanie danych kalendarza do obiektów kultury

W tym przykładzie pokazano, jak zmienić formatowanie obiektów kultury System.Globalization.CultureInfo wygenerowane przez polecenie cmdlet Get-Culture w bieżącej sesji programu PowerShell. Polecenia w przykładzie dodają właściwość Calendar do wyświetlania widoku tabeli domyślnie używanego dla obiektów kultury.

Aby rozpocząć, pobierz dane formatu z pliku kodu źródłowego i utwórz plik Format.ps1xml zawierający bieżący widok obiektów kultury.

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

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

Otwórz plik CultureInfo.Format.ps1xml w dowolnym edytorze XML lub tekstowym, takim jak Visual Studio Code. Poniższy kod XML definiuje widoki obiektu CultureInfo.

Plik CultureInfo.Format.ps1xml powinien wyglądać podobnie do następującego przykładu:

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

Utwórz nową kolumnę dla właściwości Calendar, dodając nowy zestaw tagów <TableColumnHeader>. Wartość właściwości Calendar może być długa, dlatego określ wartość 45 znaków jako <Width>.

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

Dodaj nowy element kolumny dla kalendarza w wierszach tabeli, używając tagów <TableColumnItem> i <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>

Zapisz i zamknij plik. Użyj Update-FormatData, aby dodać nowy plik formatu do bieżącej sesji programu PowerShell.

W tym przykładzie użyto parametru PrependPath, aby umieścić nowy plik w wyższej kolejności pierwszeństwa niż oryginalny plik. Aby uzyskać więcej informacji, zobacz Update-FormatData.

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

Aby przetestować zmianę, wpisz Get-Culture i przejrzyj dane wyjściowe zawierające właściwość Calendar.

Get-Culture

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

Plik XML w plikach Format.ps1xml

Pełną definicję schematu można znaleźć w Format.xsd w repozytorium kodu źródłowego programu PowerShell w witrynie GitHub.

Sekcja ViewDefinitions każdego pliku Format.ps1xml zawiera tagi <View> definiujące każdy widok. Typowy tag <View> zawiera następujące tagi:

<Name> identyfikuje nazwę widoku.
<ViewSelectedBy> określa typ obiektu lub typy, do których ma zastosowanie widok.
<GroupBy> określa sposób łączenia elementów w widoku w grupach.
<TableControl>, <ListControl>, <WideControl>i <CustomControl> zawierają tagi określające sposób wyświetlania każdego elementu.

Tag ViewSelectedBy

Tag <ViewSelectedBy> może zawierać tag <TypeName> dla każdego typu obiektu, do którego ma zastosowanie widok. Może również zawierać tag <SelectionSetName>, który odwołuje się do zestawu wyboru zdefiniowanego gdzie indziej przy użyciu tagu <SelectionSet>.

Tag 'Grupuj według'

Tag <GroupBy> zawiera tag <PropertyName>, który określa właściwość obiektu, według której elementy mają być zgrupowane. Zawiera również tag <Label>, który określa ciąg, który ma być używany jako etykieta dla każdej grupy lub tag <CustomControlName> odwołujący się do niestandardowej kontrolki zdefiniowanej gdzie indziej przy użyciu tagu <Control>. Tag <Control> zawiera tag <Name> i tag <CustomControl>.

TableControlTag

Tag <TableControl> zazwyczaj zawiera tagi <TableHeaders> i <TableRowEntries> definiujące formatowanie dla głów i wierszy tabeli. Tag <TableHeaders> zazwyczaj zawiera tagi <TableColumnHeader> zawierające tagi <Label>, <Width>i <Alignment>. Tag <TableRowEntries> zawiera <TableRowEntry> tagów dla każdego wiersza w tabeli. Tag <TableRowEntry> zawiera tag <TableColumnItems> zawierający tag <TableColumnItem> dla każdej kolumny w wierszu. Zazwyczaj tag <TableColumnItem> zawiera tag <PropertyName>, który identyfikuje właściwość obiektu do wyświetlenia w zdefiniowanej lokalizacji, lub tag <ScriptBlock> zawierający kod skryptu, który oblicza wynik, który ma być wyświetlany w lokalizacji.

Notatka

Bloki skryptów mogą być również używane w innych miejscach, w których wyniki obliczeniowe mogą być przydatne.

Tag <TableColumnItem> może również zawierać tag <FormatString> określający sposób wyświetlania właściwości lub wyników obliczeniowych.

Znacznik ListControl

Tag <ListControl> zazwyczaj zawiera tag <ListEntries>. Tag <ListEntries> zawiera tag <ListEntry>. Tag <ListEntry> zawiera tag <ListItems>. Tag <ListItems> zawiera tagi <ListItem>, które zawierają tagi <PropertyName>. Tagi <PropertyName> określają właściwość obiektu, która ma być wyświetlana w określonej lokalizacji na liście. Jeśli wybór widoku jest zdefiniowany za pomocą zestawu zaznaczeń, tagi <ListControl> i <ListEntry> mogą również zawierać tag <EntrySelectedBy>, który zawiera co najmniej jeden tag <TypeName>. Tagi <TypeName> wskazują typ obiektu, który tag <ListControl> ma wyświetlać.

Tag WideControl

Tag <WideControl> zazwyczaj zawiera tag <WideEntries>. Tag <WideEntries> zawiera jeden lub więcej tagów <WideEntry>. Tag <WideEntry> zawiera jeden tag <WideItem>.

Tag <WideItem> musi zawierać tag <PropertyName> lub tag <ScriptBlock>. Tag <PropertyName> określa właściwość do wyświetlenia w określonej lokalizacji w widoku. Tag <ScriptBlock> określa skrypt do oceny i wyświetlania w określonej lokalizacji w widoku.

Tag <WideItem> może zawierać tag <FormatString> określający sposób wyświetlania właściwości.

Tag CustomControl

Tag <CustomControl> umożliwia definiowanie formatu za pomocą blokady skryptu. Tag <CustomControl> zazwyczaj zawiera tag <CustomEntries> zawierający wiele tagów <CustomEntry>. Każdy tag <CustomEntry> zawiera tag <CustomItem>, który może zawierać różne tagi określające zawartość i formatowanie określonej lokalizacji w widoku, w tym <Text>, <Indentation>, <ExpressionBinding>i <NewLine> tagów.

Użycie pliku Tracing Format.ps1xml

Aby wykryć błędy podczas ładowania lub stosowania plików Format.ps1xml, użyj polecenia cmdlet Trace-Command z dowolnym z następujących składników formatu jako wartości parametru Name:

ŁadowaniePlikuFormatu
FormatViewBinding

Aby uzyskać więcej informacji, zobacz Trace-Command i Get-TraceSource.

Podpisywanie pliku Format.ps1xml

Aby chronić użytkowników pliku Format.ps1xml, podpisz plik przy użyciu podpisu cyfrowego. Aby uzyskać więcej informacji, proszę zapoznać się z about_Signing.

Przykładowy kod XML dla widoku niestandardowego Format-Table

Poniższy przykład XML tworzy niestandardowy widok Format-Table dla obiektów System.IO.DirectoryInfo i System.IO.FileInfo utworzonych przez Get-ChildItem. Widok niestandardowy ma nazwę MyGciView i dodaje kolumnę CreationTime do tabeli.

Aby utworzyć widok niestandardowy, użyj poleceń cmdlet Get-FormatData i Export-FormatData, aby wygenerować plik .ps1xml. Następnie zmodyfikuj plik .ps1xml, aby utworzyć kod dla widoku niestandardowego. Plik .ps1xml można przechowywać w dowolnym katalogu, do którego ma dostęp program PowerShell. Na przykład podkatalog $HOME.

Po utworzeniu pliku .ps1xml użyj polecenia cmdlet Update-FormatData, aby uwzględnić widok w bieżącej sesji programu PowerShell. Możesz też dodać polecenie aktualizacji do profilu programu PowerShell, jeśli potrzebujesz widoku dostępnego we wszystkich sesjach programu PowerShell.

W tym przykładzie niestandardowy widok musi używać formatu tabeli, w przeciwnym razie Format-Table nie działa.

Użyj Format-Table z parametrem View, aby określić nazwę widoku niestandardowego, MyGciViewi sformatuj dane wyjściowe tabeli przy użyciu kolumny CreationTime. Aby zapoznać się z przykładem uruchamiania polecenia, zobacz Format-Table.