about_Format.ps1xml

Artykuł
04/13/2023

Krótki opis

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

Możesz utworzyć własne Format.ps1xml pliki, 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 Format.ps1xml pliki, 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 w potoku ani sposób ich przekazywania. Format.ps1xml Plików nie można używać do dostosowywania formatu danych wyjściowych dla tabel skrótów.

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

Tabela
Lista
Szeroki
Niestandardowy

Na przykład gdy dane wyjściowe Get-ChildItem polecenia są przesyłane potokowo do Format-List polecenia, 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 pliku niestandardowym Format.ps1xml widok jest definiowany przez zestaw tagów XML opisujących nazwę widoku, typ obiektu, do którego można go zastosować, nagłówki kolumn i właściwości wyświetlane w treści widoku. Format w Format.ps1xml plikach jest stosowany tuż przed udostępnieniem użytkownikowi danych.

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 Format.ps1xml pliki, a następnie dodaj je do sesji programu PowerShell.

Aby utworzyć Format.ps1xml plik 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 wszystkich osób badających plik.

Po zapisaniu zmian użyj polecenia Update-FormatData , aby dodać nowy plik do sesji programu PowerShell. Jeśli widok ma mieć pierwszeństwo przed widokiem zdefiniowanym w wbudowanych plikach, użyj parametru PrependPath . Update-FormatData dotyczy tylko bieżącej sesji. Aby wprowadzić zmianę do wszystkich przyszłych sesji, dodaj Update-FormatData polecenie 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 Get-Culture polecenie cmdlet w bieżącej sesji programu PowerShell. Polecenia w przykładzie dodają właściwość Calendar do domyślnego widoku tabeli wyświetlania obiektów kultury.

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

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

CultureInfo.Format.ps1xml Otwórz plik 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 calendar w wierszach tabeli przy użyciu 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 polecenia 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 pliku Format.xsd w repozytorium kodu źródłowego programu PowerShell w witrynie GitHub.

Sekcja ViewDefinitions każdego Format.ps1xml pliku zawiera <View> tagi definiujące każdy widok. Typowy <View> tag 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ć <TypeName> tag dla każdego typu obiektu, do którego ma zastosowanie widok. Może również zawierać <SelectionSetName> tag, który odwołuje się do zestawu wyboru zdefiniowanego gdzie indziej przy użyciu tagu <SelectionSet> .

Tag GroupBy

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

TableControlTag

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

Uwaga

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

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

Tag ListControl

Tag <ListControl> zwykle zawiera <ListEntries> tag. Tag <ListEntries> zawiera <ListEntry> tag . Tag <ListEntry> zawiera <ListItems> tag . Tag <ListItems> zawiera <ListItem> tagi, które zawierają <PropertyName> tagi. 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 przy użyciu zestawu zaznaczenia, <ListControl> tagi i <ListEntry> mogą również zawierać <EntrySelectedBy> tag zawierający jeden lub więcej <TypeName> tagów. Te <TypeName> tagi określają typ obiektu, który <ListControl> ma być wyświetlany.

Tag WideControl

Tag <WideControl> zwykle zawiera <WideEntries> tag. Tag <WideEntries> zawiera co najmniej jeden <WideEntry> tag. <WideEntry> Tag zawiera jeden <WideItem> tag.

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

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

Tag CustomControl

Tag <CustomControl> umożliwia definiowanie formatu za pomocą bloku skryptu. <CustomControl> Tag zazwyczaj zawiera <CustomEntries> tag zawierający wiele <CustomEntry> tagów. Każdy <CustomEntry> tag zawiera <CustomItem> tag, który może zawierać różne tagi, które określają 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 Format.ps1xml plików, użyj Trace-Command polecenia cmdlet z dowolnym z następujących składników formatu jako wartości parametru Name :

FormatFileLoading
FormatViewBinding

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

Podpisywanie pliku Format.ps1xml

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

Przykładowy kod XML dla widoku niestandardowego Format-Table

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

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

Po utworzeniu .ps1xml pliku użyj Update-FormatData polecenia cmdlet , 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 widok niestandardowy musi używać formatu tabeli, w przeciwnym razie Format-Table kończy się niepowodzeniem.

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