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 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 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 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 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 cmdlet New-Object 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 parâmetro ComObject do cmdlet New-Object para criar um objeto COM com o Shell.Application ProgID. Ele armazena o objeto resultante na variável $ObjShell. O segundo comando canaliza a variável $ObjShell para o cmdlet Get-Member, 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 em sua á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 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.

Nota

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

Exemplo 6: chamar 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 de matriz 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 associar os três membros de $array a parâmetros do construtor, mas o construtor não usa três parâmetros. Encapsular $array em outra matriz impede que o PowerShell tente associar os três membros de $array a 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 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.

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 ProgID (identificador programático) 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 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 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 terminação.

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 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 que podem ser chamados por COM.

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 .NET Framework. Não é possível 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

Não é possível redirecionar a entrada para este cmdlet.

Saídas

Object

New-Object retorna o objeto que é criado.

Observações

  • New-Object fornece a funcionalidade mais usada da função CreateObject do VBScript. 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 do Host de Script do Windows facilitando o trabalho com objetos do .NET Framework na linha de comando e nos scripts.