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 上，您可以使用這項功能，在 PowerShell 中對 Unmanaged 函式進行平台調用（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的非靜態方法。

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

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

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 類別所建立。輸出會顯示變數的值$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會儲存 PassThru 參數所Add-Type建立的物件。 Cmdlet 會將 Add-Type 函式新增 ShowWindowAsync 至 PowerShell 會話做為靜態方法。此命令會使用 MemberDefinition 參數來指定儲存在變數中的 $Signature 方法定義。此命令會 使用 Name 和 Namespace 參數來指定類別的名稱和命名空間。 PassThru 參數會產生代表型別的物件。

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

若要將PowerShell控制台最小化， ShowWindowAsync 請使用 Get-Process Cmdlet 搭配 $PID 自動變數來取得裝載目前 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 查看目前的位置。

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

-CompilerOptions

指定原始碼編譯程式的選項。這些選項會傳送至編譯程式，而不會進行修訂。

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

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 參數的值會與輸入時完全相同。不會將任何字元解譯為通配符。如果路徑包含逸出字元，請以單引弧括住它。單引號會告知PowerShell不要將任何字元解譯為逸出序列。

使用 Path 或 LiteralPath 參數可保證您要載入的元件。

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

-MemberDefinition

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

在 Windows 上，您可以使用這項功能，在 PowerShell 中對 Unmanaged 函式進行平台調用（P/Invoke）呼叫。

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
Library
WindowsApplication

重要

從 PowerShell 7.1 開始， ConsoleApplicationWindowsApplication且不支援，而且如果其中一個值指定為 OutputType 參數的值，則 PowerShell 會擲回終止錯誤。

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 物件，代表已加入的類型。根據預設，此 Cmdlet 不會產生任何輸出。

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

-Path

指定包含型別的原始碼檔案或元件 DLL 檔案的路徑。

如果您提交原始碼檔案， Add-Type 請在檔案中編譯程式代碼，並建立類型的記憶體內部元件。 Path 值中指定的擴展名會決定所使用的編譯程式Add-Type。

使用 Path 或 LiteralPath 參數可保證您要載入的元件。

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 元件。您必須在傳遞至此參數的值中包含它們的特定參考。

Type:	String[]
Aliases:	RA
Position:	Named
Default value:	None
Required:	False
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
Required:	True
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
Required:	False
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

輸入

輸出

備註

相關連結

意見反應

其他資源