about_Format.ps1xml

Artykuł
04/13/2023

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

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

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

Aby utworzyć plik w Format.ps1xml 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 polecenia 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 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 dla kolumny Calendar w wierszach tabeli przy użyciu <TableColumnItem> tagów 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 polecenia , 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 Grupuj wg

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 określający ciąg, który ma być używany jako etykieta dla każdej grupy lub <CustomControlName> tag odwołujący się do kontrolki niestandardowej 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 dla 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 których wyniki obliczeniowe mogą być przydatne.

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> zazwyczaj 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 co najmniej jeden <TypeName> tag. Te <TypeName> tagi określają typ obiektu, który <ListControl> ma być wyświetlany.

Tag WideControl

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

<WideItem> Tag musi zawierać <PropertyName> tag lub <ScriptBlock> tag. Tag <PropertyName> określa właściwość, która ma być wyświetlana w określonej lokalizacji w widoku. <ScriptBlock> Tag określa skrypt do oceny i wyświetlania w określonej lokalizacji w widoku.

<WideItem> Tag 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 dla obiektów System.IO.DirectoryInfo i System.IO.FileInfo utworzonych przez Get-ChildItemprogram . Widok niestandardowy nosi 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 ma dostęp program PowerShell. 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 parametru Format-TableView , 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-Table.