about_Types.ps1xml

Статья
05/09/2024

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

Объясняется, как использовать 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 , указывающее количество объектов в массиве. Однако, так как имя Length не содержит четкого описания свойства, PowerShell добавляет свойство псевдонима с именем Count , которое отображает то же значение. Следующий XML-код добавляет свойство Count к типу System.Array .

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

Чтобы получить новый AliasProperty, используйте 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 командлет .

Дополнительные сведения см. в разделе 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

XML в файлах Types.ps1xml

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

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

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

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

<Name>: содержит имя затронутого типа .NET.

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

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

ПсевдонимСвойства

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

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

Например, свойство псевдонима Count является псевдонимом для свойства 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> код, в котором определено свойство.

Например, свойство System.IO.DirectoryInfoMode объектов — это свойство кода, определенное в поставщике файловой системы 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>: коллекция методов объекта .

ПримечаниеСвойство

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

Тег <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-код создает набор свойств с именем 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 методы System.Management.ManagementDateTimeConverter и ToDmtfDateTime класса .

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

Дополнительные сведения см. в Windows PowerShell пакет средств разработки программного обеспечения (SDK).

Update-TypeData

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

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

"hello".get_Length()

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

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

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

Поделиться через