Add-Type

将 Microsoft .NET 类添加到 PowerShell 会话。

语法

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

说明

Add-Type cmdlet 允许在 PowerShell 会话中定义 Microsoft .NET Framework 类。 然后,可以使用 New-Object cmdlet 实例化对象,并像使用任何 .NET Framework 对象一样使用这些对象。 如果将 Add-Type 命令添加到 PowerShell 配置文件中,则该类在所有 PowerShell 会话中均可用。

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

可以使用 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 cmdlet 将类添加到会话中。 因为它使用的是内联源代码,所以该命令使用 TypeDefinition 参数来指定 $Source 变量中的代码。

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

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

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

示例 2:检查添加的类型

此示例使用 Get-Member cmdlet 检查 Add-TypeNew-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.Object 类的 System.RuntimeType 对象。

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

Get-Member cmdlet 获取存储在 $BasicTestObject 变量中的对象的成员。 $BasicTestObject 是通过配合使用 New-Object cmdlet 与 BasicTest 类创建的。 该输出表明 $BasicTestObject 变量的值是 BasicTest 类的实例,并且它包括一个名为 Multiply 的成员。

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

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

$AccType = Add-Type -AssemblyName "accessib*" -PassThru

$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变量存储 PassThru Add-Type 参数创建的对象。 Add-Type cmdlet 将 ShowWindowAsync 函数作为静态方法添加到 PowerShell 会话。 该命令使用 MemberDefinition 参数来指定保存在 $Signature 变量中的方法定义。 该命令使用 NameNamespace 参数来指定类的名称和命名空间。 PassThru 参数生成一个表示类型的对象。

新的 ShowWindowAsync 静态方法用于最小化和还原 PowerShell 控制台的命令中。 该方法采用两个参数:窗口句柄和指定如何显示窗口的整数。

为了最小化 PowerShell 控制台,ShowWindowAsync 结合使用 Get-Process cmdlet 与 $PID 自动变量,以获取托管当前 PowerShell 会话的进程。 然后,它使用当前进程的 MainWindowHandle 属性和表示 SW_MINIMIZE 值的值 2

为了还原窗口,ShowWindowAsync 将值 4 用于窗口位置,它表示 SW_RESTORE 值。

若要最大化窗口,请使用表示 SW_MAXIMIZE 的值 3

示例 5:从 Visual Basic 文件添加类型

此示例使用 Add-Type cmdlet 将在 Hello.vb 文件中定义的 VBFromFile 类添加到当前会话中。 在命令输出中显示 Hello.vb 文件的文本。

Add-Type -Path "C:\PS-Test\Hello.vb"
[VBFromFile]::SayHello(", World")

# From Hello.vb

Public Class VBFromFile
  Public Shared Function SayHello(sourceName As String) As String
    Dim myValue As String = "Hello"
    return myValue + sourceName
  End Function
End Class

Hello, World

Add-Type 使用 Path 参数指定源文件、Hello.vb,并添加文件中定义的类型。 SayHello 函数作为 VBFromFile 类的静态方法调用。

示例 6:添加具有 JScript.NET 的类

此示例使用 JScript.NET 在 PowerShell 会话中创建新类 FRectangle

Add-Type @'
 class FRectangle {
   var Length : double;
   var Height : double;
   function Perimeter() : double {
       return (Length + Height) * 2; }
   function Area() : double {
       return Length * Height;  } }
'@ -Language JScript

$rect = [FRectangle]::new()
$rect

Length Height
------ ------
     0      0

示例 7:添加 F# 编译器

此示例显示了如何使用 Add-Type cmdlet 将 F# 代码编译器添加到你的 PowerShell 会话中。 若要在 PowerShell 中运行此示例,必须有使用 F# 语言安装的 FSharp.Compiler.CodeDom.dll

Add-Type -Path "FSharp.Compiler.CodeDom.dll"
$Provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider
$FSharpCode = @"
let rec loop n =if n <= 0 then () else beginprint_endline (string_of_int n);loop (n-1)end
"@
$FSharpType = Add-Type -TypeDefinition $FSharpCode -CodeDomProvider $Provider -PassThru |
   Where-Object { $_.IsPublic }
