Freigeben über

New-Object

  • Referenz
Modul:
Microsoft.PowerShell.Utility

Erstellt eine Instanz eines Microsoft .NET Framework- oder COM-Objekts.

Syntax

New-Object
   [-TypeName] <String>
   [[-ArgumentList] <Object[]>]
   [-Property <IDictionary>]
   [<CommonParameters>]
New-Object
   [-ComObject] <String>
   [-Strict]
   [-Property <IDictionary>]
   [<CommonParameters>]

Beschreibung

Das New-Object Cmdlet erstellt eine Instanz eines .NET Framework- oder COM-Objekts.

Sie können entweder den Typ einer .NET Framework-Klasse oder eine ProgID eines COM-Objekts angeben. Standardmäßig geben Sie den vollqualifizierten Namen einer .NET Framework-Klasse ein, und das Cmdlet gibt einen Verweis auf eine Instanz dieser Klasse zurück. Verwenden Sie zum Erstellen einer Instanz eines COM-Objekts den ComObject-Parameter , und geben Sie die ProgID des Objekts als Wert an.

Beispiele

Beispiel 1: Erstellen eines System.Version-Objekts

In diesem Beispiel wird ein System.Version-Objekt mit der Zeichenfolge "1.2.3.4" als Konstruktor erstellt.

New-Object -TypeName System.Version -ArgumentList "1.2.3.4"

Major  Minor  Build  Revision
-----  -----  -----  --------
1      2      3      4

Beispiel 2: Erstellen eines COM-Objekts in Internet Explorer

In diesem Beispiel werden zwei Instanzen des COM-Objekts erstellt, das die Internet Explorer-Anwendung darstellt. In der ersten Instanz wird die Hashtabelle "Property"- Parameter verwendet, um die Navigate2-Methode aufzurufen und die Visible-Eigenschaft des Objekts so $True festzulegen, dass die Anwendung sichtbar wird. Die zweite Instanz erhält dieselben Ergebnisse mit einzelnen Befehlen.

$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`

Beispiel 3: Verwenden des Strict-Parameters zum Generieren eines nicht beendeten Fehlers

In diesem Beispiel wird veranschaulicht, dass das Hinzufügen des Strict-Parameters bewirkt, dass das New-Object Cmdlet einen nicht beendeten Fehler generiert, wenn das COM-Objekt eine Interopassembly verwendet.

$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

Beispiel 4: Erstellen eines COM-Objekts zum Verwalten des Windows-Desktops

Dieses Beispiel zeigt das Erstellen und Verwenden eines COM-Objekts zur Verwaltung Ihres Windows-Desktops.

Der erste Befehl verwendet den ComObject-Parameter des New-Object Cmdlets, um ein COM-Objekt mit der Shell.Application ProgID zu erstellen. Das resultierende Objekt wird in der $ObjShell Variablen gespeichert. Mit dem zweiten Befehl wird die $ObjShell Variable an das Get-Member Cmdlet weitergeleitet, wodurch die Eigenschaften und Methoden des COM-Objekts angezeigt werden. Zu den Methoden gehört die ToggleDesktop-Methode . Der dritte Befehl ruft die ToggleDesktop-Methode des Objekts auf, um die geöffneten Fenster auf dem Desktop zu minimieren.

$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}

Beispiel 5: Übergeben mehrerer Argumente an einen Konstruktor

In diesem Beispiel wird gezeigt, wie Sie ein Objekt mit einem Konstruktor erstellen, der mehrere Parameter verwendet. Die Parameter müssen bei Verwendung des ArgumentList-Parameters in ein Array gesetzt werden.

$array = @('One', 'Two', 'Three')
$parameters = @{
    TypeName = 'System.Collections.Generic.HashSet[string]'
    ArgumentList = ([string[]]$array, [System.StringComparer]::OrdinalIgnoreCase)
}
$set = New-Object @parameters

PowerShell bindet jedes Element des Arrays an einen Parameter des Konstruktors.

Hinweis

In diesem Beispiel wird die Parametersplatting zur Lesbarkeit verwendet. Weitere Informationen finden Sie unter about_Splatting.

Beispiel 6: Aufrufen eines Konstruktors, der ein Array als einzelner Parameter verwendet

In diesem Beispiel wird gezeigt, wie Sie ein Objekt mit einem Konstruktor erstellen, der einen Parameter verwendet, der ein Array oder eine Auflistung ist. Der Arrayparameter muss in ein anderes Array eingeschlossen werden.

$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

Der erste Versuch, das Objekt in diesem Beispiel zu erstellen, schlägt fehl. PowerShell hat versucht, die drei Member des $array Konstruktors an Parameter zu binden, der Konstruktor verwendet jedoch nicht drei Parameter. Das Umschließen $array in ein anderes Array verhindert, dass PowerShell versucht, die drei Member des $array Konstruktors an Parameter zu binden.

Parameter

-ArgumentList

Gibt ein Array von Argumenten an, das an den Konstruktor der .NET Framework-Klasse übergeben werden soll. Wenn der Konstruktor einen einzelnen Parameter verwendet, der ein Array ist, müssen Sie diesen Parameter innerhalb eines anderen Arrays umschließen. Zum Beispiel:

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate -ArgumentList (,$bytes)

Weitere Informationen zum Verhalten von ArgumentList finden Sie unter about_Splatting.

Der Alias für ArgumentList ist Args.

Typ:Object[]
Aliase:Args
Position:1
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ComObject

Gibt den Programmbezeichner (ProgID) des COM-Objekts an.

Typ:String
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Property

Legt Eigenschaftswerte fest und ruft Methoden des neuen Objekts auf.

Geben Sie eine Hashtabelle ein, in der die Schlüssel die Namen von Eigenschaften oder Methoden und die Werte Eigenschaftswerte oder Methodenargumente sind. New-Object erstellt das Objekt und legt jeden Eigenschaftswert fest und ruft jede Methode in der Reihenfolge auf, in der sie in der Hashtabelle angezeigt werden.

Wenn das neue Objekt von der PSObject-Klasse abgeleitet wird und Sie eine Eigenschaft angeben, die für das Objekt nicht vorhanden ist, New-Object fügt die angegebene Eigenschaft dem Objekt als NoteProperty hinzu. Wenn das Objekt kein PSObject ist, generiert der Befehl einen nicht beendeten Fehler.

Typ:IDictionary
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Strict

Gibt an, dass das Cmdlet einen nicht beendeten Fehler generiert, wenn ein COM-Objekt, das Sie erstellen möchten, eine Interopassembly verwendet. Dieses Feature unterscheidet tatsächliche COM-Objekte von .NET Framework-Objekten mit COM Callable Wrappers.

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-TypeName

Gibt den vollqualifizierten Namen der .NET Framework-Klasse an. Sie können nicht sowohl den TypeName-Parameter als auch den ComObject-Parameter angeben.

Typ:String
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

Object

Dieses Cmdlet gibt das objekt zurück, das es erstellt.

Hinweise

  • New-Object stellt die am häufigsten verwendeten Funktionen der VBScript CreateObject-Funktion bereit. Eine Anweisung wie Set objShell = CreateObject("Shell.Application") in VBScript kann in PowerShell übersetzt $objShell = New-Object -COMObject "Shell.Application" werden.
  • New-Object erweitert die in der Windows Script Host-Umgebung verfügbaren Funktionen, indem es das Arbeiten mit .NET Framework-Objekten über die Befehlszeile und in Skripts erleichtert.