Add-Type
Adiciona uma classe do 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 do Microsoft .NET Core em sua sessão do PowerShell. Em seguida, você pode instanciar objetos usando o New-Object
cmdlet e usar os objetos 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 você 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 de Invocação de Plataforma (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 Add-Type
para especificar uma linguagem e um compilador alternativos, C# é o padrão, opções do compilador, dependências de assembly, o namespace de 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 na 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 ele está usando o código-fonte embutido, o comando usa o parâmetro TypeDefinition para especificar o código na $Source
variável.
O Add
método estático da classe BasicTest usa os caracteres de dois-pontos (::
) para especificar um membro estático da classe . Os inteiros são adicionados e a soma é exibida.
O New-Object
cmdlet cria 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
foram adicionados à sessão. O Get-Member
comando revela que é um objeto System.RuntimeType , que é derivado da classe System.Object .
O Get-Member
parâmetro Estático 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 armazenado na $BasicTestObject
variável.
$BasicTestObject
foi criado usando o New-Object
cmdlet com a classe BasicTest . A saída revela que o valor da $BasicTestObject
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 NJsonSchema.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 em que 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 o assembly correto mesmo quando não tiver certeza do nome ou de sua ortografia. O parâmetro PassThru gera objetos que representam as classes 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 De invocação de plataforma (P/Invoke) para chamar uma função no User32.dll
do 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 esteja visível em uma sessão do PowerShell, o public
palavra-chave foi adicionado à assinatura padrão. Para obter mais informações, consulte Função ShowWindowAsync .
A $ShowWindowAsync
variável armazena o objeto criado pelo Add-Type
parâ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 hospeda 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 4
para a posição da janela, que representa o SW_RESTORE
valor .
Para maximizar a janela, use o valor de 3
que representa SW_MAXIMIZE
.
Parâmetros
-AssemblyName
Especifica o nome de um assembly que inclui os tipos. Add-Type
usa 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
o resolverá para o nome completo e usará o nome completo para carregar o assembly.
Usar os parâmetros Path ou LiteralPath garante que você esteja carregando o assembly que você pretendia carregar. Quando você usa o parâmetro AssemblyName, o PowerShell solicita que o .NET resolve o nome do assembly usando o processo de resolução de assembly padrão do .NET. Como o .NET pesquisa primeiro a pasta do aplicativo, Add-Type
pode carregar um assembly de $PSHOME
em vez da versão na pasta atual. Para obter mais informações, consulte Local do assembly.
Se o .NET não resolve o nome, o PowerShell examinará o local atual para localizar o assembly. Quando você usa curingas no parâmetro AssemblyName , o processo de resolução de assembly do .NET falha ao fazer com que o PowerShell examine o 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 sem revisão para o compilador.
Esse parâmetro permite que você direcione o compilador para gerar um arquivo executável, inserir recursos ou definir opções de linha de comando, como a opção /unsafe
.
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 impedir o Add-Type
tratamento de avisos do compilador como erros.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Language
Especifica a linguagem usada no código-fonte. O valor aceitável para esse 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 ele é digitado. Nenhum caractere é interpretado como caractere 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 você 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 P/Invoke (Invocação de Plataforma) 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. Esse parâmetro é necessário ao gerar um tipo por meio 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 estiver 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 opcional e um nome de arquivo. 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 OutputAssemblyType Enumeration.
Os valores aceitáveis para esse parâmetro são os seguintes:
ConsoleApplication
Library
WindowsApplication
Importante
A partir do PowerShell 7.1, ConsoleApplication
e WindowsApplication
não têm suporte e o PowerShell gera um erro de encerramento se um deles for especificado 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 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
compila o código nos arquivos e cria 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 você 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 depende o tipo. Por padrão, Add-Type
referências System.dll
e System.Management.Automation.dll
. Os assemblies que você especificar usando esse parâmetro são referenciados além os 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 cadeia de caracteres ou cadeia de caracteres here, ou insira uma variável que contenha o código-fonte. Para obter mais informações sobre cadeias de caracteres aqui, 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 Exceção, os scripts que usam Exceção 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 o palavra-chave C#, Using
.
Por padrão, Add-Type
faz referência ao namespace Sistema . 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 mencionados 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
Você não pode canalizar objetos para este cmdlet.
Saídas
None
Por padrão, esse cmdlet não retorna nenhuma saída.
Quando você usa o parâmetro PassThru , esse cmdlet retorna um objeto System.Type que representa o novo tipo.
Observações
Os tipos que você adiciona existem apenas 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.
Nomes de tipo e namespaces devem ser exclusivos em uma sessão. Você não pode descarregar um tipo ou alterá-lo. Se você precisar alterar o código de um tipo, deverá alterar o nome ou iniciar uma nova sessão do PowerShell. Caso contrário, o comando falhará.
Em 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 (Cache de Assembly Global).
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 na 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.
Assemblies no GAC podem ser carregados pelo nome do tipo, em vez de por caminho. O carregamento de assemblies de um caminho arbitrário requer Add-Type
, pois esses assemblies não podem ser carregados automaticamente.