Add-Type

參考

模組:: Microsoft.PowerShell.Utility

將Microsoft .NET 類別新增至 PowerShell 會話。

Syntax

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

Description

Cmdlet Add-Type 可讓您在 PowerShell 會話中定義Microsoft .NET Core 類別。接著，您可以使用 Cmdlet 來具現化物件 New-Object ，並使用物件，就像使用任何 .NET Core 物件一樣。如果您將命令新增 Add-Type 至 PowerShell 設定檔，則類別適用于所有 PowerShell 會話。

您可以透過指定現有組件或原始程式碼檔案來指定類型，或者指定變數中內嵌或預存的原始程式碼。您甚至可以只指定方法，並 Add-Type 定義並產生類別。在 Windows 上，您可以使用這項功能，讓 Platform Invoke (P/Invoke) PowerShell 中的 Unmanaged 函式呼叫。如果您指定原始程式碼， 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 的非靜態方法。

Cmdlet Add-Type 會將類別新增至會話。因為其使用內嵌原始程式碼，所以命令會使用 TypeDefinition 參數來指定變數中的 $Source 程式碼。

AddBasicTest類別的靜態方法會使用雙冒號字元 () :: 來指定類別的靜態成員。會加入整數，並顯示總和。

Cmdlet New-Object 會具現化 BasicTest 類別的實例。它會將新物件儲存在變數中 $BasicTestObject 。

$BasicTestObjectMultiply會使用方法。整數會相乘，並顯示乘積。

範例 2：檢查新增的類型

此範例會 Get-Member 使用 Cmdlet 來檢查範例 1中建立的 Add-Type 和 New-Object Cmdlet 物件。

