Compartilhar via

New-Object

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

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

Sintaxe

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 do .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 como $True para 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: Usar o parâmetro Strict para gerar um erro de não encerramento

Este exemplo demonstra que adicionar o parâmetro Strict faz com que o New-Object cmdlet gere um erro de não encerramento 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 parâmetro ComObject do New-Object 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 associa cada membro da matriz a um parâmetro do construtor.

Observação

Este exemplo usa splatting de parâmetro para legibilidade. 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 dentro de outro array.

$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 associar 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 associar os três membros de $array aos parâmetros do construtor.

Parâmetros

-ArgumentList

Especifica uma matriz de argumentos a serem passados para o construtor da classe .NET Framework. Se o construtor usar um único parâmetro que seja uma matriz, você deverá 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.

Tipo:Object[]
Aliases:Args
Cargo:1
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ComObject

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

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Property

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

Insira uma tabela de hash na qual as chaves são os nomes das 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 em que eles aparecem na tabela de 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 um NoteProperty. Se o objeto não for um PSObject, o comando gerará um erro de não encerramento.

Tipo:IDictionary
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Strict

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TypeName

Especifica o nome totalmente qualificado da classe do .NET Framework. Você não pode especificar o parâmetro TypeName e o parâmetro ComObject .

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

Object

Esse cmdlet retorna o objeto que ele cria.

Observações

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