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 cmdlet New-Object 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 mithilfe der Zeichenfolge "1.2.3.4" als Konstruktor ein System.Version-Objekt 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. Die erste Instanz verwendet die Property-Parameterhashtabelle, um die Navigate2-Methode aufzurufen und die Visible-Eigenschaft des Objekts auf $True festzulegen, um die Anwendung sichtbar zu machen. 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 parameters Strict bewirkt, dass das Cmdlet New-Object 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

In diesem Beispiel wird gezeigt, wie Sie ein COM-Objekt erstellen und verwenden, um Ihren Windows-Desktop zu verwalten.

Der erste Befehl verwendet den ComObject Parameter des cmdlets New-Object, um ein COM-Objekt mit der Shell.Application ProgID zu erstellen. Es speichert das resultierende Objekt in der $ObjShell Variablen. Mit dem zweiten Befehl wird die $ObjShell Variable an das Cmdlet Get-Member weitergeleitet, das die Eigenschaften und Methoden des COM-Objekts anzeigt. 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 in einem Array platziert werden, wenn ArgumentList Parameter verwendet wird.

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

Anmerkung

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 von $array an Parameter des Konstruktors zu binden, der Konstruktor verwendet jedoch nicht drei Parameter. Das Umschließen $array in einem anderen Array verhindert, dass PowerShell versucht, die drei Member $array an Parameter des Konstruktors 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 programmgesteuerten Bezeichner (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 sind 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, fügt New-Object 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-aufrufbaren Wrappern.

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 parameter TypeName 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 $objShell = New-Object -COMObject "Shell.Application" in PowerShell übersetzt 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.