Partilhar via

New-Object

Módulo:
Microsoft.PowerShell.Utility Module

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

Sintaxe

Net (Predefinição) 

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

Com 

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 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 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 Property parameter hash table 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 a adição do 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  <<<< -ComObject 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 ToggleDesktop método. O terceiro comando chama o ToggleDesktop método 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 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.

Observação

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 do $array aos parâmetros do construtor, mas o construtor não usa três parâmetros. Encapsular $array em outra matriz impede que o PowerShell tente vincular os três membros do $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 mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

O alias para ArgumentList é Args.

Propriedades dos parâmetros

Tipo:

Object[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Argumentos

Conjuntos de parâmetros

Net
Position:1
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-ComObject

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

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

Com
Position:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 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, 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.

Propriedades dos parâmetros

Tipo:IDictionary
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

Com
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

Net
Position:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

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.