將 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 compiler

接受管線輸入?

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 所傳回的物件型別。

輸入

None

您無法經由管道將物件輸出至 Add-Type。

輸出

None 或 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 變數中之型別的靜態方法。






請參閱




目錄