Add-Type (Microsoft.PowerShell.Utility)

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 cmdlet 允许您在 PowerShell 会话中定义 Microsoft .NET Core 类。然后，您可以使用 New-Object cmdlet 实例化对象，并像使用任何 .NET Core 对象一样使用这些对象。如果您将 Add-Type 命令添加到 PowerShell 配置文件中，则该类在所有 PowerShell 会话中都可用。

您可以通过指定现有程序集或源代码文件来指定类型，也可以指定内联或保存在变量中的源代码。您甚至可以仅指定一个方法，然后 Add-Type 定义并生成该类。在 Windows 上，您可以使用此功能对 PowerShell 中的非托管函数进行平台调用 (P/Invoke) 调用。如果指定源代码，Add-Type 会编译指定的源代码并生成包含新 .NET Core 类型的内存中程序集。

您可以使用 Add-Type 的参数指定备用语言和编译器（默认为 C#）、编译器选项、程序集依赖项、类命名空间、类型名称以及生成的程序集。

从 PowerShell 7 开始，如果已存在同名类型，Add-Type 不会编译类型。此外，Add-Type 会在包含 pwsh.dll 的文件夹下的 ref 文件夹中查找程序集。

示例

示例 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 cmdlet 将类添加到会话中。由于它使用内联源代码，因此该命令使用 TypeDefinition 参数来指定 $Source 变量中的代码。

BasicTest 类的 Add 静态方法使用双冒号字符 (::) 来指定该类的静态成员。整数相加并显示总和。

New-Object cmdlet 实例化 BasicTest 类的实例。它将新对象保存在 $BasicTestObject 变量中。

$BasicTestObject 使用 Multiply 方法。整数相乘并显示乘积。

示例 2：检查添加的类型

此示例使用 Get-Member cmdlet 检查 Add-Type 和 New-Object cmdlet 在示例 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 cmdlet 获取 Add-Type 添加到会话的 BasicTest 类的类型和成员。 Get-Member 命令表明它是一个System.RuntimeType 对象，它派生自System.Object 类。

Get-Member Static 参数获取 BasicTest 类的静态属性和方法。输出显示包含 Add 方法。

Get-Member cmdlet 获取存储在 $BasicTestObject 变量中的对象的成员。 $BasicTestObject 是通过使用 New-Object cmdlet 和 BasicTest 类创建的。输出显示 $BasicTestObject 变量的值是 BasicTest 类的实例，并且它包含一个名为 Multiply 的成员。

示例 3：从程序集中添加类型

此示例将 JsonSchema.NET.dll 程序集中的类添加到当前会话。

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

Set-Location 使用 Path 参数指定 $PSHOME 变量。该变量引用 DLL 文件所在的 PowerShell 安装目录。

$AccType 变量存储使用 Add-Type cmdlet 创建的对象。 Add-Type 使用AssemblyName 参数指定程序集的名称。即使您不确定名称或其拼写，星号 (*) 通配符也可让您获得正确的程序集。 PassThru 参数生成表示添加到会话中的类的对象。

示例 4：调用本机 Windows API

此示例演示如何在 PowerShell 中调用本机 Windows API。 Add-Type 使用平台调用 (P/Invoke) 机制从 PowerShell 调用 User32.dll 中的函数。此示例仅适用于运行 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 cmdlet 将 ShowWindowAsync 函数作为静态方法添加到 PowerShell 会话中。该命令使用 MemberDefinition 参数来指定保存在 $Signature 变量中的方法定义。该命令使用名称和命名空间参数来指定类的名称和命名空间。 PassThru 参数生成一个表示类型的对象。

命令中使用新的 ShowWindowAsync 静态方法来最小化和恢复 PowerShell 控制台。该方法采用两个参数：窗口句柄和指定窗口显示方式的整数。

为了最小化 PowerShell 控制台，ShowWindowAsync 使用带有 $PID 自动变量的 Get-Process cmdlet 来获取托管当前 PowerShell 的进程会议。然后，它使用当前进程的 MainWindowHandle 属性和值 2（代表 SW_MINIMIZE 值）。

为了恢复窗口，ShowWindowAsync 使用值 4 作为窗口位置，该值表示 SW_RESTORE 值。

要最大化窗口，请使用代表 SW_MAXIMIZE 的 3 值。

参数

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

语言

夏普

命名

夏普

False

False

False

-LiteralPath

指定包含类型的源代码文件或程序集 DLL 文件的路径。与 Path 不同，LiteralPath 参数的值完全按照键入的方式使用。没有字符被解释为通配符。如果路径包含转义字符，请将其用单引号引起来。单引号告诉 PowerShell 不要将任何字符解释为转义序列。

使用 Path 或 LiteralPath 参数可确保您加载您想要加载的程序集。

String[]

PSPath, LP

命名

None

True

False

False

-MemberDefinition

指定类的新属性或方法。 Add-Type 生成支持属性或方法所需的模板代码。

在 Windows 上，您可以使用此功能对 PowerShell 中的非托管函数进行平台调用 (P/Invoke) 调用。

String[]

1

None

True

False

False

-Name

指定要创建的类的名称。从成员定义生成类型时需要此参数。

类型名称和命名空间在会话中必须是唯一的。您无法卸载类型或更改它。要更改类型的代码，您必须更改名称或启动新的 PowerShell 会话。否则，命令失败。

String

0

None

True

False

False

-Namespace

指定类型的命名空间。

如果命令中未包含此参数，则会在 Microsoft.PowerShell.Commands.AddType.AutoGenerateTypes 命名空间中创建该类型。如果命令中包含的参数具有空字符串值或 $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，如果将其中任何一个指定为 OutputType 参数的值，则 PowerShell 会引发终止错误。

输出组件类型

OT

控制台应用程序、库、Windows应用程序

命名

None

False

False

False

-PassThru

返回一个 System.Runtime 对象，该对象表示已添加的类型。默认情况下，此 cmdlet 不会生成任何输出。

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

输入

无

您无法将对象通过管道传输到此 cmdlet。

输出

无

默认情况下，此 cmdlet 不返回任何输出。

类型

当您使用 PassThru 参数时，此 cmdlet 将返回表示新类型的 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，因为这些程序集无法自动加载。