Add-Type

Модуль:

Microsoft.PowerShell.Utility

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

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

Примеры

Пример 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 командлетами и 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-MemberStatic получает статические свойства и методы класса BasicTest . В выходных Add данных показано, что метод включен.

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

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

В этом примере классы из сборки NJsonSchema.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);
"@

$ShowWindowAsync = Add-Type -MemberDefinition $Signature -Name "Win32ShowWindowAsync" -Namespace Win32Functions -PassThru

# 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 . Команда использует параметры 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 оно разрешается в полное имя, а затем использует полное имя для загрузки сборки.

Этот параметр не принимает путь или имя файла. Чтобы ввести путь к файлу библиотеки динамической компоновки (DLL) сборки, используйте параметр Path .

Type:	String[]
Aliases:	AN
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	True

-CompilerOptions

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

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

В одной команде нельзя использовать параметры CompilerOptions и ReferencedAssemblies .

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IgnoreWarnings

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Language

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

Type:	Language
Accepted values:	CSharp
Position:	Named
Default value:	CSharp
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-LiteralPath

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

Type:	String[]
Aliases:	PSPath, LP
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MemberDefinition

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

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

Type:	String[]
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

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

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

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Namespace

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

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

Type:	String
Aliases:	NS
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputAssembly

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

Type:	String
Aliases:	OA
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-OutputType

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

Ниже приведены допустимые значения для этого параметра.

• ConsoleApplication
• Библиотека
• Приложение Windows

Важно!

ConsoleApplication Значения и WindowsApplication не создают рабочих выходных данных и не должны использоваться.

Type:	OutputAssemblyType
Aliases:	OT
Accepted values:	ConsoleApplication, Library, WindowsApplication
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

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

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

При отправке файла Add-Type сборки принимает типы из сборки. Чтобы указать сборку в памяти или глобальный кэш сборок, используйте параметр AssemblyName.

Type:	String[]
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ReferencedAssemblies

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

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

Нельзя использовать параметры CompilerOptions и ReferencedAssemblies в одной команде.

Type:	String[]
Aliases:	RA
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TypeDefinition

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

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

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UsingNamespace

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

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

Type:	String[]
Aliases:	Using
Position:	Named
Default value:	System namespace
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

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

None

Вы не можете отправлять объекты по конвейеру в Add-Type.

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

None or System.Type

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

Связанные ссылки

• about_Profiles
• about_Quoting_Rules
• Add-Member
• New-Object
• OutputAssemblyType
• Вызов неуправляемого кода (P/Invoke)
• Where-Object