Поиск по сайту:

Add-Type (Microsoft.PowerShell.Utility)

Add-Type

Модуль:
Microsoft.PowerShell.Utility

Добавляет класс Microsoft .NET в сеанс PowerShell.

Синтаксис

Add-Type
   [-TypeDefinition] <String>
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   [-Name] <String>
   [-MemberDefinition] <String[]>
   [-Namespace <String>]
   [-UsingNamespace <String[]>]
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   [-Path] <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   -LiteralPath <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   -AssemblyName <String[]>
   [-PassThru]
   [<CommonParameters>]

Описание

Командлет Add-Type позволяет определить класс Microsoft .NET Core в сеансе PowerShell. Затем вы можете создавать экземпляры объектов с помощью командлета New-Object и использовать их так же, как и любой другой объект .NET Core. Если вы добавите команду Add-Type в свой профиль PowerShell, класс будет доступен во всех сеансах PowerShell.

Вы можете указать тип, указав существующую сборку или файлы исходного кода, либо указать исходный код в строке или сохранить его в переменной. Вы даже можете указать только метод, а Add-Type определит и сгенерирует класс. В Windows вы можете использовать эту функцию для выполнения вызовов Platform Invoke (P/Invoke) к неуправляемым функциям в PowerShell. Если вы укажете исходный код, Add-Type компилирует указанный исходный код и создает в памяти сборку, содержащую новые типы .NET Core.

Вы можете использовать параметры Add-Type, чтобы указать альтернативный язык и компилятор, C# используется по умолчанию, параметры компилятора, зависимости сборки, пространство имен классов, имена типов и результирующую сборку.

Начиная с PowerShell 7, Add-Type не компилирует тип, если тип с таким именем уже существует. Кроме того, Add-Type ищет сборки в папке ref внутри папки, содержащей pwsh.dll.

Примеры

Пример 1. Добавление типа .NET в сеанс.

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

$Source = @"
public class BasicTest
{
  public static int Add(int a, int b)
    {
        return (a + b);
    }
  public int Multiply(int a, int b)
    {
    return (a * b);
    }
}
"@

Add-Type -TypeDefinition $Source
[BasicTest]::Add(4, 3)
$BasicTestObject = New-Object BasicTest
$BasicTestObject.Multiply(5, 2)

Переменная $Source хранит исходный код класса. У этого типа есть статический метод Add и нестатический метод Multiply.

Командлет Add-Type добавляет класс в сеанс. Поскольку команда использует встроенный исходный код, она использует параметр TypeDefinition для указания кода в переменной $Source.

Статический метод Add класса BasicTest использует символы двойного двоеточия (::) для указания статического члена класса. Целые числа складываются и отображается сумма.

Командлет New-Object создает экземпляр класса BasicTest. Он сохраняет новый объект в переменной $BasicTestObject.

$BasicTestObject использует метод Multiply. Целые числа умножаются, и отображается результат.

Пример 2. Проверка добавленного типа

В этом примере используется командлет Get-Member для проверки объектов, созданных командлетами Add-Type и New-Object в Примере 1. .

[BasicTest] | Get-Member

TypeName: System.RuntimeType

Name                 MemberType Definition
----                 ---------- ----------
AsType               Method     type AsType()
Clone                Method     System.Object Clone(), System.Object ICloneable.Clone()
Equals               Method     bool Equals(System.Object obj), bool Equals(type o)
FindInterfaces       Method     type[] FindInterfaces(System.Reflection.TypeFilter filter...
...

[BasicTest] | Get-Member -Static

TypeName: BasicTest

Name            MemberType Definition
----            ---------- ----------
Add             Method     static int Add(int a, int b)
Equals          Method     static bool Equals(System.Object objA, System.Object objB)
new             Method     BasicTest new()
ReferenceEquals Method     static bool ReferenceEquals(System.Object objA, System.Object objB)

$BasicTestObject | Get-Member

TypeName: BasicTest

Name        MemberType Definition
----        ---------- ----------
Equals      Method     bool Equals(System.Object obj)
GetHashCode Method     int GetHashCode()
GetType     Method     type GetType()
Multiply    Method     int Multiply(int a, int b)
ToString    Method     string ToString()

Командлет Get-Member получает тип и члены класса BasicTest, который Add-Type добавил в сеанс. Команда Get-Member показывает, что это объект System.RuntimeType, производный от класса System.Object.

Параметр Get-Member Static получает статические свойства и методы класса BasicTest. Вывод показывает, что метод Add включен.

Командлет Get-Member получает элементы объекта, хранящиеся в переменной $BasicTestObject. $BasicTestObject был создан с помощью командлета New-Object с классом BasicTest. Вывод показывает, что значение переменной $BasicTestObject является экземпляром класса BasicTest и включает в себя член с именем Multiply.

Пример 3. Добавление типов из сборки

В этом примере классы из сборки JsonSchema.NET.dll добавляются в текущий сеанс.

Set-Location -Path $PSHOME
$AccType = Add-Type -AssemblyName *jsonschema* -PassThru

Set-Location использует параметр Path для указания переменной $PSHOME. Переменная ссылается на каталог установки PowerShell, в котором находится файл DLL.

Переменная $AccType хранит объект, созданный с помощью командлета Add-Type. Add-Type использует параметр AssemblyName для указания имени сборки. Подстановочный знак звездочки (*) позволяет получить правильную сборку, даже если вы не уверены в имени или его написании. Параметр PassThru создает объекты, представляющие классы, добавляемые в сеанс.

Пример 4. Вызов собственных API-интерфейсов Windows

В этом примере показано, как вызывать собственные API-интерфейсы Windows в PowerShell. Add-Type использует механизм Platform Invoke (P/Invoke) для вызова функции в User32.dll из PowerShell. Этот пример работает только на компьютерах под управлением операционной системы Windows.

$Signature = @"
[DllImport("user32.dll")]public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow);
"@

