New-Object

Artigo
10/30/2009

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

Sintaxe

New-Object -ComObject <string> [-Strict] [-Property <hashtable>] [<CommonParameters>]

New-Object [-TypeName] <string> [[-ArgumentList] <Object[]>] [-Property <hashtable>] [<CommonParameters>]

Descrição

O cmdlet New-Object 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 .NET Framework e o cmdlet retorna uma referência para 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.

Parâmetros

-ArgumentList <Object[]>

Especifica uma lista de argumentos a serem passados ao construtor da classe .NET Framework. Separe os elementos na lista usando vírgulas (,). O alias para ArgumentList é Args.

Necessário?	false
Posição?	2
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ComObject <string>

Especifica o ProgID (identificador de programação) do objeto COM.

Necessário?	true
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Property <hashtable>

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

Insira uma tabela de hash na qual 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 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 exista no objeto, New-Object acrescentará a propriedade especificada ao objeto como uma NoteProperty. Se o objeto não for um PSObject, o comando gerará um erro de não-encerramento.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Strict

Especifica se um erro deve ser encaminhado se o objeto COM que você tentar criar usar um assembly interop. Isso permite que você faça a distinção entre objetos COM reais de objetos .NET Framework com callable wrappers de COM.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-TypeName <string>

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

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

Nenhum

Você não pode canalizar a entrada para este cmdlet.

Saídas

Object

New-Object retorna o objeto criado.

Observações

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 convertida em $objShell = new-object -comobject "Shell.Application" no Windows PowerShell.

New-Object é ampliado mediante a funcionalidade disponível no ambiente do Windows Script Host, facilitando o trabalho com objetos .NET Framework a partir da linha de comando e nos scripts.

Exemplo 1

C:\PS>new-object -typename System.Version -argumentlist "1.2.3.4" 

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

Descrição
-----------
Esse comando cria um objeto System.Version usando a cadeia de caracteres "1.2.3.4" como o construtor.

Exemplo 2

C:\PS>$ie = new-object -comobject InternetExplorer.Application -property @{navigate2="www.microsoft.com"; visible = $true}

Descrição
-----------
Este comando cria uma instância do objeto COM que representa o aplicativo Internet Explorer. Ele usa o parâmetro Property para chamar o método Navigate2 e definir a propriedade Visible do objeto como $true para tornar o aplicativo visível.

Esse comando é o equivalente do seguinte:

$ie = new-object -comobject InternetExplorer.Application 
$ie.navigate2("www.microsoft.com")
$ie.visible = $true

Exemplo 3

C:\PS>$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 prima
ry interop assembly. If this type exposes different members than the IDispa
tch 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

Descrição
-----------
Esse comando demonstra que a especificação do parâmetro Strict faz com que o cmdlet New-Object gere um erro de não-encerramento quando o objeto COM criado usa um assembly de interoperabilidade.

Exemplo 4

C:\PS>$objshell = new-object -comobject "Shell.Application"

C:\PS> $objshell | get-member

C:\PS> $objshell.ToggleDesktop()

Descrição
-----------
O comando usa o parâmetro ComObject para criar um objeto COM com o ProgID "Shell.Application". Ele armazena o objeto de cultura resultante na variável $objShell.

O segundo comando envia a variável $objShell para o cmdlet Get-Member, que exibe as propriedades e métodos do objeto COM. 

O terceiro comando chama o método ToggleDesktop do objeto para minimizar as janelas abertas em sua área de trabalho.

Consulte também

Conceitos

Compare-Object
Select-Object
Sort-Object
ForEach-Object
Group-Object
Measure-Object
Tee-Object
Where-Object

Compartilhar via