about_Format.ps1xml

Статья
04/13/2023

Краткое описание

Начиная с PowerShell 6 представления по умолчанию для объектов определяются в исходном коде PowerShell.

Вы можете создать собственные Format.ps1xml файлы, чтобы изменить отображение объектов или определить значения по умолчанию для новых типов объектов, создаваемых в PowerShell.

Подробное описание

Начиная с PowerShell 6 представления по умолчанию определяются в исходном коде PowerShell. Файлы Format.ps1xml из PowerShell 5.1 и более ранних версий не существуют в PowerShell 6 и более поздних версиях.

Исходный код PowerShell определяет отображение объектов по умолчанию в консоли PowerShell. Вы можете создать собственные Format.ps1xml файлы, чтобы изменить отображение объектов или определить значения по умолчанию для новых типов объектов, создаваемых в PowerShell.

Когда PowerShell отображает объект, он использует данные в структурированных файлах форматирования для определения отображения объекта по умолчанию. Данные в файлах форматирования определяют, отображается ли объект в таблице или списке, и определяет, какие свойства отображаются по умолчанию.

Форматирование влияет только на отображение. Это не влияет на то, какие свойства объекта передаются по конвейеру или как они передаются. Format.ps1xml Файлы нельзя использовать для настройки формата выходных данных для хэш-таблиц.

.ps1xml Файл форматирования может определить четыре разных представления каждого объекта:

Таблица
List
Широк.
Пользовательское

Например, если выходные данные Get-ChildItem команды передаются Format-List в команду, использует представление списка, определенное в исходном коде, Format-List чтобы определить, как отображать объекты файлов и папок в виде списка.

Если файл форматирования включает несколько представлений объекта, PowerShell применяет первое представление, которое он находит.

В пользовательском Format.ps1xml файле представление определяется набором XML-тегов, описывающих имя представления, тип объекта, к которому он может применяться, заголовки столбцов и свойства, отображаемые в тексте представления. Формат в Format.ps1xml файлах применяется непосредственно перед представлением данных пользователю.

Создание новых файлов Format.ps1xml

Чтобы изменить формат отображения существующего представления объектов или добавить представления для новых объектов, создайте собственные Format.ps1xml файлы и добавьте их в сеанс PowerShell.

Чтобы создать Format.ps1xml файл для определения пользовательского представления, используйте командлеты Get-FormatData и Export-FormatData . Используйте текстовый редактор для редактирования файла. Файл можно сохранить в любом каталоге, к которому может получить доступ PowerShell, например подкаталогу $HOME.

Чтобы изменить форматирование текущего представления, найдите представление в файле форматирования и используйте теги для изменения представления. Чтобы создать представление для нового типа объекта, создайте новое представление или используйте существующее представление в качестве модели. Теги описаны в следующем разделе. Затем вы можете удалить все остальные представления в файле, чтобы изменения были очевидны для всех, кто изучает файл.

После сохранения изменений используйте Update-FormatData , чтобы добавить новый файл в сеанс PowerShell. Если представление должно иметь приоритет над представлением, определенным в встроенных файлах, используйте параметр PrependPath . Update-FormatData влияет только на текущий сеанс. Чтобы внести изменения во все будущие сеансы, добавьте Update-FormatData команду в профиль PowerShell.

Пример. Добавление данных календаря в объекты языка и региональных параметров

В этом примере показано, как изменить форматирование объектов языка и региональных параметров System.Globalization.CultureInfo , Get-Culture созданных командлетом в текущем сеансе PowerShell. Команды в примере добавляют свойство Calendar в представление таблицы по умолчанию для объектов языка и региональных параметров.

Чтобы начать, получите данные формата из файла исходного кода и создайте Format.ps1xml файл, содержащий текущее представление объектов языка и региональных параметров.

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

Откройте файл в любом xml-редакторе или текстовом редакторе CultureInfo.Format.ps1xml , например Visual Studio Code. Следующий XML-код определяет представления объекта CultureInfo .

Файл CultureInfo.Format.ps1xml должен выглядеть следующим образом:

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

Создайте столбец для свойства Calendar , добавив новый набор тегов <TableColumnHeader> . Значение свойства Calendar может быть длинным, поэтому укажите значение 45 символов в качестве <Width>значения.

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

Добавьте новый элемент столбца для календаря в строки таблицы с помощью <TableColumnItem> тегов и <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>

Сохранить и закрыть файл. Используйте Update-FormatData для добавления нового файла форматирования в текущий сеанс PowerShell.

В этом примере используется параметр PrependPath для размещения нового файла в более высоком порядке приоритета, чем исходный файл. Дополнительные сведения см. в разделе Update-FormatData.

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

Чтобы проверить изменение, введите Get-Culture и просмотрите выходные данные, включающие свойство Calendar .

Get-Culture

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

XML-файл в файлах Format.ps1xml

Полное определение схемы можно найти в Format.xsd в репозитории исходного кода PowerShell на GitHub.

Раздел ViewDefinitions каждого Format.ps1xml файла содержит <View> теги, определяющие каждое представление. Типичный <View> тег содержит следующие теги:

<Name> определяет имя представления.
<ViewSelectedBy> указывает тип объекта или типы, к которым применяется представление.
<GroupBy> указывает, как элементы в представлении будут объединяться в группах.
<TableControl>, <ListControl>, <WideControl>и <CustomControl> содержат теги, определяющие способ отображения каждого элемента.

