about_Format.ps1xml

Artykuł
04/13/2023

Krótki opis

Pliki Format.ps1xml w programie PowerShell definiują 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.

Długi opis

Pliki Format.ps1xml w programie PowerShell definiują domyślne wyświetlanie obiektów w programie 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.

Program PowerShell zawiera siedem plików formatowania. Te pliki znajdują się w katalogu instalacyjnym ($PSHOME). Każdy plik definiuje wyświetlanie grupy obiektów programu Microsoft .NET Framework:

Certificate.Format.ps1xml

Obiekty w magazynie certyfikatów, takie jak certyfikaty X.509 i magazyny certyfikatów.
DotNetTypes.Format.ps1xml

Inne typy programu .NET Framework, takie jak CultureInfo, FileVersionInfo i EventLogEntry.
FileSystem.Format.ps1xml

Obiekty systemu plików, takie jak pliki i katalogi.
Help.Format.ps1xml

Widoki pomocy, takie jak szczegółowe i pełne widoki, parametry i przykłady.
PowerShellCore.Format.ps1xml

Obiekty generowane przez podstawowe polecenia cmdlet programu PowerShell, takie jak Get-Member i Get-History.
PowerShellTrace.Format.ps1xml

Obiekty śledzenia, takie jak obiekty wygenerowane przez Trace-Command polecenie cmdlet.
Registry.Format.ps1xml

Obiekty rejestru, takie jak klucze i wpisy.

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 potokiem do Format-List polecenia, Format-List używa widoku w FileSystem.Format.ps1xml pliku do określenia sposobu 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.

Format.ps1xml W pliku 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 Format.ps1xml plikach jest stosowany tuż przed przedstawieniem danych użytkownikowi.

Tworzenie nowych plików Format.ps1xml

Pliki .ps1xml zainstalowane za pomocą programu PowerShell są podpisane cyfrowo, aby zapobiec manipulacji, ponieważ formatowanie może zawierać bloki skryptów. 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ć nowy plik, skopiuj istniejący Format.ps1xml plik. Nowy plik może mieć dowolną .ps1xml nazwę, ale musi mieć rozszerzenie nazwy pliku. Nowy plik można umieścić w dowolnym katalogu dostępnym dla programu PowerShell, ale warto umieścić pliki w katalogu instalacyjnym programu PowerShell ($PSHOME) lub w podkatalogu katalogu instalacyjnego.

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 polecenia cmdlet , 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.

Pierwszym krokiem jest znalezienie Format.ps1xml pliku zawierającego bieżący widok obiektów kultury. Następujące Select-String polecenie znajduje plik:

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.Globalization.CultureInfo"
}

Select-String @Parms

C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:113:
     <Name>System.Globalization.CultureInfo</Name>
C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:115:
<TypeName>System.Globalization.CultureInfo</TypeName>

To polecenie pokazuje, że definicja znajduje się w DotNetTypes.Format.ps1xml pliku.

Następne polecenie kopiuje zawartość pliku do nowego pliku . MyDotNetTypes.Format.ps1xml

Copy-Item $PSHome\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml

MyDotNetTypes.Format.ps1xml Otwórz plik w dowolnym edytorze XML lub tekstowym, takim jak Visual Studio Code. Znajdź sekcję obiektu System.Globalization.CultureInfo . Poniższy kod XML definiuje widoki obiektu CultureInfo . Obiekt ma tylko widok TableControl .

<View>
  <Name>System.Globalization.CultureInfo</Name>
  <ViewSelectedBy>
    <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
    <TypeName>System.Globalization.CultureInfo</TypeName>
  </ViewSelectedBy>
  <TableControl>
    <TableHeaders>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
      <TableColumnHeader>
        <Width>16</Width>
      </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>

Usuń pozostałą część pliku, z wyjątkiem otwierania <?xml>, <Configuration>i tagów oraz <ViewDefinitions> zamykających <ViewDefinitions> i <Configuration> tagów. Jeśli istnieje podpis cyfrowy, usuń go z pliku niestandardowego Format.ps1xml.

Plik MyDotNetTypes.Format.ps1xml powinien teraz 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>Deserialized.System.Globalization.CultureInfo</TypeName>
    <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 $PSHOME\MyDotNetTypes.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.

Wartość domyślna jest wyświetlana w pliku Types.ps1xml

Domyślne wyświetlanie niektórych podstawowych typów obiektów jest definiowanych w Types.ps1xml pliku w $PSHOME katalogu. Węzły mają nazwę PsStandardMembers, a węzły podrzędne używają jednego z następujących tagów:

<DefaultDisplayProperty>
<DefaultDisplayPropertySet>
<DefaultKeyPropertySet>

Aby uzyskać więcej informacji, zobacz about_Types.ps1xml.

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 tworzy Format-Table niestandardowy widok obiektów System.IO.DirectoryInfo i System.IO.FileInfo utworzonych przez Get-ChildItemprogram . Widok niestandardowy nosi nazwę mygciview i dodaje kolumnę CreationTime do tabeli.

Widok niestandardowy jest tworzony na podstawie edytowanej wersji pliku przechowywanego FileSystem.Format.ps1xml w $PSHOME programie PowerShell 5.1.

Po zapisaniu pliku niestandardowego .ps1xml użyj polecenia Update-FormatData , aby uwzględnić widok w sesji 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-Table View , aby określić nazwę i sformatować dane wyjściowe tabeli w widoku niestandardowym. Aby zapoznać się z przykładem uruchamiania polecenia, zobacz Format-Table.

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.IO.DirectoryInfo"
}
Select-String @Parms
Copy-Item $PSHome\FileSystem.format.ps1xml .\MyFileSystem.Format.ps1xml
Update-FormatData -PrependPath $PSHOME\Format\MyFileSystem.Format.ps1xml