Add-Type

Referência

Módulo:: Microsoft.PowerShell.Utility

Adiciona uma classe Microsoft .NET a uma sessão do PowerShell.

Syntax

Add-Type
   [-TypeDefinition] <String>
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]

Add-Type
   [-Name] <String>
   [-MemberDefinition] <String[]>
   [-Namespace <String>]
   [-UsingNamespace <String[]>]
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]

Add-Type
   [-Path] <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]

Add-Type
   -LiteralPath <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]

Add-Type
   -AssemblyName <String[]>
   [-PassThru]
   [<CommonParameters>]

Description

O Add-Type cmdlet permite definir uma classe Microsoft .NET Core em sua sessão do PowerShell. Em seguida, você pode instanciar objetos, usando o New-Object cmdlet, e usá-los da mesma forma que usaria qualquer objeto .NET Core. Se você adicionar um Add-Type comando ao seu perfil do PowerShell, a classe estará disponível em todas as sessões do PowerShell.

Você pode especificar o tipo especificando um assembly existente ou arquivos de código-fonte, ou pode especificar o código-fonte embutido ou salvo em uma variável. Você pode até mesmo especificar apenas um método e Add-Type define e gera a classe. No Windows, você pode usar esse recurso para fazer chamadas Platform Invoke (P/Invoke) para funções não gerenciadas no PowerShell. Se você especificar o código-fonte, Add-Type compilará o código-fonte especificado e gerará um assembly na memória que contém os novos tipos do .NET Core.

Você pode usar os parâmetros de para especificar uma linguagem alternativa e um compilador, C# é o padrão, opções do compilador, dependências de assembly, o namespace de Add-Type classe, os nomes do tipo e o assembly resultante.

A partir do PowerShell 7, Add-Type não compila um tipo se já existir um tipo com o mesmo nome. Além disso, Add-Type procura assemblies em uma ref pasta sob a pasta que contém pwsh.dll.

Exemplos

Exemplo 1: Adicionar um tipo .NET a uma sessão

Este exemplo adiciona a classe BasicTest à sessão especificando o código-fonte armazenado em uma variável. A classe BasicTest é usada para adicionar inteiros, criar um objeto e multiplicar inteiros.

$Source = @"
public class BasicTest
{
  public static int Add(int a, int b)
    {
        return (a + b);
    }
  public int Multiply(int a, int b)
    {
    return (a * b);
    }
}
"@

Add-Type -TypeDefinition $Source
[BasicTest]::Add(4, 3)
$BasicTestObject = New-Object BasicTest
$BasicTestObject.Multiply(5, 2)

A $Source variável armazena o código-fonte da classe. O tipo tem um método estático chamado Add e um método não estático chamado Multiply.

O Add-Type cmdlet adiciona a classe à sessão. Como está usando código-fonte embutido, o comando usa o parâmetro TypeDefinition para especificar o $Source código na variável.

O Add método estático da classe BasicTest usa os caracteres de dois pontos duplos (::) para especificar um membro estático da classe. Os inteiros são adicionados e a soma é exibida.

O New-Object cmdlet instancia uma instância da classe BasicTest . Ele salva o novo objeto na $BasicTestObject variável.

$BasicTestObject usa o Multiply método. Os inteiros são multiplicados e o produto é exibido.

Exemplo 2: Examinar um tipo adicionado

Este exemplo usa o Get-Member cmdlet para examinar os objetos que os Add-Type cmdlets e New-Object criaram no Exemplo 1.

[BasicTest] | Get-Member

TypeName: System.RuntimeType