$addTypeSplat = @{
    MemberDefinition = $Signature
    Name = "Win32ShowWindowAsync"
    Namespace = 'Win32Functions'
    PassThru = $true
}
$ShowWindowAsync = Add-Type @addTypeSplat

# Minimize the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $pid).MainWindowHandle, 2)

# Restore the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $Pid).MainWindowHandle, 4)

Переменная $Signature хранит подпись C# функции ShowWindowAsync. Чтобы гарантировать, что полученный метод будет виден в сеансе PowerShell, к стандартной подписи было добавлено ключевое слово public. Дополнительные сведения см. в разделе Функция ShowWindowAsync.

Переменная $ShowWindowAsync хранит объект, созданный параметром Add-Type PassThru. Командлет Add-Type добавляет функцию ShowWindowAsync в сеанс PowerShell в качестве статического метода. Команда использует параметр MemberDefinition для указания определения метода, сохраненного в переменной $Signature. Команда использует параметры Name и Namespace, чтобы указать имя и пространство имен для класса. Параметр PassThru создает объект, представляющий типы.

Новый статический метод ShowWindowAsync используется в командах для свертывания и восстановления консоли PowerShell. Метод принимает два параметра: дескриптор окна и целое число, определяющее способ отображения окна.

Чтобы свернуть консоль PowerShell, ShowWindowAsync использует командлет Get-Process с автоматической переменной $PID, чтобы получить процесс, в котором размещен текущий PowerShell. сессия. Затем он использует свойство MainWindowHandle текущего процесса и значение 2, которое представляет значение SW_MINIMIZE.

Чтобы восстановить окно, ShowWindowAsync использует значение 4 для позиции окна, которое представляет значение SW_RESTORE.

Чтобы развернуть окно, используйте значение 3, которое представляет SW_MAXIMIZE.

Параметры

-AssemblyName

Указывает имя сборки, включающей типы. Add-Type берет типы из указанной сборки. Этот параметр является обязательным при создании типов на основе имени сборки.

Введите полное или простое имя, также называемое частичным именем сборки. В имени сборки разрешены подстановочные знаки. Если вы вводите простое или частичное имя, Add-Type преобразует его в полное имя, а затем использует полное имя для загрузки сборки.

Использование параметров Path или LiteralPath гарантирует, что вы загружаете именно ту сборку, которую намеревались загрузить. Когда вы используете параметр AssemblyName, PowerShell просит .NET разрешить имя сборки, используя стандартный процесс разрешения сборки .NET. Поскольку .NET сначала выполняет поиск в папке приложения, Add-Type может загрузить сборку из $PSHOME вместо версии в текущей папке. Дополнительные сведения см. в разделе Расположение сборки.

Если .NET не удается разрешить имя, PowerShell ищет сборку в текущем местоположении. Если вы используете подстановочные знаки в параметре AssemblyName, процесс разрешения сборки .NET завершается сбоем, в результате чего PowerShell выполняет поиск в текущем местоположении.

Тип :

String[]

Псевдонимы:

AN

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

True

-CompilerOptions

Указывает параметры компилятора исходного кода. Эти опции отправляются компилятору без доработки.

Этот параметр позволяет вам указать компилятору сгенерировать исполняемый файл, внедрить ресурсы или установить параметры командной строки, такие как параметр /unsafe.

Тип :

String[]

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-IgnoreWarnings

Игнорирует предупреждения компилятора. Используйте этот параметр, чтобы запретить Add-Type обрабатывать предупреждения компилятора как ошибки.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

False

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Language

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

Тип :

Язык

Принятые значения:

CSharp

Позиция:

Именованный

Значение по умолчанию:

CSharp

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-LiteralPath

Указывает путь к файлам исходного кода или файлам DLL сборки, содержащим эти типы. В отличие от Path, значение параметра LiteralPath используется точно так, как оно введено. Никакие символы не интерпретируются как подстановочные знаки. Если путь содержит escape-символы, заключите его в одинарные кавычки. Одинарные кавычки сообщают PowerShell не интерпретировать никакие символы как escape-последовательности.

Использование параметров Path или LiteralPath гарантирует, что вы загружаете именно ту сборку, которую намеревались загрузить.

Тип :

