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


Add-Type

Добавляет класс 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 эту функцию можно использовать для вызова платформенного вызова (P/Invoke) неуправляемых функций в PowerShell. При указании исходного кода компилирует указанный исходный код Add-Type и создает сборку в памяти, содержащую новые типы .NET Core.

Параметры можно использовать для указания альтернативного языка и компилятора, C# — это параметры Add-Type компилятора, зависимости сборок, пространство имен класса, имена типа и результирующая сборка.

Начиная с 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 .

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

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

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

[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 параметр получает статические свойства и методы класса 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 использует механизм вызова платформы (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 сохраняет сигнатуру ShowWindowAsync C# функции. Чтобы убедиться, что результирующий метод отображается в сеансе PowerShell, public ключевое слово было добавлено в стандартную подпись. Дополнительные сведения см. в разделе "Функция ShowWindowAsync ".

Переменная $ShowWindowAsync сохраняет объект, созданный параметром Add-Type PassThru . Командлет Add-Type добавляет функцию в ShowWindowAsync сеанс PowerShell в качестве статического метода. Команда использует параметр MemberDefinition для указания определения метода, сохраненного в переменной $Signature . Команда использует параметры пространства имен и имен, чтобы указать имя и пространство имен для класса. Параметр 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[]
Aliases:AN
Position:Named
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:True

-CompilerOptions

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

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

Тип:String[]
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-IgnoreWarnings

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

Тип:SwitchParameter
Position:Named
Default value:False
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Language

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

Тип:Language
Допустимые значения:CSharp
Position:Named
Default value:CSharp
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-LiteralPath

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

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

Тип:String[]
Aliases:PSPath, LP
Position:Named
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-MemberDefinition

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

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

Тип:String[]
Position:1
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Name

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

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

Тип:String
Position:0
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Namespace

Задает пространство имен для типа.

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

Тип:String
Aliases:NS
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-OutputAssembly

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

Тип:String
Aliases:OA
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:True

-OutputType

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

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

  • ConsoleApplication
  • Library
  • WindowsApplication

Внимание

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

Тип:OutputAssemblyType
Aliases:OT
Допустимые значения:ConsoleApplication, Library, WindowsApplication
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-PassThru

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

Тип:SwitchParameter
Position:Named
Default value:False
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Path

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

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

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

Тип:String[]
Position:0
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-ReferencedAssemblies

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

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

Тип:String[]
Aliases:RA
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-TypeDefinition

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

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

Тип:String
Position:0
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-UsingNamespace

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

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

Тип:String[]
Aliases:Using
Position:Named
Default value:System namespace
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

Входные данные

None

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

Выходные данные

None

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

Type

При использовании параметра 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, так как эти сборки не могут быть загружены автоматически.