$FSharpType::loop(4)

4
3
2
1

Add-Type 使用 Path 参数指定程序集并获取程序集中的类型。 New-Object 创建 F# 代码提供程序的实例,并将结果保存在 $Provider 变量中。 $FSharpCode 变量保存用于定义 Loop 方法的 F# 代码。

$FSharpType变量存储保存在其中$FSharpCode定义的公共类型的 cmdlet 的结果Add-Type。 TypeDefinition 参数指定定义类型的源代码。 CodeDomProvider 参数指定源代码编译器。 PassThru 参数指示 Add-Type 返回表示类型的 Runtime 对象。 对象沿管道向下发送到仅返回公共类型的 Where-Object cmdlet。 因为 F# 提供程序生成了非公共类型,以支持生成的公共类型,所以需使用 Where-Object cmdlet。

Loop 方法作为 $FSharpType 变量中存储的类型的静态方法进行调用。

参数

-AssemblyName

指定包含类型的程序集的名称。 Add-Type 将从指定的程序集中获取类型。 在基于程序集名称创建类型时,此参数是必需的。

输入程序集的完整名称或简单名称(也称为部分名称)。 在程序集名称中允许使用通配符。 如果输入简单或部分名称,则 Add-Type 会将其解析为完整名称,然后使用该完整名称加载程序集。

使用 PathLiteralPath 参数可确保加载要加载的程序集。 使用 AssemblyName 参数时,PowerShell 要求 .NET 使用标准 .NET 程序集解析过程解析程序集名称。 由于 .NET 首先搜索应用程序文件夹, Add-Type 因此可能会从 $PSHOME 当前文件夹中加载程序集而不是版本。 有关详细信息,请参阅 程序集位置

如果 .NET 无法解析名称,PowerShell 将在当前位置查找程序集。 在 AssemblyName 参数中使用通配符时,.NET 程序集解析过程失败,导致 PowerShell 在当前位置查找。

类型:String[]
别名:AN
Position:Named
默认值:None
必需:True
接受管道输入:False
接受通配符:True

-CodeDomProvider

指定代码生成器或编译器。 Add-Type 使用指定的编译器来编译源代码。 默认值为 C# 编译器。 当你要使用一种无法通过 Language 参数指定的语言时,请使用此参数。 你指定的 CodeDomProvider 必须能够从源代码生成程序集。

类型:CodeDomProvider
别名:Provider
Position:Named
默认值:C# compiler
必需:False
接受管道输入:False
接受通配符:False

-CompilerParameters

指定用于源代码编译器的选项。 这些选项无需修改即可发送到编译器。

此参数使你可以指示编译器生成可执行文件、嵌入资源,或设置命令行选项,如 /unsafe 选项。 此参数可实现 CompilerParameters 类 System.CodeDom.Compiler.CompilerParameters

不能在同一命令中使用 CompilerParameters 和 ReferencedAssemblies 参数。

类型:CompilerParameters
别名:CP
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-IgnoreWarnings

忽略编译器警告。 使用此参数防止 Add-Type 将编译器警告作为错误进行处理。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-Language

指定在源代码中使用的语言。 Add-Type cmdlet 使用此参数的值来选择适当的 CodeDomProvider。 默认值为 CSharp。 此参数的可接受值如下所示:

  • CSharp
  • CSharpVersion2
  • CSharpVersion3
  • JScript
  • VisualBasic
类型:Language
接受的值:CSharp, CSharpVersion2, CSharpVersion3, JScript, VisualBasic
Position:Named
默认值:CSharp
必需:False
接受管道输入:False
接受通配符:False

-LiteralPath

指定包含类型的源代码文件或程序集 DLL 文件的路径。 与 Path 不同,LiteralPath 参数的值严格按照所键入的形式使用。 不会将任何字符解释为通配符。 如果路径包括转义符,请将其括在单引号中。 单引号告知 PowerShell 不要将任何字符解释为转义序列。

