New-Object

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Cria uma instância de um objeto Microsoft .NET Framework ou COM.

Syntax

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

Description

O New-Object cmdlet cria uma instância de um objeto .NET Framework ou COM.

Você pode especificar o tipo de uma classe .NET Framework ou um ProgID de um objeto COM. Por padrão, você digita o nome totalmente qualificado de uma classe do .NET Framework e o cmdlet retorna uma referência a uma instância dessa classe. Para criar uma instância de um objeto COM, use o parâmetro ComObject e especifique o ProgID do objeto como seu valor.

Exemplos

Exemplo 1: Criar um objeto System.Version

Este exemplo cria um objeto System.Version usando a cadeia de caracteres "1.2.3.4" como o construtor.

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

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

Exemplo 2: Criar um objeto COM do Internet Explorer

Este exemplo cria duas instâncias do objeto COM que representa o aplicativo Internet Explorer. A primeira instância usa a tabela de hash do parâmetro Property para chamar o método Navigate2 e definir a propriedade Visible do objeto para $True tornar o aplicativo visível. A segunda instância obtém os mesmos resultados com comandos individuais.

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

Exemplo 3: Use o parâmetro Strict para gerar um erro de não terminação

Este exemplo demonstra que adicionar o parâmetro Strict faz com que o New-Object cmdlet gere um erro de não terminação quando o objeto COM usa um assembly de interoperabilidade.

$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

Exemplo 4: Criar um objeto COM para gerenciar a área de trabalho do Windows

Este exemplo mostra como criar e usar um objeto COM para gerenciar sua área de trabalho do Windows.

O primeiro comando usa o New-Object parâmetro ComObject do cmdlet para criar um objeto COM com o Shell.Application ProgID. Ele armazena o objeto resultante na $ObjShell variável. O segundo comando canaliza a $ObjShell variável para o Get-Member cmdlet, que exibe as propriedades e os métodos do objeto COM. Entre os métodos está o método ToggleDesktop . O terceiro comando chama o método ToggleDesktop do objeto para minimizar as janelas abertas na área de trabalho.

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

Exemplo 5: Passar vários argumentos para um construtor

Este exemplo mostra como criar um objeto com um construtor que usa vários parâmetros. Os parâmetros devem ser colocados em uma matriz ao usar o parâmetro ArgumentList .

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

O PowerShell vincula cada membro da matriz a um parâmetro do construtor.

Nota

Este exemplo usa splatting de parâmetros para facilitar a leitura. Para obter mais informações, consulte about_Splatting.

Exemplo 6: Chamando um construtor que usa uma matriz como um único parâmetro

Este exemplo mostra como criar um objeto com um construtor que usa um parâmetro que é uma matriz ou coleção. O parâmetro array deve ser colocado encapsulado dentro de outra 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

A primeira tentativa de criar o objeto neste exemplo falha. O PowerShell tentou vincular os três membros de $array aos parâmetros do construtor, mas o construtor não usa três parâmetros. O encapsulamento $array em outra matriz impede que o PowerShell tente vincular os três membros de $array aos parâmetros do construtor.

Parâmetros

-ArgumentList

Especifica uma matriz de argumentos para passar para o construtor da classe .NET Framework. Se o construtor usa um único parâmetro que é uma matriz, você deve encapsular esse parâmetro dentro de outra matriz. Por exemplo:

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

Para obter mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

O alias para ArgumentList é Args.

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

-ComObject

Especifica o identificador programático (ProgID) do objeto COM.

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

-Property

Define valores de propriedade e invoca métodos do novo objeto.

Introduza uma tabela hash em que as chaves são os nomes de propriedades ou métodos e os valores são valores de propriedade ou argumentos de método. New-Object cria o objeto e define cada valor de propriedade e invoca cada método na ordem que eles são apresentados na tabela hash.

Se o novo objeto for derivado da classe PSObject e você especificar uma propriedade que não existe no objeto, New-Object adicionará a propriedade especificada ao objeto como NoteProperty. Se o objeto não for um PSObject, o comando gerará um erro de não terminação.

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

-Strict

Indica que o cmdlet gera um erro de não terminação quando um objeto COM que você tenta criar usa um assembly de interoperabilidade. Esse recurso distingue objetos COM reais de objetos do .NET Framework com wrappers chamáveis COM.

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

-TypeName

Especifica o nome totalmente qualificado da classe .NET Framework. Não é possível especificar o parâmetro TypeName e o parâmetro ComObject .

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

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

Object

Este cmdlet retorna o objeto que cria.

Notas

  • New-Object fornece a funcionalidade mais comumente usada da função VBScript CreateObject. Uma instrução como Set objShell = CreateObject("Shell.Application") no VBScript pode ser traduzida para $objShell = New-Object -COMObject "Shell.Application" no PowerShell.
  • New-Object expande a funcionalidade disponível no ambiente Windows Script Host facilitando o trabalho com objetos do .NET Framework a partir da linha de comando e dentro de scripts.