Name                 MemberType Definition
----                 ---------- ----------
AsType               Method     type AsType()
Clone                Method     System.Object Clone(), System.Object ICloneable.Clone()
Equals               Method     bool Equals(System.Object obj), bool Equals(type o)
FindInterfaces       Method     type[] FindInterfaces(System.Reflection.TypeFilter filter...
...

[BasicTest] | Get-Member -Static

TypeName: BasicTest

Name            MemberType Definition
----            ---------- ----------
Add             Method     static int Add(int a, int b)
Equals          Method     static bool Equals(System.Object objA, System.Object objB)
new             Method     BasicTest new()
ReferenceEquals Method     static bool ReferenceEquals(System.Object objA, System.Object objB)

$BasicTestObject | Get-Member

TypeName: BasicTest

Name        MemberType Definition
----        ---------- ----------
Equals      Method     bool Equals(System.Object obj)
GetHashCode Method     int GetHashCode()
GetType     Method     type GetType()
Multiply    Method     int Multiply(int a, int b)
ToString    Method     string ToString()

O Get-Member cmdlet obtém o tipo e os membros da classe BasicTest que Add-Type foi adicionada à sessão. O Get-Member comando revela que é um objeto System.RuntimeType , que é derivado da classe System.Object .

O Get-Memberparâmetro Static obtém as propriedades estáticas e os métodos da classe BasicTest . A saída mostra que o Add método está incluído.

O Get-Member cmdlet obtém os membros do objeto armazenados na $BasicTestObject variável. $BasicTestObject foi criado usando o New-Object cmdlet com a classe BasicTest . A saída revela que o $BasicTestObject valor da variável é uma instância da classe BasicTest e que inclui um membro chamado Multiply.

Exemplo 3: Adicionar tipos de um assembly

Este exemplo adiciona as classes do JsonSchema.NET.dll assembly à sessão atual.

Set-Location -Path $PSHOME
$AccType = Add-Type -AssemblyName *jsonschema* -PassThru

Set-Location usa o parâmetro Path para especificar a $PSHOME variável. A variável faz referência ao diretório de instalação do PowerShell onde o arquivo DLL está localizado.

A $AccType variável armazena um objeto criado com o Add-Type cmdlet. Add-Type usa o parâmetro AssemblyName para especificar o nome do assembly. O caractere curinga asterisco (*) permite que você obtenha a montagem correta, mesmo quando você não tem certeza do nome ou de sua ortografia. O parâmetro PassThru gera objetos que representam as classes que são adicionadas à sessão.

Exemplo 4: Chamar APIs nativas do Windows

Este exemplo demonstra como chamar APIs nativas do Windows no PowerShell. Add-Type usa o mecanismo Platform Invoke (P/Invoke) para chamar uma função do User32.dll PowerShell. Este exemplo só funciona em computadores que executam o sistema operacional Windows.

$Signature = @"
[DllImport("user32.dll")]public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow);
"@

$addTypeSplat = @{
    MemberDefinition = $Signature
    Name = "Win32ShowWindowAsync"
    Namespace = 'Win32Functions'
    PassThru = $true
}
$ShowWindowAsync = Add-Type @addTypeSplat

# Minimize the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $pid).MainWindowHandle, 2)

# Restore the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $Pid).MainWindowHandle, 4)

A $Signature variável armazena a assinatura C# da ShowWindowAsync função. Para garantir que o método resultante seja visível em uma sessão do PowerShell, a public palavra-chave foi adicionada à assinatura padrão. Para obter mais informações, consulte Função ShowWindowAsync .

A $ShowWindowAsync variável armazena o objeto criado pelo Add-Typeparâmetro PassThru . O Add-Type cmdlet adiciona a ShowWindowAsync função à sessão do PowerShell como um método estático. O comando usa o parâmetro MemberDefinition para especificar a definição de método salva na $Signature variável. O comando usa os parâmetros Name e Namespace para especificar um nome e um namespace para a classe. O parâmetro PassThru gera um objeto que representa os tipos.

O novo ShowWindowAsync método estático é usado nos comandos para minimizar e restaurar o console do PowerShell. O método usa dois parâmetros: o identificador de janela e um inteiro que especifica como a janela é exibida.

Para minimizar o console do PowerShell, ShowWindowAsync usa o Get-Process cmdlet com a $PID variável automática para obter o processo que está hospedando a sessão atual do PowerShell. Em seguida, ele usa a propriedade MainWindowHandle do processo atual e um valor de 2, que representa o SW_MINIMIZE valor.

Para restaurar a janela, ShowWindowAsync usa um valor de para a posição da 4 janela, que representa o SW_RESTORE valor.

Para maximizar a janela, use o valor que 3 representa SW_MAXIMIZE.

Parâmetros

-AssemblyName

Especifica o nome de um assembly que inclui os tipos. Add-Type Obtém os tipos do assembly especificado. Esse parâmetro é necessário quando você está criando tipos com base em um nome de assembly.

