about_Types.ps1xml

  • Статья

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

Описание использования Types.ps1xml файлов для расширения типов объектов, используемых в PowerShell.

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

Данные расширенного типа определяют дополнительные свойства и методы ("члены") типов объектов в PowerShell. Существует два способа добавления данных расширенного типа в сеанс PowerShell.

  • Types.ps1xml file: XML-файл, определяющий данные расширенного типа.
  • Update-TypeData: командлет, который перезагрузит Types.ps1xml файлы и определяет расширенные данные для типов в текущем сеансе.

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

Сведения о данных расширенного типа

Данные расширенного типа определяют дополнительные свойства и методы ("члены") типов объектов в PowerShell. Вы можете расширить любой тип, поддерживаемый PowerShell, и использовать добавленные свойства и методы таким же образом, как и свойства, определенные в типах объектов.

Например, PowerShell добавляет свойство DateTime ко всем System.DateTime объектам, таким как возвращаемые командлетом Get-Date .

(Get-Date).DateTime

Sunday, January 29, 2012 9:43:57 AM

Свойство DateTime не будет находиться в описании структуры System.DateTime, так как PowerShell добавляет свойство и отображается только в PowerShell.

PowerShell внутренне определяет набор расширенных типов по умолчанию. Эти сведения о типе загружаются в каждом сеансе PowerShell при запуске. Свойство DateTime является частью этого набора по умолчанию. До PowerShell 6 определения типов были сохранены Types.ps1xml в каталоге установки PowerShell ($PSHOME).

Добавление данных расширенного типа в PowerShell

В сеансах PowerShell существует три источника данных расширенного типа.

  • Данные расширенного типа определяются PowerShell и загружаются автоматически в каждый сеанс PowerShell. Начиная с PowerShell 6 эти сведения компилируются в PowerShell и больше не отправляются в Types.ps1xml файл.

  • Файлы Types.ps1xml , экспортируемые модулями, загружаются при импорте модуля в текущий сеанс.

  • Данные расширенного типа, определенные с помощью командлета Update-TypeData , добавляются только в текущий сеанс. Он не сохраняется в файле.

В сеансе данные расширенного типа из трех источников применяются к объектам одинаково и доступны для всех объектов указанных типов.

Командлеты TypeData

Следующие командлеты включены в модуль Microsoft.PowerShell.Utility в PowerShell 3.0 и более поздних версий.

  • Get-TypeData: получает данные расширенного типа в текущем сеансе.
  • Update-TypeData: перезагружает Types.ps1xml файлы. Добавляет данные расширенного типа в текущий сеанс.
  • Remove-TypeData: удаляет данные расширенного типа из текущего сеанса.

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

Встроенные файлы Types.ps1xml

Файлы Types.ps1xml в $PSHOME каталоге добавляются автоматически в каждый сеанс.

Файл Types.ps1xml в каталоге установки PowerShell ($PSHOME) — это XML-текстовый файл, который позволяет добавлять свойства и методы в объекты, используемые в PowerShell. В PowerShell есть встроенные Types.ps1xml файлы, добавляющие несколько элементов в типы .NET, но можно создать дополнительные Types.ps1xml файлы для дальнейшего расширения типов.

Например, по умолчанию объекты массива (System.Array) имеют свойство Length , которое содержит количество объектов в массиве. Тем не менее, поскольку длина имени явно не описывает свойство, PowerShell добавляет свойство псевдонима с именем Count, которое отображает то же значение. Следующий XML-код добавляет свойство Count в System.Array тип.

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>
        Length
      </ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

Чтобы получить новый ПсевдонимProperty, используйте Get-Member команду в любом массиве, как показано в следующем примере.

Get-Member -InputObject (1,2,3,4)

Команда возвращает следующие результаты.

Name       MemberType    Definition
----       ----------    ----------
Count      AliasProperty Count = Length
Address    Method        System.Object& Address(Int32)
Clone      Method        System.Object Clone()
CopyTo     Method        System.Void CopyTo(Array array, Int32 index):
Equals     Method        System.Boolean Equals(Object obj)
Get        Method        System.Object Get(Int32)
# ...

В результате можно использовать свойство Count или свойство Length массивов в PowerShell. Например:

(1, 2, 3, 4).count
4

(1, 2, 3, 4).length
4

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

