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 , которое содержит количество объектов в массиве. Тем не менее, так как имя 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
142
XML в файлах Types.ps1xml
Полное определение схемы можно найти в файле Types.xsd в репозитории исходного кода PowerShell на сайте GitHub.
Тег <Types>
содержит все типы, определенные в файле . Должен быть только один <Types>
тег.
Каждый тип .NET, упомянутый в файле, должен быть представлен тегом <Type>
.
Теги типов должны содержать следующие теги:
<Name>
: содержит имя затронутого типа .NET.
<Members>
: заключает теги для новых свойств и методов, определенных для типа .NET.
Любой из следующих тегов элементов может находиться внутри тега <Members>
.
AliasProperty
Определяет новое имя для существующего свойства.
Тег <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.DirectoryInfo
Mode объектов — это свойство кода, определенное в поставщике Файловой системы 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>
отображаются в основных <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>
Набор свойств
Свойства, которые принимают аргументы и возвращают значение.
<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>
Дополнительные сведения см. в разделе пакет sdk для Windows PowerShell.
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.