Add-Type
將 Microsoft .NET Framework 型別 (類別) 加入至 Windows PowerShell 工作階段。
語法
Add-Type -AssemblyName <string[]> [-IgnoreWarnings] [-PassThru] [<CommonParameters>]
Add-Type [-Name] <string> [-MemberDefinition] <string[]> [-CodeDomProvider <CodeDomProvider>] [-CompilerParameters <CompilerParameters>] [-Language {<CSharp> | <CSharpVersion3> | <VisualBasic> | <JScript>}] [-Namespace <string>] [-OutputAssembly <string>] [-OutputType <OutputAssemblyType>] [-ReferencedAssemblies <string[]>] [-UsingNamespace <string[]>] [-IgnoreWarnings] [-PassThru] [<CommonParameters>]
Add-Type [-Path] <string[]> [-CompilerParameters <CompilerParameters>] [-OutputAssembly <string>] [-OutputType <OutputAssemblyType>] [-ReferencedAssemblies <string[]>] [-IgnoreWarnings] [-PassThru] [<CommonParameters>]
Add-Type [-TypeDefinition] <string> [-CodeDomProvider <CodeDomProvider>] [-CompilerParameters <CompilerParameters>] [-Language {<CSharp> | <CSharpVersion3> | <VisualBasic> | <JScript>}] [-OutputAssembly <string>] [-OutputType <OutputAssemblyType>] [-ReferencedAssemblies <string[]>] [-IgnoreWarnings] [-PassThru] [<CommonParameters>]
描述
Add-Type Cmdlet 能讓您在 Windows PowerShell 工作階段中定義 .NET Framework 類別。然後您可以具現化物件 (利用 New-Object Cmdlet) 並使用這些物件,就像使用任何 .NET Framework 物件一樣。如果將 Add-Type 命令新增到 Windows PowerShell 設定檔,就可以在所有 Windows PowerShell 工作階段中使用該類別。
您不僅可以透過指定現有的組件或原始程式碼檔來指定型別,也可以指定內嵌原始程式碼或儲存在變數中的原始程式碼。您甚至可以只指定方法,Add-Type 就會定義並產生類別。您可以在 Windows PowerShell 中使用此功能,對 Unmanaged 函數進行平台叫用 (P/Invoke) 呼叫。如果您指定原始程式碼,Add-Type 會編譯指定的原始程式碼,並在記憶體中產生包含新 .NET Framework 型別的組件。
您可以使用 Add-Type 的參數,指定替代語言和編譯器 (預設為 CSharp)、編譯器選項、組件相依性、類別命名空間、型別名稱和產生的組件。
參數
-AssemblyName <string[]>
指定包含型別的組件名稱。Add-Type 會從指定的組件取得型別。當您根據組件名稱建立型別時,必須提供此參數。
請輸入組件的完整名稱或簡單名稱 (也稱為「部分名稱」)。在組件名稱中允許使用萬用字元。如果輸入簡單名稱或部分名稱,Add-Type 會將其解析成完整名稱,然後以完整名稱來載入組件。
此參數不接受路徑或檔名。若要輸入組件動態連結程式庫 (DLL) 檔的路徑,請使用 Path 參數。
必要? |
true |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
true |
-CodeDomProvider <CodeDomProvider>
指定程式碼產生器或編譯器。Add-Type 會以指定的編譯器來編譯原始程式碼。預設為 CSharp 編譯器。如果您使用無法以 Language 參數指定的語言,請使用 CodeDomProvider 參數。您所指定的 CodeDomProvider 必須能夠從原始程式碼產生組件。
必要? |
false |
位置? |
named |
預設值 |
CSharp 編譯器 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-CompilerParameters <CompilerParameters>
為原始程式碼編譯器指定選項。這些選項會在不修改的情況下傳送給編譯器。
此參數可讓您指示編譯器產生可執行檔、嵌入資源或設定命令列選項,例如 "/unsafe" 選項。此參數會實作 CompilerParameters 類別 (System.CodeDom.Compiler.CompilerParameters)。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-IgnoreWarnings
忽略編譯器警告。此參數可用來避免 Add-Type 將編譯器警告當做錯誤。
必要? |
false |
位置? |
named |
預設值 |
False |
接受管線輸入? |
false |
接受萬用字元? |
false |
-Language <Language>
指定原始程式碼中使用的語言。Add-Type 會以語言來選取正確的語言編譯器。
有效的值包括 "CSharp"、"CSharpVersion3"、"VisualBasic" 和 "JScript"。預設為 "CSharp"。
必要? |
false |
位置? |
named |
預設值 |
CSharp |
接受管線輸入? |
false |
接受萬用字元? |
false |
-MemberDefinition <string[]>
為類別指定新的屬性或方法。Add-Type 會產生支援屬性或方法所需的範本程式碼。
您可以在 Windows PowerShell 中使用此功能,對 Unmanaged 函數進行平台叫用 (P/Invoke) 呼叫。如需詳細資訊,請參閱範例。
必要? |
true |
位置? |
2 |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Name <string>
指定要建立的類別名稱。當從成員定義產生型別時,必須提供此參數。
型別名稱和命名空間在工作階段內必須是唯一的。您無法卸載或變更型別。如果需要為型別變更程式碼,則必須變更名稱或啟動新的 Windows PowerShell 工作階段,否則命令會失敗。
必要? |
true |
位置? |
1 |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Namespace <string>
為型別指定命名空間。
如果未在命令中包含此參數,則會在 Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes 命名空間中建立型別。如果在命令中包含此參數並為其加上空字串或 $null 值,則會在全域命名空間中產生型別。
必要? |
false |
位置? |
named |
預設值 |
Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes |
接受管線輸入? |
false |
接受萬用字元? |
false |
-OutputAssembly <string>
為有指定之名稱的組件在位置中產生 DLL 檔。請輸入路徑 (選擇性) 和檔名。允許使用萬用字元。根據預設,Add-Type 只會在記憶體中產生組件。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
true |
-OutputType <OutputAssemblyType>
指定輸出組件的輸出類型。有效的值為 Library、ConsoleApplication 和 WindowsApplication。
根據預設,不會指定任何輸出類型。
只有當命令中指定了輸出組件時,這個參數才有效。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-PassThru
傳回代表已加入之型別的 System.Runtime 物件。根據預設,此 Cmdlet 不會產生任何輸出。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Path <string[]>
指定包含型別的原始程式碼檔或組件 DLL 檔之路徑。
如果您送出原始程式碼檔,Add-Type 會編譯當中的程式碼,並在記憶體中建立型別的組件。Path 的值中指定的副檔名會決定 Add-Type 使用的編譯器。
如果您送出組件檔,Add-Type 會從組件取得型別。若要指定記憶體中的組件或是全域組件快取,請使用 AssemblyName 參數。
必要? |
true |
位置? |
1 |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-ReferencedAssemblies <string[]>
指定型別相依的組件。根據預設,Add-Type 會參考 System.dll 和 System.Management.Automation.dll。除預設組件之外,它還會參考使用此參數所指定的組件。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-TypeDefinition <string>
指定包含型別定義的原始程式碼。請在字串或 here-string 中輸入原始程式碼,或是輸入包含原始程式碼的變數。如需 here-string 的詳細資訊,請參閱 about_Quoting_Rules。
請在您的型別定義中加上命名空間宣告。如果省略命名空間宣告的話,您的型別可能會與另一個型別或另一個型別的捷徑同名,而導致意外覆寫。例如,若定義一個稱為 "Exception" 的型別,則以 "Exception" 當做 System.Exception 之捷徑的指令碼將會失敗。
必要? |
true |
位置? |
1 |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-UsingNamespace <string[]>
指定類別所需的其他命名空間。此參數與 C# 的 "Using" 關鍵字相當類似。
根據預設,Add-Type 會參考 System 命名空間。當使用 MemberDefinition 參數時,Add-Type 預設也會參考 System.Runtime.InteropServices 命名空間。除預設命名空間之外,它還會參考使用 UsingNamespace 參數所新增的命名空間。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
<CommonParameters>
這個 Cmdlet 支援一般參數:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊,請參閱 about_Commonparameters.
輸入和輸出
輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。
輸入 |
無 您無法經由管道將物件輸出至 Add-Type。 |
輸出 |
無或 System.RuntimeType 當您使用 PassThru 參數時,Add-Type 會傳回代表新型別的 System.RuntimeType 物件。否則,這個 Cmdlet 不會產生任何輸出。 |
附註
您所加入的型別只存在於目前的工作階段中。若要在所有工作階段中使用這些型別,請將它們新增到 Windows PowerShell 設定檔。如需設定檔的詳細資訊,請參閱 about_Profiles。
型別名稱 (和命名空間) 在工作階段內必須是唯一的。您無法卸載或變更型別。如果需要為型別變更程式碼,則必須變更名稱或啟動新的 Windows PowerShell 工作階段,否則命令會失敗。
有些語言 (如 IronPython 和 JSharp) 的 CodeDomProvider 類別並不會產生輸出,因此用這些語言撰寫的型別不能與 Add-Type 搭配使用。
此 Cmdlet 是以 CodeDomProvider 類別基礎。如需這個類別的詳細資訊,請參閱 Microsoft .NET Framework SDK。
範例 1
C:\PS>$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);
}
}
"@
C:\PS> Add-Type -TypeDefinition $source
C:\PS> [BasicTest]::Add(4, 3)
C:\PS> $basicTestObject = New-Object BasicTest
C:\PS> $basicTestObject.Multiply(5, 2)
描述
-----------
這些命令會藉由指定儲存在變數中的原始程式碼,將 BasicTest 類別加入至工作階段。型別有一個稱為 Add 的靜態方法,以及一個稱為 Multiply 的非靜態方法。
第一個命令會將類別的原始程式碼儲存到 $source 變數。
第二個命令會使用 Add-Type Cmdlet 將類別新增到工作階段。因為使用的是內嵌原始程式碼,此命令會使用 TypeDefinition 參數指定 $source 變數中的程式碼。
其他命令則會使用新的類別。
第三個命令會呼叫 BasicTest 類別的 Add 靜態方法,並使用雙冒號字元 (::) 指定類別的靜態成員。
第四個命令會使用 New-Object Cmdlet 將 BasicTest 類別的執行個體具現化,然後將新的物件儲存到 $basicTestObject 變數。
第五個命令會使用 $basicTestObject 的 Multiply 方法。
範例 2
C:\PS>[BasicTest] | get-member
C:\PS> [BasicTest] | get-member -static
C:\PS> $basicTestObject | get-member
C:\PS> [BasicTest] | get-member
TypeName: System.RuntimeType
Name MemberType Definition
---- ---------- ----------
Clone Method System.Object Clone()
Equals Method System.Boolean Equals
FindInterfaces Method System.Type[] FindInt
...
C:\PS> [BasicTest] | get-member -static
TypeName: BasicTest
Name MemberType Definition
---- ---------- ----------
Add Method static System.Int32 Add(Int32 a, Int32 b)
Equals Method static System.Boolean Equals(Object objA,
ReferenceEquals Method static System.Boolean ReferenceEquals(Obj
C:\PS> $basicTestObject | get-member
TypeName: BasicTest
Name MemberType Definition
---- ---------- ----------
Equals Method System.Boolean Equals(Object obj)
GetHashCode Method System.Int32 GetHashCode()
GetType Method System.Type GetType()
Multiply Method System.Int32 Multiply(Int32 a, Int32 b)
ToString Method System.String ToString()
描述
-----------
這些命令會使用 Get-Member Cmdlet 查看上一個範例中所建立的 Add-Type 和 New-Object Cmdlet。
第一個命令會使用 Get-Member Cmdlet 取得 Add-Type 新增到工作階段的 BasicTest 類別的型別和成員。Get-Member 命令會顯示這個類別是 System.RuntimeType 物件,後者是從 System.Object 類別衍生而來。
第二個命令會使用 Get-Member 的 Static 參數取得 BasicTest 類別的靜態屬性和方法。輸出會顯示 Add 方法已包含在其中。
第三個命令會使用 Get-Member 取得儲存在 $BasicTestObject 變數中的物件成員。此為物件執行個體,是透過使用 New-Object Cmdlet 搭配 $BasicType 類別建立的。
輸出會顯示 $basicTestObject 變數的值是 BasicTest 類別的執行個體,而且它有一個稱為 Multiply 的成員。
範例 3
C:\PS>$accType = add-type -assemblyname accessib* -passthru
描述
-----------
這個命令會將 Accessibility 組件的類別新增到目前的工作階段,並使用 AssemblyName 參數指定組件的名稱。即使您不確定組件名稱或其拼字,還是可以使用萬用字元取得正確的組件。
這個命令會使用 PassThru 參數產生代表已加入至工作階段之類別的物件,然後將這些物件儲存到 $accType 變數。
範例 4
C:\PS>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
C:\PS> [VBFromFile]::SayHello(", World")
Hello, World
描述
-----------
這個範例會使用 Add-Type Cmdlet 將 Hello.vb 檔案中所定義的 VBFromFile 類別新增到目前的工作階段。Hello.vb 檔案的文字會出現在命令輸出中。
第一個命令會使用 Add-Type Cmdlet 將 Hello.vb 檔案中所定義的型別新增到目前的工作階段,並使用 path 參數指定原始程式檔。
第二個命令會呼叫 SayHello 函數,以做為 VBFromFile 類別的靜態方法。
範例 5
C:\PS>$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 Windows PowerShell console
$showWindowAsync::ShowWindowAsync((Get-Process -id $pid).MainWindowHandle, 2)
# Restore it
$showWindowAsync::ShowWindowAsync((Get-Process -id $pid).MainWindowHandle, 4)
描述
-----------
這個範例中的命令示範如何在 Windows PowerShell 中呼叫原生 Windows API。Add-Type 會使用平台叫用 (P/Invoke) 機制,從 Windows PowerShell 呼叫 User32.dll 中的函數。
第一個命令會將 ShowWindowAsync 函數的 C# 簽章儲存到 $signature 變數 (如需詳細資訊,請參閱 MSDN Library (https://go.microsoft.com/fwlink/?LinkId=143643) 中的<ShowWindowAsync 函數>(英文))。為確保產生的方法會在 Windows PowerShell 工作階段中顯示,"public" 關鍵字已經新增到標準簽章。
第二個命令會使用 Add-Type Cmdlet 將 ShowWindowAsync 函數新增到 Windows PowerShell 工作階段,以做為 Add-Type 所建立之類別的靜態方法。此命令會使用 MemberDefinition 參數指定儲存在 $signature 變數中的方法定義。
也會使用 Name 和 Namespace 參數指定類別的名稱及命名空間,以及使用 PassThru 參數產生代表型別的物件,然後該物件儲存到 $showWindowAsync 變數。
第三個和第四個命令會使用新的 ShowWindowAsync 靜態方法。此方法會接受兩個參數,一個是視窗控制碼,另一個是指定視窗顯示方式的整數。
第三個命令會呼叫 ShowWindowAsync。它會使用 Get-Process Cmdlet 搭配 $pid 自動變數,取得主控目前 Windows PowerShell 工作階段的處理序,然後使用目前處理序的 MainWindowHandle 屬性以及 "2" 這個值,後者代表 SW_MINIMIZE 值。
為了還原視窗,第四個命令會針對視窗位置使用 "4" 這個值,後者代表 SW_RESTORE 值 (SW_MAXIMIZE 為 3)。
範例 6
C:\PS>Add-Type -MemberDefinition $jsMethod -Name "PrintInfo" -Language JScript
描述
-----------
這個命令會使用 Add-Type Cmdlet 將內嵌 JScript 程式碼的方法新增到 Windows PowerShell 工作階段。這個命令會使用 MemberDefinition 參數送出儲存在 $jsMethod 變數中的原始程式碼、使用 Name 變數指定 Add-Type 為方法所建立之類別的名稱,以及使用 Language 參數指定 JScript 語言。
範例 7
C:\PS>Add-Type -Path FSharp.Compiler.CodeDom.dll
C:\PS> Add-Type -Path FSharp.Compiler.CodeDom.dll
C:\PS> $provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider
C:\PS> $fSharpCode = @"
let rec loop n =
if n <= 0 then () else begin
print_endline (string_of_int n);
loop (n-1)
end
"@
C:\PS> $fsharpType = Add-Type -TypeDefinition $fSharpCode -CodeDomProvider $provider -PassThru | where { $_.IsPublic }
C:\PS> $fsharpType::loop(4)
4
3
2
1
描述
-----------
這個範例示範如何使用 Add-Type Cmdlet 將 FSharp 程式碼編譯器新增到 Windows PowerShell 工作階段。若要在 Windows PowerShell 中執行這個範例,必須要有隨 FSharp 語言安裝的 FSharp.Compiler.CodeDom.dll。
這個範例中的第一個命令會使用 Add-Type Cmdlet 搭配 Path 參數來指定組件。Add-Type 會取得該組件中的型別。
第二個命令會使用 New-Object Cmdlet 建立 FSharp 程式碼提供者的執行個體,然後將結果儲存到 $provider 變數。
第三個命令會將定義 Loop 方法的 FSharp 程式碼儲存到 $FSharpCode 變數。
第四個命令會使用 Add-Type Cmdlet 將定義在 $fSharpCode 中的公用型別儲存到 $fSharpType 變數。TypeDefinition 參數會指定定義型別的原始程式碼。CodeDomProvider 參數則會指定原始程式碼編譯器。
PassThru 參數會指示 Add-Type 傳回代表型別的執行階段物件,然後管線運算子 (|) 會將該執行階段物件傳送給 Where-Object Cmdlet,讓後者只傳回公用型別。使用 Where-Object 篩選器,是因為 FSharp 提供者會產生非公用型別來支援產生的公用型別。
第五個命令會呼叫 Loop 方法,以做為儲存在 $fSharpType 變數中之型別的靜態方法。