Add-Type

Referência

Módulo:: Microsoft.PowerShell.Utility

Adiciona uma classe .NET Microsoft 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-lhe definir uma classe Microsoft .NET Core na sua sessão do PowerShell. Em seguida, pode instanciar objetos com o New-Object cmdlet e utilizar os objetos tal como utilizaria qualquer objeto .NET Core. Se adicionar um Add-Type comando ao seu perfil do PowerShell, a classe estará disponível em todas as sessões do PowerShell.

Pode especificar o tipo ao especificar uma assemblagem ou ficheiros de código fonte existentes ou pode especificar o código fonte inline ou guardado numa variável. Pode até especificar apenas um método e Add-Type define e gera a classe . No Windows, pode utilizar esta funcionalidade para fazer chamadas de Invocação de Plataforma (P/Invocar) para funções não geridas no PowerShell. Se especificar o código fonte, Add-Type compila o código fonte especificado e gera uma assemblagem dentro da memória que contém os novos tipos de .NET Core.

Pode utilizar os parâmetros de Add-Type para especificar um idioma e compilador alternativos, C# é a predefinição, opções de compilador, dependências de assemblagem, o espaço de nomes da classe, os nomes do tipo e a assemblagem 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 assemblagens numa 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 ao especificar o código fonte armazenado numa variável. A classe BasicTest é utilizada para adicionar números inteiros, criar um objeto e multiplicar números 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. Uma vez que está a utilizar código fonte inline, o comando utiliza o parâmetro TypeDefinition para especificar o código na $Source variável .

O Add método estático da classe BasicTest utiliza os carateres de dois pontos (::) para especificar um membro estático da classe . Os números inteiros são adicionados e a soma é apresentada.

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

$BasicTestObject utiliza o Multiply método . Os números inteiros são multiplicados e o produto é apresentado.

Exemplo 2: Examinar um tipo adicionado

Este exemplo utiliza 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 se trata de um objeto System.RuntimeType , 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. O resultado 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 com o New-Object cmdlet com a classe BasicTest . O resultado 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 a partir de uma assemblagem

Este exemplo adiciona as classes da NJsonSchema.dll assemblagem à sessão atual.

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

Set-Location utiliza 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 está localizado o ficheiro DLL.

A $AccType variável armazena um objeto criado com o Add-Type cmdlet . Add-Type utiliza o parâmetro AssemblyName para especificar o nome da assemblagem. O caráter universal asterisco (*) permite-lhe obter a assemblagem correta mesmo quando não tem a certeza do nome ou da 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 utiliza o mecanismo Invocação de Plataforma (P/Invocar) para chamar uma função do User32.dll PowerShell. Este exemplo só funciona em computadores com o sistema operativo Windows.

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

$ShowWindowAsync = Add-Type -MemberDefinition $Signature -Name "Win32ShowWindowAsync" -Namespace Win32Functions -PassThru

# 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 está visível numa sessão do PowerShell, a public palavra-chave foi adicionada à assinatura padrão. Para obter mais informações, veja ShowWindowAsync function (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 utiliza o parâmetro MemberDefinition para especificar a definição do método guardada na $Signature variável . O comando utiliza os parâmetros Nome e Espaço de Nomes para especificar um nome e espaço de nomes para a classe. O parâmetro PassThru gera um objeto que representa os tipos.

O novo ShowWindowAsync método estático é utilizado nos comandos para minimizar e restaurar a consola do PowerShell. O método utiliza dois parâmetros: a alça da janela e um número inteiro que especifica a forma como a janela é apresentada.

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

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

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

Parâmetros

-AssemblyName

Especifica o nome de uma assemblagem que inclui os tipos. Add-Type utiliza os tipos da assemblagem especificada. Este parâmetro é necessário quando está a criar tipos com base num nome de assemblagem.

Introduza o nome completo ou simples, também conhecido como o nome parcial, de uma assemblagem. Os carateres universais são permitidos no nome da assemblagem. Se introduzir um nome simples ou parcial, Add-Type resolve-o com o nome completo e, em seguida, utiliza o nome completo para carregar a assemblagem.

Este parâmetro não aceita um caminho ou um nome de ficheiro. Para introduzir o caminho para o ficheiro DLL (dynamic-link library) de assemblagem, utilize o parâmetro Path .

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

-CompilerOptions

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

Este parâmetro permite-lhe direcionar o compilador para gerar um ficheiro executável, incorporar recursos ou definir opções de linha de comandos, como a opção /unsafe .

Não pode utilizar os parâmetros CompilerOptions e ReferencedAssemblies no mesmo comando.

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

-IgnoreWarnings

Ignora os avisos do compilador. Utilize este parâmetro para impedir Add-Type o processamento de avisos do compilador como erros.

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

-Language

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

CSharp

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

-LiteralPath

Especifica o caminho para ficheiros de código fonte ou ficheiros DLL de assemblagem que contêm os tipos. Ao contrário de Path, o valor do parâmetro LiteralPath é utilizado exatamente como é escrito. Nenhum caráter é interpretado como carateres universais. Se o caminho incluir carateres de escape, coloque-o entre aspas. As aspas únicas indicam ao PowerShell para não interpretar os carateres como sequências de escape.

Type:	String[]
Aliases:	PSPath, LP
Position:	Named
Default value:	None
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 suportar as propriedades ou métodos.

No Windows, pode utilizar esta funcionalidade para fazer chamadas de Invocação da Plataforma (P/Invoke) para funções não geridas no PowerShell.

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