[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()

Cmdlet Get-Member 會取得新增至會話之 BasicTest 類別 Add-Type 的類型和成員。此命令 Get-Member 會顯示它是 System.RuntimeType 物件，其衍生自 System.Object 類別。

Get-MemberStatic參數會取得BasicTest類別的靜態屬性和方法。輸出會顯示 Add 方法已包含。

Cmdlet Get-Member 會取得儲存在變數中的 $BasicTestObject 物件成員。 $BasicTestObject 是使用 New-Object Cmdlet 搭配 BasicTest 類別所建立。輸出會顯示變數的值是BasicTest類別的 $BasicTestObject 實例，而且它包含名為 Multiply 的成員。

範例 3：從元件新增類型

本範例會將元件中的 NJsonSchema.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 會使用 Platform Invoke (P/Invoke) 機制，從 PowerShell 呼叫中的 User32.dll 函式。此範例僅適用于執行 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 會儲存PassThru參數所 Add-Type 建立的物件。 Cmdlet 會將 Add-Type 函 ShowWindowAsync 式新增至 PowerShell 會話作為靜態方法。此命令會使用 MemberDefinition 參數來指定儲存在變數中的 $Signature 方法定義。此命令會使用 Name 和 Namespace 參數指定類別的名稱和命名空間。 PassThru參數會產生代表型別的物件。

新的 ShowWindowAsync 靜態方法用於命令中，以最小化和還原 PowerShell 主控台。方法會採用兩個參數：視窗控制碼，以及指定視窗顯示方式的整數。

若要將 PowerShell 主控台最小化， ShowWindowAsync 請使用 Get-Process Cmdlet 搭配 $PID 自動變數來取得裝載目前 PowerShell 會話的程式。然後它會使用目前進程的MainWindowHandle屬性，以及代表 SW_MINIMIZE 值的值 2 。

若要還原視窗， ShowWindowAsync 請使用的值 4 作為視窗位置的值，代表 SW_RESTORE 值。

若要最大化視窗，請使用代表 SW_MAXIMIZE 的值 3 。

參數

-AssemblyName

指定包含類型之組件的名稱。 Add-Type 會從指定的元件取得型別。當您根據元件名稱建立類型時，需要此參數。

輸入元件的完整或簡單名稱，也稱為部分名稱。組件名稱允許使用萬用字元。如果您輸入簡單或部分名稱， Add-Type 請將它解析為完整名稱，然後使用完整名稱載入元件。

此參數不接受路徑或檔案名。若要輸入元件動態連結程式庫 (DLL) 檔案的路徑，請使用 Path 參數。

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

-CompilerOptions

指定原始程式碼編譯器的選項。這些選項會在不經過修訂的情況下傳送至編譯器。

此參數可讓您指示編譯器產生可執行檔、內嵌資源或設定命令列選項，例如 /unsafe 選項。

您無法在同一個命令中使用 CompilerOptions 和 ReferencedAssemblies 參數。

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

-IgnoreWarnings

忽略編譯器警告。使用此參數可防止 Add-Type 將編譯器警告當做錯誤來處理。

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

-Language

指定在原始程式碼中使用的語言。此參數可接受的值為

CSharp

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

-LiteralPath

指定包含類型之原始程式碼檔案或組件 DLL 檔案的路徑。不同于 Path， LiteralPath 參數的值會與輸入時完全相同。沒有字元會被視為萬用字元。如果路徑包含逸出字元，請將它括在單引號中。單引號會指示 PowerShell 不要將任何字元解譯為逸出序列。

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

-MemberDefinition

為類別指定新的屬性或方法。 Add-Type 會產生支援屬性或方法所需的範本程式碼。

在 Windows 上，您可以使用這項功能，讓 Platform Invoke (P/Invoke) PowerShell 中的 Unmanaged 函式呼叫。

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

-Name

指定要建立之類別的名稱。從成員定義產生類型時，此參數是必要的。

類別名稱和命名空間在工作階段中必須是唯一的。您無法卸載類型或加以變更。若要變更類型的程式碼，您必須變更名稱或啟動新的 PowerShell 會話。否則命令會失敗。

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

-Namespace

指定類型的命名空間。

如果此命令中未包含此參數，則會在Microsoft中建立類型。PowerShell.Commands.AddType.AutoGeneratedTypes命名空間。如果參數包含在命令中，且具有空字串值或的值 $Null ，則會在全域命名空間中產生類型。

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

-OutputAssembly

使用位置中的指定名稱來產生組件的 DLL 檔。輸入選擇性路徑和檔案名。允許使用萬用字元。根據預設， Add-Type 只會在記憶體中產生元件。

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

-OutputType

指定輸出組件的輸出類型。預設不會指定任何輸出類型。此參數只有在命令中已指定輸出組件時才有效。如需值的詳細資訊，請參閱 OutputAssemblyType 列舉。

此參數可接受的值如下所示：

ConsoleApplication
Library
WindowsApplication

重要

自 PowerShell 7.1 起， ConsoleApplication 且不支援， WindowsApplication 而且如果其中一個指定為 OutputType 參數的值，則 PowerShell 會擲回終止錯誤。

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

-PassThru

傳回代表已新增之類型的 System.Runtime 物件。根據預設，此 Cmdlet 不會產生任何輸出。

Type:	SwitchParameter
Position:	Named
Default value:	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
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
Accept pipeline input:	False
Accept wildcard characters:	False

-TypeDefinition

指定包含類型定義的原始程式碼。以字串或 here-string 輸入原始程式碼，或者輸入包含原始程式碼的變數。如需 here-strings 的詳細資訊，請參閱 about_Quoting_Rules。

在您的類型定義中包含命名空間宣告。如果您省略命名空間宣告，您的類型的名稱可能會與其他類型或其他類型的捷徑名稱相同，這會造成意外覆寫。例如，如果您定義稱為 Exception的類型，使用 Exception 作為 System.Exception 快捷方式的腳本將會失敗。

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

-UsingNamespace

指定類別需要的其他命名空間。這與 C# 關鍵字 Using 非常類似。

根據預設， Add-Type 會參考系統命名空間。使用 MemberDefinition 參數時， Add-Type 也預設會參考 System.Runtime.InteropServices 命名空間。除了參照預設命名空間之外，也會參照您使用 UsingNamespace 參數新增的命名空間。

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

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

根據預設，此 Cmdlet 不會傳回任何輸出。

Type

當您使用 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 ，因為這些元件無法自動載入。

Add-Type

Syntax

Description

範例

範例 1：將 .NET 類型新增至會話

範例 2：檢查新增的類型

範例 3：從元件新增類型

範例 4：呼叫原生 Windows API

參數

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

輸入

輸出

備註

意見反應

其他資源

Add-Type

Syntax

Description

範例

範例 1：將 .NET 類型新增至會話

範例 2：檢查新增的類型

範例 3：從元件新增類型

範例 4：呼叫原生 Windows API

參數

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

輸入

輸出

備註

相關連結

意見反應

其他資源