Insira o nome completo ou simples, também conhecido como nome parcial, de um assembly. Caracteres curinga são permitidos no nome do assembly. Se você inserir um nome simples ou parcial, Add-Type resolve-o para o nome completo e, em seguida, usa o nome completo para carregar o assembly.

O uso dos parâmetros Path ou LiteralPath garante que você esteja carregando o assembly que pretendia carregar. Quando você usa o parâmetro AssemblyName, o PowerShell solicita ao .NET para resolver o nome do assembly usando o processo de resolução de assembly .NET padrão. Como o .NET pesquisa a pasta do aplicativo primeiro, Add-Type pode carregar um assembly em vez da $PSHOME versão na pasta atual. Para obter mais informações, consulte Local da montagem.

Se o .NET não conseguir resolver o nome, o PowerShell procurará no local atual para localizar o assembly. Quando você usa curingas no parâmetro AssemblyName , o processo de resolução de assembly .NET falha fazendo com que o PowerShell procure no local atual.

Type:	String[]
Aliases:	AN
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	True

-CompilerOptions

Especifica as opções para o compilador de código-fonte. Essas opções são enviadas para o compilador sem revisão.

Esse parâmetro permite direcionar o compilador para gerar um arquivo executável, incorporar recursos ou definir opções de linha de comando, como a /unsafe opção.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IgnoreWarnings

Ignora os avisos do compilador. Use esse parâmetro para evitar Add-Type que os avisos do compilador sejam manipulados como erros.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Language

Especifica o idioma usado no código-fonte. O valor aceitável para este parâmetro é CSharp.

Type:	Language
Accepted values:	CSharp
Position:	Named
Default value:	CSharp
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-LiteralPath

Especifica o caminho para arquivos de código-fonte ou arquivos DLL de assembly que contêm os tipos. Ao contrário de Path, o valor do parâmetro LiteralPath é usado exatamente como é digitado. Nenhum caractere é interpretado como curinga. Se o caminho incluir caracteres de escape, coloque-o entre aspas simples. Aspas simples dizem ao PowerShell para não interpretar nenhum caractere como sequências de escape.

O uso dos parâmetros Path ou LiteralPath garante que você esteja carregando o assembly que pretendia carregar.

Type:	String[]
Aliases:	PSPath, LP
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MemberDefinition

Especifica novas propriedades ou métodos para a classe. Add-Type gera o código de modelo necessário para dar suporte às propriedades ou métodos.

No Windows, você pode usar esse recurso para fazer chamadas Platform Invoke (P/Invoke) para funções não gerenciadas no PowerShell.

Type:	String[]
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Especifica o nome da classe a ser criada. Este parâmetro é necessário ao gerar um tipo a partir de uma definição de membro.

O nome do tipo e o namespace devem ser exclusivos dentro de uma sessão. Não é possível descarregar um tipo ou alterá-lo. Para alterar o código de um tipo, você deve alterar o nome ou iniciar uma nova sessão do PowerShell. Caso contrário, o comando falhará.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Namespace

Especifica um namespace para o tipo.

Se esse parâmetro não estiver incluído no comando, o tipo será criado no namespace Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Se o parâmetro for incluído no comando com um valor de cadeia de caracteres vazio ou um valor de $Null, o tipo será gerado no namespace global.

Type:	String
Aliases:	NS
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputAssembly

Gera um arquivo DLL para o assembly com o nome especificado no local. Insira um caminho e um nome de arquivo opcionais. Caracteres curinga são permitidos. Por padrão, Add-Type gera o assembly somente na memória.

Type:	String
Aliases:	OA
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-OutputType

Especifica o tipo de saída do assembly de saída. Por padrão, nenhum tipo de saída é especificado. Este parâmetro é válido somente quando um assembly de saída é especificado no comando. Para obter mais informações sobre os valores, consulte Enumeração OutputAssemblyType.

Os valores aceitáveis para este parâmetro são os seguintes:

ConsoleApplication
Library
WindowsApplication

Importante

A partir do PowerShell 7.1, ConsoleApplication e WindowsApplication não são suportados e o PowerShell lança um erro de terminação se ambos forem especificados como valores para o parâmetro OutputType .

Type:	OutputAssemblyType
Aliases:	OT
Accepted values:	ConsoleApplication, Library, WindowsApplication
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

Retorna um objeto System.Runtime que representa os tipos que foram adicionados. Por padrão, esse cmdlet não gera nenhuma saída.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