-Name

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

O nome do tipo e o espaço de nomes têm de ser exclusivos numa sessão. Não pode descarregar um tipo nem alterá-lo. Para alterar o código de um tipo, tem de alterar o nome ou iniciar uma nova sessão do PowerShell. Caso contrário, o comando falha.

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

-Namespace

Especifica um espaço de nomes para o tipo.

Se este parâmetro não estiver incluído no comando, o tipo é criado no Microsoft. Espaço de nomes PowerShell.Commands.AddType.AutoGeneratedTypes. Se o parâmetro estiver incluído no comando com um valor de cadeia vazio ou um valor de $Null, o tipo é gerado no espaço de nomes global.

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

-OutputAssembly

Gera um ficheiro DLL para a assemblagem com o nome especificado na localização. Introduza um caminho e nome de ficheiro opcionais. Os carateres universais são permitidos. Por predefinição, Add-Type gera a assemblagem apenas na memória.

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

-OutputType

Especifica o tipo de saída da assemblagem de saída. Por predefinição, não é especificado nenhum tipo de saída. Este parâmetro só é válido quando uma assemblagem de saída é especificada no comando. Para obter mais informações sobre os valores, veja 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 gera 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
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

Devolve um objeto System.Runtime que representa os tipos que foram adicionados. Por predefinição, este cmdlet não gera nenhuma saída.

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

-Path

Especifica o caminho para ficheiros de código fonte ou ficheiros DLL de assemblagem que contêm os tipos.

Se submeter ficheiros de código fonte, Add-Type compila o código nos ficheiros e cria uma assemblagem dentro da memória dos tipos. A extensão de ficheiro especificada no valor de Caminho determina o compilador que Add-Type utiliza.

Se submeter um ficheiro de assemblagem, Add-Type tira os tipos da assemblagem. Para especificar uma assemblagem dentro da memória ou a cache de assemblagem global, utilize o parâmetro AssemblyName .

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

-ReferencedAssemblies

Especifica as assemblagens de que o tipo depende. Por predefinição, Add-Type as referências System.dll e System.Management.Automation.dll. As assemblagens que especificar com este parâmetro são referenciadas para além das assemblagens predefinidas.

A partir do PowerShell 6, ReferencedAssemblies não inclui as assemblagens .NET predefinidas. Tem de incluir uma referência específica aos mesmos no valor transmitido a este parâmetro.

Não pode utilizar os parâmetros CompilerOptions e ReferencedAssemblies no mesmo comando.

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

-TypeDefinition

Especifica o código fonte que contém as definições de tipo. Introduza o código fonte numa cadeia de carateres ou numa cadeia de carateres ou introduza uma variável que contenha o código fonte. Para obter mais informações sobre as cadeias here-strings, consulte about_Quoting_Rules.

Inclua uma declaração de espaço de nomes na definição do seu tipo. Se omitir a declaração do espaço de nomes, o seu tipo poderá ter o mesmo nome que outro tipo ou o atalho para outro tipo, causando uma substituição não intencional. Por exemplo, se definir um tipo chamado Exceção, os scripts que utilizam a Exceção como atalho para System.Exception falharão.

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

-UsingNamespace

Especifica outros espaços de nomes que são necessários para a classe. Isto é muito parecido com a palavra-chave C#, Using.

Por predefinição, Add-Type referencia o espaço de nomes do sistema . Quando o parâmetro MemberDefinition é utilizado, Add-Type também referencia o espaço de nomes System.Runtime.InteropServices por predefinição. Os espaços de nomes que adicionar com o parâmetro UsingNamespace são referenciados para além dos espaços de nomes predefinidos.

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

Entradas

None

Não pode encaminhar objetos para este cmdlet.

Saídas

None

Por predefinição, este cmdlet não devolve nenhuma saída.

Type

Quando utiliza o parâmetro PassThru , este cmdlet devolve um objeto System.Type que representa o novo tipo.

Notas

Os tipos que adicionar existem apenas na sessão atual. Para utilizar os tipos em todas as sessões, adicione-os ao seu perfil do PowerShell. Para obter mais informações sobre o perfil, veja about_Profiles.

Os nomes dos tipos e os espaços de nomes têm de ser exclusivos numa sessão. Não pode descarregar um tipo nem alterá-lo. Se precisar de alterar o código de um tipo, tem de alterar o nome ou iniciar uma nova sessão do PowerShell. Caso contrário, o comando falha.

No Windows PowerShell (versão 5.1 e abaixo), tem de utilizar Add-Type para tudo o que ainda não esteja carregado. Normalmente, isto aplica-se a assemblagens encontradas na Cache de Assemblagem Global (GAC). No PowerShell 6 e superior, não existe nenhum GAC, pelo que o PowerShell instala as suas próprias assemblagens no $PSHome. Estas assemblagens são carregadas automaticamente a pedido, pelo que não é necessário utilizá-las Add-Type para carregá-las. No entanto, a utilização Add-Type continua a ser permitida para permitir que os scripts sejam implicitamente compatíveis com qualquer versão do PowerShell.

As assemblagens no GAC podem ser carregadas por nome de tipo, em vez de por caminho. O carregamento de assemblagens a partir de um caminho arbitrário requer Add-Type, uma vez que essas assemblagens não podem ser carregadas 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 a partir de uma assemblagem

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 a partir de uma assemblagem

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