String[]

Псевдонимы:

PSPath, LP

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-MemberDefinition

Указывает новые свойства или методы класса. Add-Type генерирует код шаблона, необходимый для поддержки свойств или методов.

В Windows вы можете использовать эту функцию для выполнения вызовов Platform Invoke (P/Invoke) к неуправляемым функциям в PowerShell.

Тип :

String[]

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Name

Указывает имя создаваемого класса. Этот параметр необходим при создании типа из определения члена.

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

Тип :

String

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Namespace

Указывает пространство имен для типа.

Если этот параметр не включен в команду, тип создается в пространстве имен Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes. Если параметр включен в команду с пустым строковым значением или значением $Null, тип создается в глобальном пространстве имен.

Тип :

String

Псевдонимы:

NS

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-OutputAssembly

Создает файл DLL для сборки с указанным именем в расположении. Введите необязательный путь и имя файла. Допускаются подстановочные знаки. По умолчанию Add-Type создает сборку только в памяти.

Тип :

String

Псевдонимы:

OA

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

True

-OutputType

Указывает тип вывода выходной сборки. По умолчанию тип вывода не указан. Этот параметр допустим только в том случае, если в команде указана выходная сборка. Дополнительные сведения о значениях см. в разделе Перечисление OutputAssemblyType.

Допустимые значения этого параметра следующие:

    ConsoleApplication
    Library
    WindowsApplication

Это важно

Начиная с PowerShell 7.1, ConsoleApplication и WindowsApplication не поддерживаются, и PowerShell выдает завершающую ошибку, если какое-либо из них указано в качестве значений для параметра OutputType.

Тип :

Выходная сборкатипе

Псевдонимы:

OT

Принятые значения:

Консольное приложение, библиотека, Windows-приложение

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-PassThru

Возвращает объект System.Runtime, представляющий добавленные типы. По умолчанию этот командлет не генерирует никаких выходных данных.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

False

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Path

Указывает путь к файлам исходного кода или файлам DLL сборки, содержащим эти типы.

Если вы отправляете файлы исходного кода, Add-Type компилирует код в файлах и создает в памяти сборку типов. Расширение файла, указанное в значении Path, определяет компилятор, который использует Add-Type.

Использование параметров Path или LiteralPath гарантирует, что вы загружаете именно ту сборку, которую намеревались загрузить.

Тип :

String[]

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-ReferencedAssemblies

Указывает сборки, от которых зависит тип. По умолчанию Add-Type ссылается на System.dll и System.Management.Automation.dll. Сборки, указанные с помощью этого параметра, упоминаются в дополнение к сборкам по умолчанию.

Начиная с PowerShell 6, ReferencedAssemblies не включает сборки .NET по умолчанию. Вы должны включить конкретную ссылку на них в значение, передаваемое этому параметру.

Тип :

String[]

Псевдонимы:

RA

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-TypeDefinition

Указывает исходный код, содержащий определения типов. Введите исходный код в виде строки или здесь-строки либо введите переменную, содержащую исходный код. Дополнительные сведения о строках см. в разделе about_Quoting_Rules.

Включите объявление пространства имен в определение типа. Если вы опустите объявление пространства имен, ваш тип может иметь то же имя, что и другой тип, или ярлык для другого типа, что приведет к непреднамеренной перезаписи. Например, если вы определите тип под названием Exception, сценарии, использующие Exception в качестве ярлыка для System.Exception, завершатся ошибкой.

Тип :

String

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-UsingNamespace

Указывает другие пространства имен, необходимые для класса. Это очень похоже на ключевое слово C# Using.

По умолчанию Add-Type ссылается на пространство имен System. Когда используется параметр MemberDefinition, Add-Type также по умолчанию ссылается на пространство имен System.Runtime.InteropServices. Пространства имен, добавляемые с помощью параметра UsingNamespace, упоминаются в дополнение к пространствам имен по умолчанию.

Тип :

String[]

Псевдонимы:

Using

Позиция:

Именованный

Значение по умолчанию:

Системное пространство имен

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

Нет

Вы не можете передавать объекты в этот командлет.

Выходы

Нет

По умолчанию этот командлет не возвращает никаких результатов.

Тип

При использовании параметра PassThru этот командлет возвращает объект System.Type, представляющий новый тип.

Примечания

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

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

В Windows PowerShell (версии 5.1 и ниже) вам необходимо использовать Add-Type для всего, что еще не загружено. Чаще всего это относится к сборкам, найденным в глобальном кэше сборок (GAC). В PowerShell 6 и более поздних версиях GAC отсутствует, поэтому PowerShell устанавливает собственные сборки в $PSHOME. Эти сборки автоматически загружаются по запросу, поэтому для их загрузки нет необходимости использовать Add-Type. Однако использование Add-Type по-прежнему разрешено, чтобы обеспечить неявную совместимость сценариев с любой версией PowerShell.

Сборки в GAC можно загружать по имени типа, а не по пути. Для загрузки сборок по произвольному пути требуется Add-Type, поскольку эти сборки не могут быть загружены автоматически.