New-Object

  • Référence
Module:
Microsoft.PowerShell.Utility

Crée une instance d'un objet Microsoft .NET Framework ou COM.

Syntaxe

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

Description

L’applet New-Object de commande crée une instance d’un objet .NET Framework ou COM.

Vous pouvez spécifier le type d'une classe .NET Framework ou un ProgID d'un objet COM. Par défaut, vous tapez le nom complet d'une classe .NET Framework et l'applet de commande retourne une référence à une instance de cette classe. Pour créer une instance d’un objet COM, utilisez le paramètre ComObject et spécifiez le ProgID de l’objet comme valeur.

Exemples

Exemple 1 : Créer un objet System.Version

Cet exemple crée un objet System.Version à l’aide de la chaîne « 1.2.3.4 » comme constructeur.

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

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

Exemple 2 : Créer un objet COM Internet Explorer

Cet exemple crée deux instances de l’objet COM qui représente l’application Internet Explorer. La première instance utilise la table de hachage du paramètre Property pour appeler la méthode Navigate2 et définir la propriété Visible de l’objet pour $True rendre l’application visible. La deuxième instance obtient les mêmes résultats avec des commandes individuelles.

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

Exemple 3 : Utiliser le paramètre Strict pour générer une erreur sans fin

Cet exemple montre que l’ajout du paramètre Strict entraîne la New-Object génération d’une erreur de non-fin lorsque l’objet COM utilise un assembly d’interopérabilité.

$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

Exemple 4 : Créer un objet COM pour gérer le bureau Windows

Cet exemple illustre comment créer et utiliser un objet COM pour gérer votre Bureau Windows.

La première commande utilise le paramètre ComObject de l’applet New-Object de commande pour créer un objet COM avec Shell.Application ProgID. Il stocke l’objet résultant dans la $ObjShell variable. La deuxième commande canalise la $ObjShell variable vers l’applet Get-Member de commande, qui affiche les propriétés et méthodes de l’objet COM. Parmi les méthodes, il s’agit de la méthode ToggleDesktop . La troisième commande appelle la méthode ToggleDesktop de l’objet pour réduire les fenêtres ouvertes sur votre bureau.

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

Exemple 5 : Passer plusieurs arguments à un constructeur

Cet exemple montre comment créer un objet avec un constructeur qui accepte plusieurs paramètres. Les paramètres doivent être placés dans un tableau lors de l’utilisation du paramètre ArgumentList .

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

PowerShell lie chaque membre du tableau à un paramètre du constructeur.

Remarque

Cet exemple utilise la mise en forme de paramètres pour la lisibilité. Pour plus d’informations, consultez about_Splatting.

Exemple 6 : Appel d’un constructeur qui prend un tableau en tant que paramètre unique

Cet exemple montre comment créer un objet avec un constructeur qui accepte un paramètre qui est un tableau ou une collection. Le paramètre de tableau doit être placé dans un wrapper à l’intérieur d’un autre tableau.

$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

La première tentative de création de l’objet dans cet exemple échoue. PowerShell a tenté de lier les trois membres aux $array paramètres du constructeur, mais le constructeur ne prend pas trois paramètres. $array L’habillage dans un autre tableau empêche PowerShell de tenter de lier les trois membres aux $array paramètres du constructeur.

Paramètres

-ArgumentList

Spécifie un tableau d’arguments à passer au constructeur de la classe .NET Framework. Si le constructeur accepte un paramètre unique qui est un tableau, vous devez encapsuler ce paramètre à l’intérieur d’un autre tableau. Par exemple :

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

Pour plus d’informations sur le comportement d’ArgumentList, consultez about_Splatting.

L’alias de ArgumentList est Args.

Type:Object[]
Alias:Args
Position:1
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ComObject

Spécifie l'identificateur programmatique (ProgID) de l'objet COM.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Property

Définit les valeurs de propriété et appelle les méthodes du nouvel objet.

Entrez une table de hachage dans laquelle les clés sont les noms des propriétés ou des méthodes, et les valeurs sont des valeurs de propriété ou des arguments de méthode. New-Object crée l’objet et définit chaque valeur de propriété et appelle chaque méthode dans l’ordre dans lequel elles apparaissent dans la table de hachage.

Si le nouvel objet est dérivé de la classe PSObject et que vous spécifiez une propriété qui n’existe pas sur l’objet, New-Object ajoute la propriété spécifiée à l’objet en tant que NoteProperty. Si l’objet n’est pas un PSObject, la commande génère une erreur de non-fin.

Type:IDictionary
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Strict

Indique que l’applet de commande génère une erreur non terminée lorsqu’un objet COM que vous tentez de créer utilise un assembly d’interopérabilité. Cette fonctionnalité distingue les objets COM réels des objets .NET Framework avec des wrappers CCW (COM-callable wrapper).

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-TypeName

Spécifie le nom complet de la classe .NET Framework. Vous ne pouvez pas spécifier à la fois le paramètre TypeName et le paramètre ComObject .

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

Object

Cette applet de commande retourne l’objet qu’il crée.

Notes

  • New-Object fournit les fonctionnalités les plus couramment utilisées de la fonction CreateObject VBScript. Une instruction comme Set objShell = CreateObject("Shell.Application") dans VBScript peut être traduite $objShell = New-Object -COMObject "Shell.Application" dans PowerShell.
  • New-Object développe les fonctionnalités disponibles dans l’environnement hôte de script Windows en facilitant l’utilisation d’objets .NET Framework à partir de la ligne de commande et dans les scripts.