使用 PathLiteralPath 参数可确保加载要加载的程序集。

类型:String[]
别名:PSPath
Position:Named
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-MemberDefinition

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

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

类型:String[]
Position:1
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-Name

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

类型名称和命名空间在一个会话中必须是唯一的。 不可以卸载或更改类型。 要更改类型的代码,必须更改其名称或启动新的 PowerShell 会话。 否则,该命令将失败。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-Namespace

指定类型的命名空间。

如果命令中未包括此参数,则将在 Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes 命名空间中创建类型。 如果在含有空字符串值或 $Null 值的命令中包括此参数,则将在全局命名空间中生成类型。

类型:String
别名:NS
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-OutputAssembly

在该位置中为具有指定名称的程序集生成 DLL 文件。 输入可选路径和文件名。 允许使用通配符。 默认情况下,Add-Type 仅在内存中生成程序集。

类型:String
别名:OA
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:True

-OutputType

指定输出程序集的输出类型。 默认情况下,不指定输出类型。 仅当命令中指定了输出程序集时,此参数才有效。 有关这些值的详细信息,请参阅 OutputAssemblyType 枚举

此参数的可接受值如下所示:

  • ConsoleApplication
  • Library
  • WindowsApplication
类型:OutputAssemblyType
别名:OT
接受的值:ConsoleApplication, Library, WindowsApplication
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-PassThru

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

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-Path

指定包含类型的源代码文件或程序集 DLL 文件的路径。

如果提交源代码文件,则 Add-Type 将编译这些文件中的代码并创建这些类型的内存中程序集。 在 Path 的值中指定的文件扩展名将确定 Add-Type 使用的编译器。

如果提交程序集文件,则 Add-Type 将获取该程序集中的类型。 若要指定内存中程序集或全局程序集缓存,请使用 AssemblyName 参数。

类型:String[]
Position:0
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-ReferencedAssemblies

指定类型所依赖的程序集。 默认情况下,Add-Type 引用 System.dllSystem.Management.Automation.dll。 除了引用默认程序集之外,还将引用你通过使用此参数指定的程序集。

不能在同一命令中使用 CompilerParameters 和 ReferencedAssemblies 参数。

类型:String[]
别名:RA
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-TypeDefinition

指定包含类型定义的源代码。 以字符串或 here-string 的形式输入源代码或输入一个包含源代码的变量。 有关 here-string 的详细信息,请参阅 about_Quoting_Rules

在类型定义中包括命名空间声明。 如果省略命名空间声明,则你的类型可能会与其他类型或其他类型的快捷方式同名,从而导致意外覆盖。 例如,如果你定义一个名为 Exception 的类型,则将 Exception 用作 System.Exception 的快捷方式的脚本将失败。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-UsingNamespace

指定类所需的其他命名空间。 这非常类似于 C# 关键字 Using

默认情况下,Add-Type 引用 System 命名空间。 当使用 MemberDefinition 参数时,Add-Type 默认情况下还引用 System.Runtime.InteropServices 命名空间。 除了引用默认命名空间之外,还会引用你通过使用 UsingNamespace 参数添加的命名空间。

类型:String[]
别名:Using
Position:Named
默认值:System namespace
必需:False
接受管道输入:False
接受通配符:False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

None

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

Type

使用 PassThru 参数时,此 cmdlet 返回表示新类型的 System.Type 对象。

备注

你添加的类型仅存在当前会话中。 若要在所有会话中使用这些类型,请将它们添加到你的 PowerShell 配置文件中。 有关配置文件的详细信息,请参阅 about_Profiles

类型名称和命名空间在一个会话中必须是唯一的。 不可以卸载或更改类型。 如果需要更改类型的代码,则必须更改其名称或启动新的 PowerShell 会话。 否则,该命令将失败。

某些语言的 CodeDomProvider 类(如 IronPython 和 J#)不生成输出。 因此,采用这些语言编写的类型不能与 Add-Type 一起使用。

此 cmdlet 基于 Microsoft .NET Framework CodeDomProvider 类