Especifica o caminho para arquivos de código-fonte ou arquivos DLL de assembly que contêm os tipos.

Se você enviar arquivos de código-fonte, Add-Type compilará o código nos arquivos e criará um assembly na memória dos tipos. A extensão de arquivo especificada no valor de Path determina o compilador que Add-Type usa.

O uso dos parâmetros Path ou LiteralPath garante que você esteja carregando o assembly que pretendia carregar.

Type:	String[]
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ReferencedAssemblies

Especifica os assemblies dos quais o tipo depende. Por padrão, Add-Type referências System.dll e System.Management.Automation.dll. Os assemblies que você especifica usando esse parâmetro são referenciados além dos assemblies padrão.

A partir do PowerShell 6, ReferencedAssemblies não inclui os assemblies .NET padrão. Você deve incluir uma referência específica a eles no valor passado para esse parâmetro.

Type:	String[]
Aliases:	RA
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TypeDefinition

Especifica o código-fonte que contém as definições de tipo. Insira o código-fonte em uma string ou here-string, ou insira uma variável que contenha o código-fonte. Para obter mais informações sobre cadeias de caracteres here, consulte about_Quoting_Rules.

Inclua uma declaração de namespace em sua definição de tipo. Se você omitir a declaração de namespace, seu tipo pode ter o mesmo nome que outro tipo ou o atalho para outro tipo, causando uma substituição não intencional. Por exemplo, se você definir um tipo chamado Exception, os scripts que usam Exception como atalho para System.Exception falharão.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UsingNamespace

Especifica outros namespaces que são necessários para a classe. Isso é muito parecido com a palavra-chave C#, Using.

Por padrão, Add-Type faz referência ao namespace System . Quando o parâmetro MemberDefinition é usado, Add-Type também faz referência ao namespace System.Runtime.InteropServices por padrão. Os namespaces que você adiciona usando o parâmetro UsingNamespace são referenciados além dos namespaces padrão.

Type:	String[]
Aliases:	Using
Position:	Named
Default value:	System namespace
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

Type

Quando você usa o parâmetro PassThru , esse cmdlet retorna um objeto System.Type que representa o novo tipo.

Notas

Os tipos que você adiciona existem somente na sessão atual. Para usar os tipos em todas as sessões, adicione-os ao seu perfil do PowerShell. Para obter mais informações sobre o perfil, consulte about_Profiles.

Os nomes de tipo e namespaces devem ser exclusivos dentro de uma sessão. Não é possível descarregar um tipo ou alterá-lo. Se precisar alterar o código de um tipo, altere o nome ou inicie uma nova sessão do PowerShell. Caso contrário, o comando falhará.

No Windows PowerShell (versão 5.1 e inferior), você precisa usar Add-Type para qualquer coisa que ainda não esteja carregada. Mais comumente, isso se aplica a assemblies encontrados no GAC (Global Assembly Cache). No PowerShell 6 e superior, não há GAC, portanto, o PowerShell instala seus próprios assemblies no $PSHOME. Esses assemblies são carregados automaticamente mediante solicitação, portanto, não há necessidade de usá-los Add-Type para carregá-los. No entanto, o uso Add-Type ainda é permitido para permitir que os scripts sejam implicitamente compatíveis com qualquer versão do PowerShell.

Os assemblies no GAC podem ser carregados pelo nome do tipo, em vez de pelo caminho. O carregamento de assemblies a partir de um caminho arbitrário requer Add-Type, uma vez que esses assemblies não podem ser carregados automaticamente.

Add-Type

Syntax

Description

Exemplos

Exemplo 1: Adicionar um tipo .NET a uma sessão

Exemplo 2: Examinar um tipo adicionado

Exemplo 3: Adicionar tipos de um assembly

Exemplo 4: Chamar APIs nativas do Windows

Parâmetros

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Entradas

Saídas

Notas

Comentários

Recursos adicionais

Add-Type

Syntax

Description

Exemplos

Exemplo 1: Adicionar um tipo .NET a uma sessão

Exemplo 2: Examinar um tipo adicionado

Exemplo 3: Adicionar tipos de um assembly

Exemplo 4: Chamar APIs nativas do Windows

Parâmetros

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Entradas

Saídas

Notas

Ligações Relacionadas

Comentários

Recursos adicionais