New-Object
建立 Microsoft .NET Framework 或 COM 物件的執行個體。
Syntax
New-Object
[-TypeName] <String>
[[-ArgumentList] <Object[]>]
[-Property <IDictionary>]
[<CommonParameters>]
New-Object
[-ComObject] <String>
[-Strict]
[-Property <IDictionary>]
[<CommonParameters>]
Description
Cmdlet New-Object
會建立 .NET Framework 或 COM 物件的實例。
您可以指定 .NET Framework 類別的類型或 COM 物件的 ProgID。 根據預設,您需要輸入 .NET Framework 類別的完整名稱,而這個 Cmdlet 會傳回該類別執行個體的參考。 若要建立 COM 物件的實例,請使用 ComObject 參數,並將物件的 ProgID 指定為其值。
範例
範例 1:Create System.Version 物件
這個範例會使用 「1.2.3.4」 字串作為建構函式建立 System.Version 物件。
New-Object -TypeName System.Version -ArgumentList "1.2.3.4"
Major Minor Build Revision
----- ----- ----- --------
1 2 3 4
範例 2:Create Internet Explorer COM 物件
這個範例會建立兩個代表 Internet Explorer 應用程式的 COM 物件實例。 第一個實例會使用 Property 參數哈希表來呼叫 Navigate2 方法,並將 物件的 Visible 屬性設定為 $True
,讓應用程式可見。
第二個實例會使用個別命令取得相同的結果。
$IE1 = New-Object -COMObject InternetExplorer.Application -Property @{Navigate2="www.microsoft.com"; Visible = $True}
# The following command gets the same results as the example above.
$IE2 = New-Object -COMObject InternetExplorer.Application`
$IE2.Navigate2("www.microsoft.com")`
$IE2.Visible = $True`
範例 3:使用 Strict 參數產生非終止錯誤
這個範例示範新增 Strict 參數會導致 New-Object
Cmdlet 在 COM 物件使用 Interop 元件時產生非終止錯誤。
$A = New-Object -COMObject Word.Application -Strict -Property @{Visible = $True}
New-Object : The object written to the pipeline is an instance of the type
"Microsoft.Office.Interop.Word.ApplicationClass" from the component's primary interop assembly. If
this type exposes different members than the IDispatch members, scripts written to work with this
object might not work if the primary interop assembly is not installed.
At line:1 char:14
+ $A = New-Object <<<< -COM Word.Application -Strict; $a.visible=$true
範例 4:Create COM 物件來管理 Windows 桌面
這個範例示範如何建立和使用 COM 物件來管理您的 Windows 桌面。
第一個命令會使用 Cmdlet 的 New-Object
ComObject 參數,使用 Shell.Application ProgID 建立 COM 物件。 它會將產生的物件儲存在變數中 $ObjShell
。 第二個命令會將變數管線傳送 $ObjShell
至 Get-Member
Cmdlet,以顯示 COM 物件的屬性和方法。 在方法中,是 ToggleDesktop 方法。 第三個命令呼叫物件的 ToggleDesktop 方法,將桌面上開啟的視窗最小化。
$Objshell = New-Object -COMObject "Shell.Application"
$objshell | Get-Member
$objshell.ToggleDesktop()
TypeName: System.__ComObject#{866738b9-6cf2-4de8-8767-f794ebe74f4e}
Name MemberType Definition
---- ---------- ----------
AddToRecent Method void AddToRecent (Variant, string)
BrowseForFolder Method Folder BrowseForFolder (int, string, int, Variant)
CanStartStopService Method Variant CanStartStopService (string)
CascadeWindows Method void CascadeWindows ()
ControlPanelItem Method void ControlPanelItem (string)
EjectPC Method void EjectPC ()
Explore Method void Explore (Variant)
ExplorerPolicy Method Variant ExplorerPolicy (string)
FileRun Method void FileRun ()
FindComputer Method void FindComputer ()
FindFiles Method void FindFiles ()
FindPrinter Method void FindPrinter (string, string, string)
GetSetting Method bool GetSetting (int)
GetSystemInformation Method Variant GetSystemInformation (string)
Help Method void Help ()
IsRestricted Method int IsRestricted (string, string)
IsServiceRunning Method Variant IsServiceRunning (string)
MinimizeAll Method void MinimizeAll ()
NameSpace Method Folder NameSpace (Variant)
Open Method void Open (Variant)
RefreshMenu Method void RefreshMenu ()
ServiceStart Method Variant ServiceStart (string, Variant)
ServiceStop Method Variant ServiceStop (string, Variant)
SetTime Method void SetTime ()
ShellExecute Method void ShellExecute (string, Variant, Variant, Variant, Variant)
ShowBrowserBar Method Variant ShowBrowserBar (string, Variant)
ShutdownWindows Method void ShutdownWindows ()
Suspend Method void Suspend ()
TileHorizontally Method void TileHorizontally ()
TileVertically Method void TileVertically ()
ToggleDesktop Method void ToggleDesktop ()
TrayProperties Method void TrayProperties ()
UndoMinimizeALL Method void UndoMinimizeALL ()
Windows Method IDispatch Windows ()
WindowsSecurity Method void WindowsSecurity ()
WindowSwitcher Method void WindowSwitcher ()
Application Property IDispatch Application () {get}
Parent Property IDispatch Parent () {get}
範例 5:將多個自變數傳遞至建構函式
此範例示範如何使用採用多個參數的建構函式來建立 物件。 使用 ArgumentList 參數時,參數必須放在數位中。
$array = @('One', 'Two', 'Three')
$parameters = @{
TypeName = 'System.Collections.Generic.HashSet[string]'
ArgumentList = ([string[]]$array, [System.StringComparer]::OrdinalIgnoreCase)
}
$set = New-Object @parameters
PowerShell 會將數位的每個成員系結至建構函式的參數。
注意
此範例會使用參數展開來讀取。 如需詳細資訊,請參閱 about_Splatting。
範例 6:呼叫採用數位作為單一參數的建構函式
這個範例示範如何使用採用數位或集合之參數的建構函式來建立物件。 陣列參數必須放在另一個數位列內。
$array = @('One', 'Two', 'Three')
# This command throws an exception.
$set = New-Object -TypeName 'System.Collections.Generic.HashSet[string]' -ArgumentList $array
# This command succeeds.
$set = New-Object -TypeName 'System.Collections.Generic.HashSet[string]' -ArgumentList (,[string[]]$array)
$set
New-Object : Cannot find an overload for "HashSet`1" and the argument count: "3".
At line:1 char:8
+ $set = New-Object -TypeName 'System.Collections.Generic.HashSet[strin ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [New-Object], MethodException
+ FullyQualifiedErrorId : ConstructorInvokedThrowException,Microsoft.PowerShell.Commands.NewObjectCommand
One
Two
Three
在此範例中建立物件的第一次嘗試失敗。 PowerShell 嘗試將 的 $array
三個成員系結至建構函式的參數,但建構函式不會採用三個參數。 $array
在另一個數位中包裝可防止 PowerShell 嘗試將 的$array
三個成員系結至建構函式的參數。
參數
-ArgumentList
指定要傳遞至 .NET Framework 類別建構函式的自變數數位。 如果建構函式採用陣列的單一參數,您必須將該參數包裝在另一個數位列內。 例如:
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate -ArgumentList (,$bytes)
如需 ArgumentList 行為的詳細資訊,請參閱 about_Splatting。
ArgumentList 的別名是 Args。
Type: | Object[] |
Aliases: | Args |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ComObject
指定 COM 物件的程式設計識別碼 (ProgID)。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Property
設定屬性值,並叫用新物件的方法。
輸入雜湊表,其中索引鍵為屬性或方法的名稱,而值為屬性值或方法引數。 New-Object
會建立 物件,並設定每個屬性值,並以出現在哈希表中的順序叫用每個方法。
如果新的物件衍生自 PSObject 類別,而且您指定物件上不存在的屬性,請將 New-Object
指定的屬性新增至物件做為 NoteProperty。 如果物件不是 PSObject,命令會產生非終止錯誤。
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Strict
指出當您嘗試建立的 COM 物件使用 Interop 元件時,Cmdlet 會產生非終止錯誤。 這個功能可以區分真正的 COM 物件與使用 COM 可呼叫包裝函式的 .NET Framework 物件。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TypeName
指定 .NET Framework 類別的完整名稱。 您無法同時指定 TypeName 參數和 ComObject 參數。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
輸入
None
您無法使用管線傳送輸入至此 Cmdlet。
輸出
Object
New-Object
會傳回所建立的物件。
備註
New-Object
提供 VBScript CreateObject 函式最常用的功能。 如Set objShell = CreateObject("Shell.Application")
VBScript 中的語句可以在 PowerShell 中轉譯為$objShell = New-Object -COMObject "Shell.Application"
。New-Object
藉由輕鬆地從命令行和腳本內使用 .NET Framework 物件,即可擴充 Windows 腳本主機環境中可用的功能。