.ps1xml Файлы, установленные с помощью PowerShell, имеют цифровую подпись, чтобы предотвратить изменение, так как форматирование может включать блоки скриптов. Таким образом, чтобы добавить свойство или метод в тип .NET, создать собственные Types.ps1xml файлы и добавить их в сеанс PowerShell.

Чтобы создать файл, начните с копирования существующего Types.ps1xml файла. Новый файл может иметь любое имя, но у него должно быть .ps1xml расширение имени файла. Новый файл можно поместить в любой каталог, доступный Для PowerShell, но удобно разместить файлы в каталоге установки PowerShell или$PSHOME в подкаталоге каталога установки.

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

Types.ps1xml и add-member

Файлы Types.ps1xml добавляют свойства и методы ко всем экземплярам объектов указанного типа .NET в затронутом сеансе PowerShell. Однако если необходимо добавить свойства или методы только к одному экземпляру Add-Member объекта, используйте командлет.

Дополнительные сведения см. в разделе "Надстройка-член".

Пример. Добавление элемента age в объекты FileInfo

В этом примере показано, как добавить свойство Age в объекты System.IO.FileInfo . Возраст файла — это разница между временем создания и текущим временем в днях.

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

Сохраните следующий XML-код в файл $PSHOME\MyTypes.ps1xml.

<?xml version="1.0" encoding="utf-8" ?>
<Types>
  <Type>
    <Name>System.IO.FileInfo</Name>
    <Members>
      <ScriptProperty>
        <Name>Age</Name>
        <GetScriptBlock>
          ((Get-Date) - ($this.CreationTime)).Days
        </GetScriptBlock>
      </ScriptProperty>
    </Members>
  </Type>
</Types>

Запустите Update-TypeData , чтобы добавить новый Types.ps1xml файл в текущий сеанс. Команда использует параметр PrependData для размещения нового файла в порядке приоритета выше исходных определений.

Дополнительные сведения см. в Update-TypeDataразделе Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Чтобы проверить изменение, выполните Get-ChildItem команду, чтобы получить файл PowerShell.exe в $PSHOME каталоге, а затем передать файл Format-List командлету, чтобы получить список всех свойств файла. В результате изменения свойство Age отображается в списке.

Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age

142

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

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

Тег <Types> содержит все типы, определенные в файле. Должен быть только один <Types> тег.

Каждый тип .NET, упоминание в файле, должен быть представлен тегом<Type>.

Теги типов должны содержать следующие теги:

<Name>: заключает имя затронутого типа .NET.

<Members>: заключает теги для новых свойств и методов, определенных для типа .NET.

Любой из следующих тегов-членов может находиться внутри тега <Members> .

ПсевдонимProperty

Определяет новое имя существующего свойства.

Тег <AliasProperty> должен иметь <Name> тег, указывающий имя нового свойства и <ReferencedMemberName> тег, указывающий существующее свойство.

Например, свойство count alias — это псевдоним для свойства Length объектов массива.

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>Length</ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

CodeMethod

Ссылается на статический метод класса .NET.

Тег <CodeMethod> должен иметь тег, указывающий <Name> имя нового метода и <CodeReference> тег, указывающий код, в котором определен метод.

Например, метод ToString — это имя определения кода Microsoft.PowerShell.ToStringCodeMethods .

  <Type>
    <Name>System.Xml.XmlNode</Name>
    <Members>
      <CodeMethod>
        <Name>ToString</Name>
        <CodeReference>
          <TypeName>Microsoft.PowerShell.ToStringCodeMethods</TypeName>
          <MethodName>XmlNode</MethodName>
        </CodeReference>
      </CodeMethod>
    </Members>
  </Type>

CodeProperty

Ссылается на статический метод класса .NET.

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

Например, свойство Mode объектов — это свойство System.IO.DirectoryInfo кода, определенное в поставщике Файловой системы PowerShell.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <CodeProperty>
      <Name>Mode</Name>
      <GetCodeReference>
        <TypeName>
          Microsoft.PowerShell.Commands.FileSystemProvider
        </TypeName>
        <MethodName>Mode</MethodName>
      </GetCodeReference>
    </CodeProperty>
  </Members>
</Type>

MemberSet

Определяет коллекцию элементов (свойств и методов).

Теги <MemberSet> отображаются в основных <Members> тегах. Теги должны заключать <Name> тег, окружающий имя набора элементов и дополнительный <Members> тег, окружающий элементы (свойства и методы) в наборе. Любой из тегов, создающих свойство (например <NoteProperty> , или <ScriptProperty>) или метод (например <Method> , или <ScriptMethod>) может быть членом набора.

