Compartilhar via

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 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: Create 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: Create um objeto COM Explorer internet

Este exemplo cria duas instâncias do objeto COM que representa o aplicativo Explorer internet. 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 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: 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: Create 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 redireciona 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 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 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 a modelagem de parâmetros para facilitar a leitura. 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 em 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 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 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 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)

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.

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 noteProperty. Se o objeto não for um PSObject, o comando gerará um erro de não encerramento.

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 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.

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 do .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 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-Objectexpande a funcionalidade disponível no ambiente do Host de Script do Windows, facilitando o trabalho com objetos .NET Framework da linha de comando e dentro de scripts.