about_Format.ps1xml

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

Начиная с 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 может определять четыре различных представления каждого объекта:

Стол
Список
Широкий
Обычай

Например, если выходные данные команды 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, содержащий текущее представление объектов культуры.

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

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

Откройте файл CultureInfo.Format.ps1xml в любом xml-редакторе или текстовом редакторе, например 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

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

FormatFileLoading
FormatViewBinding

Для получения дополнительной информации, см. Trace-Command и Get-TraceSource.

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

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

Пример XML для пользовательского представления Format-Table

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

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

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

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

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