В Types.ps1xml файлах <MemberSet> тег используется для определения представлений по умолчанию объектов .NET в PowerShell. В этом случае имя набора элементов (значение в <Name> тегах) всегда является PsStandardMembers, а имена свойств (значение <Name> тега) являются одним из следующих:

  • DefaultDisplayProperty: одно свойство объекта.

  • DefaultDisplayPropertySet: одно или несколько свойств объекта.

  • DefaultKeyPropertySet: одно или несколько ключевых свойств объекта. Ключевое свойство определяет экземпляры значений свойств, например число идентификаторов элементов в журнале сеансов.

Например, следующий XML определяет отображение служб (System.ServiceProcess.ServiceController объектов), возвращаемых командлетом Get-Service по умолчанию. Он определяет набор элементов с именем PsStandardMembers , состоящий из набора свойств по умолчанию со свойствами Status, Name и DisplayName .

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

<Method>: ссылается на собственный метод базового объекта.

<Methods>: коллекция методов объекта.

ПримечаниеProperty

Определяет свойство со статическим значением.

Тег <NoteProperty> должен иметь <Name> тег, указывающий имя нового свойства и <Value> тег, указывающий значение свойства.

Например, следующий XML создает свойство Status для объектов System.IO.DirectoryInfo . Значение свойства Status всегда имеет значение Success.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <NoteProperty>
      <Name>Status</Name>
      <Value>Success</Value>
    </NoteProperty>
  </Members>
</Type>

PropertySet

Свойства, которые принимают аргументы и возвращают значение.

<Properties>: коллекция свойств объекта.

<Property>: свойство базового объекта.

<PropertySet>: определяет коллекцию свойств объекта.

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

<PropertySet> В Types.ps1xmlтегах используются для определения наборов свойств для отображения объекта по умолчанию. Вы можете определить значения PsStandardMembers по умолчанию в <Name> теге <MemberSet> тега.

Например, следующий XML-код создает СвойствоSet с именем DefaultDisplayPropertySet с тремя ReferencedProperties.

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

ScriptMethod

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

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

Например, ConvertToDateTime методы и ConvertFromDateTime методы объектов управления (System.System.Management.ManagementObject) — это методы скрипта, использующие ToDateTime и ToDmtfDateTime статические методы System.Management.ManagementDateTimeConverter класса.

<Type>
 <Name>System.Management.ManagementObject</Name>
 <Members>
 <ScriptMethod>
   <Name>ConvertToDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDateTime($args[0])
   </Script>
 </ScriptMethod>
 <ScriptMethod>
   <Name>ConvertFromDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($args[0])
   </Script>
 </ScriptMethod>
 </Members>
</Type>

ScriptProperty

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

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

Например, свойство VersionInfo объекта System.IO.FileInfo является свойством скрипта, которое приводит к использованию свойства FullName статического метода GetVersionInfo объектов System.Diagnostics.FileVersionInfo.

<Type>
  <Name>System.IO.FileInfo</Name>
  <Members>
    <ScriptProperty>
      <Name>VersionInfo</Name>
      <GetScriptBlock>
      [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName)
      </GetScriptBlock>
    </ScriptProperty>
  </Members>
</Type>

Дополнительные сведения см. в пакете SDK для Windows PowerShell.

Update-TypeData

Чтобы загрузить Types.ps1xml файлы в сеанс PowerShell, выполните Update-TypeData командлет. Если вы хотите, чтобы типы в файле были приоритетом над типами в встроенном Types.ps1xml файле, добавьте параметр Update-TypeDataPrependData. Update-TypeData влияет только на текущий сеанс. Чтобы внести изменения во все будущие сеансы, экспортировать сеанс или добавить Update-TypeData команду в профиль PowerShell.

Исключения, возникающие в свойствах или добавлении свойств в Update-TypeData команду, не сообщают об ошибках StdErr. Это необходимо для подавления исключений, которые могут возникнуть во многих распространенных типах в процессе форматирования и вывода. При получении свойств .NET можно обойти подавление исключений с помощью синтаксиса метода, как показано в следующем примере:

"hello".get_Length()

Обратите внимание, что синтаксис метода можно использовать только с свойствами .NET. Свойства, добавленные при выполнении командлета Update-TypeData , не могут использовать синтаксис метода.

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

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

См. также