Тег ViewSelectedBy

Тег <ViewSelectedBy> может содержать <TypeName> тег для каждого типа объекта, к которому применяется представление. Кроме того, он может содержать <SelectionSetName> тег, ссылающийся на набор выбора, определенный в другом месте с помощью тега <SelectionSet> .

Тег GroupBy

Тег <GroupBy> содержит тег, указывающий <PropertyName> свойство объекта, по которому нужно сгруппировать элементы. Он также содержит <Label> тег, указывающий строку, которая будет использоваться в качестве метки для каждой группы или <CustomControlName> тега, ссылающегося на пользовательский элемент управления, определенный в другом месте с помощью тега <Control> . Тег <Control> содержит <Name> тег и <CustomControl> тег.

TableControlTag

Тег <TableControl> обычно содержит <TableHeaders> и <TableRowEntries> теги, определяющие форматирование для голов и строк таблицы. Тег <TableHeaders> обычно содержит <TableColumnHeader> теги, содержащие <Label><Width>теги и <Alignment> теги. Тег <TableRowEntries> содержит <TableRowEntry> теги для каждой строки в таблице. Тег <TableRowEntry> содержит <TableColumnItems> тег, содержащий <TableColumnItem> тег для каждого столбца в строке. Как правило, <TableColumnItem> тег содержит <PropertyName> либо тег, определяющий свойство объекта, отображаемое в определенном расположении, либо <ScriptBlock> тег, содержащий код скрипта, который вычисляет результат, отображаемый в расположении.

Примечание.

Блоки скриптов также можно использовать в других местах, где можно использовать вычисляемые результаты.

Тег <TableColumnItem> также может содержать тег, указывающий <FormatString> , как будет отображаться свойство или вычисляемые результаты.

Тег ListControl

Тег <ListControl> обычно содержит <ListEntries> тег. Тег <ListEntries> содержит <ListEntry> тег. Тег <ListEntry> содержит <ListItems> тег. Тег <ListItems> содержит <ListItem> теги, содержащие <PropertyName> теги. Теги <PropertyName> указывают свойство объекта, отображаемое в указанном расположении в списке. Если выбор представления определен с помощью набора выбора, <ListControl><ListEntry> теги также могут содержать <EntrySelectedBy> тег, содержащий один или несколько <TypeName> тегов. Эти <TypeName> теги указывают тип объекта, который <ListControl> должен отображать тег.

Тег WideControl

Тег <WideControl> обычно содержит <WideEntries> тег. Тег <WideEntries> содержит один или несколько <WideEntry> тегов. Тег <WideEntry> содержит один <WideItem> тег.

Тег <WideItem> должен содержать <PropertyName> тег или <ScriptBlock> тег. Тег <PropertyName> указывает свойство, отображаемое в указанном расположении в представлении. Тег <ScriptBlock> указывает скрипт для оценки и отображения в указанном расположении в представлении.

Тег <WideItem> может содержать тег, указывающий <FormatString> способ отображения свойства.

Тег CustomControl

Тег <CustomControl> позволяет использовать блок скрипта для определения формата. Тег <CustomControl> обычно содержит <CustomEntries> тег, содержащий несколько <CustomEntry> тегов. Каждый <CustomEntry> тег содержит <CustomItem> тег, который может содержать различные теги, которые указывают содержимое и форматирование указанного расположения в представлении, включая <Text>, <Indentation><ExpressionBinding>и <NewLine> теги.

Использование файла Format.ps1xml

Чтобы обнаружить ошибки при загрузке или приложении Format.ps1xml файлов, используйте Trace-Command командлет с любым из следующих компонентов формата в качестве значения параметра Name :

FormatFileLoading
FormatViewBinding

Дополнительные сведения см. в разделе Trace-Command и Get-TraceSource.

Подписывание файла Format.ps1xml

Чтобы защитить пользователей файла, подпишите файл с помощью цифровой Format.ps1xml подписи. Дополнительные сведения см. в about_Signing.

Пример XML для пользовательского представления "Формат таблицы"

В следующем примере XML создается пользовательское представление для объектов System.IO.DirectoryInfo и System.IO.FileInfo, созданныхGet-ChildItem.Format-Table Пользовательское представление называется mygciview и добавляет столбец CreationTime в таблицу.

Чтобы создать пользовательское представление, используйте Get-FormatData командлеты для Export-FormatData создания .ps1xml файла. Затем измените .ps1xml файл, чтобы создать код для пользовательского представления. Файл .ps1xml можно хранить в любом каталоге, к которому может получить доступ PowerShell. Например, подкаталог $HOME.

.ps1xml После создания файла используйте Update-FormatData командлет для включения представления в текущий сеанс PowerShell. Кроме того, добавьте команду обновления в профиль PowerShell, если вам потребуется представление, доступное во всех сеансах PowerShell.

В этом примере пользовательское представление должно использовать формат таблицы, в противном случае завершается Format-Table сбоем.

Используйте Format-Table параметр View для указания имени пользовательского представления, mygciview и форматирования выходных данных таблицы с помощью столбца CreationTime . Пример выполнения команды см. в разделе Format-Table.