New-Object

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Crea una instancia de un objeto COM o de Microsoft .NET Framework.

Syntax

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

Description

El New-Object cmdlet crea una instancia de un objeto .NET Framework o COM.

Se puede especificar el tipo de una clase de .NET Framework o un ProgID de un objeto COM. De forma predeterminada, se escribe el nombre completo de una clase de .NET Framework y el cmdlet devuelve una referencia a una instancia de esa clase. Para crear una instancia de un objeto COM, use el parámetro ComObject y especifique el ProgID del objeto como su valor.

Ejemplos

Ejemplo 1: Crear un objeto System.Version

En este ejemplo se crea un objeto System.Version con la cadena "1.2.3.4" como constructor.

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

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

Ejemplo 2: Crear un objeto COM de Internet Explorer

En este ejemplo se crean dos instancias del objeto COM que representa la aplicación internet Explorer. La primera instancia usa la tabla hash de parámetros Property para llamar al método Navigate2 y establecer la propiedad Visible del objeto en $True para que la aplicación sea visible. La segunda instancia obtiene los mismos resultados con comandos individuales.

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

Ejemplo 3: Uso del parámetro Strict para generar un error de no terminación

En este ejemplo se muestra que agregar el parámetro Strict hace que el New-Object cmdlet genere un error de no terminación cuando el objeto COM usa un ensamblado de interoperabilidad.

$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

Ejemplo 4: Crear un objeto COM para administrar el escritorio de Windows

Este ejemplo muestra cómo crear y usar un objeto COM para administrar el escritorio de Windows.

El primer comando usa el parámetro ComObject del New-Object cmdlet para crear un objeto COM con Shell.Application ProgID. Almacena el objeto resultante en la $ObjShell variable . El segundo comando canaliza la $ObjShell variable al Get-Member cmdlet , que muestra las propiedades y los métodos del objeto COM. Entre los métodos se encuentra el método ToggleDesktop . El tercer comando llama al método ToggleDesktop del objeto para minimizar las ventanas abiertas en el escritorio.

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

Ejemplo 5: Pasar varios argumentos a un constructor

En este ejemplo se muestra cómo crear un objeto con un constructor que toma varios parámetros. Los parámetros deben colocarse en una matriz al usar el parámetro ArgumentList .

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

PowerShell enlaza cada miembro de la matriz a un parámetro del constructor.

Nota:

En este ejemplo se usa la expansión de parámetros para mejorar la legibilidad. Para obtener más información, consulte about_Splatting.

Ejemplo 6: Llamada a un constructor que toma una matriz como un único parámetro

En este ejemplo se muestra cómo crear un objeto con un constructor que toma un parámetro que es una matriz o colección. El parámetro de matriz debe colocarse encapsulado dentro de otra matriz.

$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

Se produce un error en el primer intento de crear el objeto en este ejemplo. PowerShell intentó enlazar los tres miembros de $array a los parámetros del constructor, pero el constructor no toma tres parámetros. El ajuste $array en otra matriz impide que PowerShell intente enlazar los tres miembros de $array a los parámetros del constructor.

Parámetros

-ArgumentList

Especifica una matriz de argumentos que se van a pasar al constructor de la clase de .NET Framework. Si el constructor toma un único parámetro que es una matriz, debe encapsular ese parámetro dentro de otra matriz. Por ejemplo:

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

Para obtener más información sobre el comportamiento de ArgumentList, vea about_Splatting.

El alias de ArgumentList es Args.

Type:Object[]
Aliases:Args
Position:1
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ComObject

Especifica el identificador de programación (ProgID) del objeto COM.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Property

Establece los valores de propiedad e invoca los métodos del nuevo objeto.

Especifique una tabla hash en la que las claves sean los nombres de propiedades o métodos y los valores, valores de propiedad o argumentos de método. New-Object crea el objeto y establece cada valor de propiedad e invoca cada método en el orden en que aparecen en la tabla hash.

Si el nuevo objeto se deriva de la clase PSObject y especifica una propiedad que no existe en el objeto , New-Object agrega la propiedad especificada al objeto como NoteProperty. Si el objeto no es un PSObject, el comando genera un error de no terminación.

Type:IDictionary
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Strict

Indica que el cmdlet genera un error de no terminación cuando un objeto COM que intenta crear usa un ensamblado de interoperabilidad. Esta característica distingue los objetos COM reales de objetos de .NET Framework con contenedores COM invocables.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TypeName

Especifica el nombre completo de la clase de .NET Framework. No se puede especificar tanto el parámetro TypeName como el parámetro ComObject .

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

Object

Este cmdlet devuelve el objeto que crea.

Notas

  • New-Object proporciona la funcionalidad más usada de la función CreateObject de VBScript. Una instrucción como Set objShell = CreateObject("Shell.Application") en VBScript se puede traducir a $objShell = New-Object -COMObject "Shell.Application" en PowerShell.
  • New-Object expande la funcionalidad disponible en el entorno host de Script de Windows, ya que facilita el trabajo con objetos de .NET Framework desde la línea de comandos y en los scripts.