Add-Type (Microsoft.PowerShell.Utility)

Add-Type

Módulo:

Microsoft.PowerShell.Utility

Agrega una clase Microsoft .NET a una sesión de PowerShell.

Sintaxis

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

Descripción

El cmdlet Add-Type le permite definir una clase Microsoft .NET Core en su sesión de PowerShell. Luego puede crear instancias de objetos mediante el cmdlet New-Object y usar los objetos tal como usaría cualquier objeto .NET Core. Si agrega un comando Add-Type a su perfil de PowerShell, la clase estará disponible en todas las sesiones de PowerShell.

Puede especificar el tipo especificando un ensamblado existente o archivos de código fuente, o puede especificar el código fuente en línea o guardado en una variable. Incluso puedes especificar solo un método y Add-Type define y genera la clase. En Windows, puede usar esta característica para realizar llamadas de Invocación de plataforma (P/Invoke) a funciones no administradas en PowerShell. Si especifica el código fuente, Add-Type compila el código fuente especificado y genera un ensamblado en memoria que contiene los nuevos tipos de .NET Core.

Puede usar los parámetros de Add-Type para especificar un lenguaje y un compilador alternativos (C# es el predeterminado), las opciones del compilador, las dependencias del ensamblado, el espacio de nombres de la clase, los nombres del tipo y el ensamblado resultante.

A partir de PowerShell 7, Add-Type no compila un tipo si ya existe un tipo con el mismo nombre. Además, Add-Type busca ensamblados en una carpeta ref debajo de la carpeta que contiene pwsh.dll.

Ejemplos

Ejemplo 1: agregar un tipo .NET a una sesión

Este ejemplo agrega la clase BasicTest a la sesión especificando el código fuente que se almacena en una variable. La clase BasicTest se utiliza para sumar números enteros, crear un objeto y multiplicar números enteros.

$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)

La variable $Source almacena el código fuente de la clase. El tipo tiene un método estático llamado Add y un método no estático llamado Multiply.

El cmdlet Add-Type agrega la clase a la sesión. Debido a que utiliza código fuente en línea, el comando usa el parámetro TypeDefinition para especificar el código en la variable $Source.

El método estático Add de la clase BasicTest utiliza los caracteres de dos puntos (::) para especificar un miembro estático de la clase. Se suman los números enteros y se muestra la suma.

El cmdlet New-Object crea una instancia de la clase BasicTest. Guarda el nuevo objeto en la variable $BasicTestObject.

$BasicTestObject utiliza el método Multiplicar. Los números enteros se multiplican y se muestra el producto.

Ejemplo 2: examinar un tipo agregado

En este ejemplo se utiliza el cmdlet Get-Member para examinar los objetos que los cmdlets Add-Type y New-Object crearon en el Ejemplo 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()

El cmdlet Get-Member obtiene el tipo y los miembros de la clase BasicTest que Add-Type agregó a la sesión. El comando Get-Member revela que es un objeto System.RuntimeType, que se deriva de la clase System.Object.

El parámetro Get-Member Static obtiene las propiedades y métodos estáticos de la clase BasicTest. El resultado muestra que el método Add está incluido.

El cmdlet Get-Member obtiene los miembros del objeto almacenados en la variable $BasicTestObject. $BasicTestObject se creó utilizando el cmdlet New-Object con la clase BasicTest. El resultado revela que el valor de la variable $BasicTestObject es una instancia de la clase BasicTest y que incluye un miembro llamado Multiply.

Ejemplo 3: agregar tipos desde un ensamblaje

Este ejemplo agrega las clases del ensamblado JsonSchema.NET.dll a la sesión actual.

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

Set-Location utiliza el parámetro Path para especificar la variable $PSHOME. La variable hace referencia al directorio de instalación de PowerShell donde se encuentra el archivo DLL.

La variable $AccType almacena un objeto creado con el cmdlet Add-Type. Add-Type utiliza el parámetro AssemblyName para especificar el nombre del ensamblaje. El carácter comodín asterisco (*) le permite obtener el ensamblado correcto incluso cuando no está seguro del nombre o su ortografía. El parámetro PassThru genera objetos que representan las clases que se agregan a la sesión.

Ejemplo 4: llamar a las API nativas de Windows

Este ejemplo demuestra cómo llamar a las API nativas de Windows en PowerShell. Add-Type utiliza el mecanismo Platform Invoke (P/Invoke) para llamar a una función en User32.dll desde PowerShell. Este ejemplo solo funciona en computadoras que ejecutan el sistema operativo 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)

La variable $Signature almacena la firma C# de la función ShowWindowAsync. Para garantizar que el método resultante sea visible en una sesión de PowerShell, se agregó la palabra clave public a la firma estándar. Para obtener más información, consulte Función ShowWindowAsync.

La variable $ShowWindowAsync almacena el objeto creado por el parámetro Add-Type PassThru. El cmdlet Add-Type agrega la función ShowWindowAsync a la sesión de PowerShell como un método estático. El comando utiliza el parámetro MemberDefinition para especificar la definición del método guardada en la variable $Signature. El comando utiliza los parámetros Nombre y Namespace para especificar un nombre y un espacio de nombres para la clase. El parámetro PassThru genera un objeto que representa los tipos.

El nuevo método estático ShowWindowAsync se utiliza en los comandos para minimizar y restaurar la consola de PowerShell. El método toma dos parámetros: el identificador de la ventana y un número entero que especifica cómo se muestra la ventana.

Para minimizar la consola de PowerShell, ShowWindowAsync usa el cmdlet Get-Process con la variable automática $PID para obtener el proceso que aloja el PowerShell actual. sesión. Luego utiliza la propiedad MainWindowHandle del proceso actual y un valor de 2, que representa el valor SW_MINIMIZE.

Para restaurar la ventana, ShowWindowAsync utiliza un valor de 4 para la posición de la ventana, que representa el valor SW_RESTORE.

Para maximizar la ventana, utilice el valor de 3 que representa SW_MAXIMIZE.

Parámetros

-AssemblyName

Especifica el nombre de un ensamblado que incluye los tipos. Add-Type toma los tipos del ensamblado especificado. Este parámetro es obligatorio cuando se crean tipos basados en un nombre de ensamblado.

Introduzca el nombre completo o simple, también conocido como nombre parcial, de un ensamblado. Se permiten caracteres comodín en el nombre del ensamblado. Si ingresa un nombre simple o parcial, Add-Type lo resuelve con el nombre completo y luego usa el nombre completo para cargar el ensamblado.

El uso de los parámetros Path o LiteralPath garantiza que está cargando el ensamblaje que pretendía cargar. Cuando utiliza el parámetro AssemblyName, PowerShell le pide a .NET que resuelva el nombre del ensamblado mediante el proceso de resolución de ensamblados estándar de .NET. Dado que .NET busca primero en la carpeta de la aplicación, Add-Type podría cargar un ensamblado desde $PSHOME en lugar de la versión en la carpeta actual. Para obtener más información, consulte Ubicación de montaje.

Si .NET no puede resolver el nombre, PowerShell busca en la ubicación actual el ensamblado. Cuando se utilizan comodines en el parámetro AssemblyName, el proceso de resolución del ensamblado .NET falla y PowerShell busca en la ubicación actual.

Tipo :

String[]

Alias:

AN

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

True

-CompilerOptions

Especifica las opciones para el compilador de código fuente. Estas opciones se envían al compilador sin revisión.

Este parámetro le permite indicar al compilador que genere un archivo ejecutable, incruste recursos o establezca opciones de línea de comandos, como la opción /unsafe.

Tipo :

String[]

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-IgnoreWarnings

Ignora las advertencias del compilador. Utilice este parámetro para evitar que Add-Type maneje las advertencias del compilador como errores.

Tipo :

SwitchParameter

Posición:

Nombrado

Valor predeterminado:

False

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-Language

Especifica el idioma que se utiliza en el código fuente. El valor aceptable para este parámetro es CSharp.

Tipo :

Idioma

Valores aceptados:

CSharp

Posición:

Nombrado

Valor predeterminado:

CSharp

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-LiteralPath

Especifica la ruta a los archivos de código fuente o archivos DLL de ensamblaje que contienen los tipos. A diferencia de Path, el valor del parámetro LiteralPath se utiliza exactamente tal como se escribe. Ningún carácter se interpreta como comodín. Si la ruta incluye caracteres de escape, escríbala entre comillas simples. Las comillas simples le indican a PowerShell que no interprete ningún carácter como secuencia de escape.

El uso de los parámetros Path o LiteralPath garantiza que está cargando el ensamblaje que pretendía cargar.

Tipo :

String[]

Alias:

PSPath, LP

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-MemberDefinition

Especifica nuevas propiedades o métodos para la clase. Add-Type genera el código de plantilla necesario para admitir las propiedades o métodos.

En Windows, puede usar esta característica para realizar llamadas de Invocación de plataforma (P/Invoke) a funciones no administradas en PowerShell.

Tipo :

String[]

Posición:

1

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-Name

Especifica el nombre de la clase a crear. Este parámetro es necesario al generar un tipo a partir de una definición de miembro.

El nombre del tipo y el espacio de nombres deben ser únicos dentro de una sesión. No puede descargar un tipo ni cambiarlo. Para cambiar el código de un tipo, debe cambiar el nombre o iniciar una nueva sesión de PowerShell. De lo contrario, el comando falla.

Tipo :

String

Posición:

0

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-Namespace

Especifica un espacio de nombres para el tipo.

Si este parámetro no está incluido en el comando, el tipo se crea en el espacio de nombres Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes. Si el parámetro se incluye en el comando con un valor de cadena vacío o un valor de $Null, el tipo se genera en el espacio de nombres global.

Tipo :

String

Alias:

NS

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-OutputAssembly

Genera un archivo DLL para el ensamblado con el nombre especificado en la ubicación. Ingrese una ruta y un nombre de archivo opcionales. Se permiten caracteres comodín. De forma predeterminada, Add-Type genera el ensamblado solo en la memoria.

Tipo :

String

Alias:

OA

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

True

-OutputType

Especifica el tipo de salida del ensamblaje de salida. De forma predeterminada, no se especifica ningún tipo de salida. Este parámetro solo es válido cuando se especifica un ensamblado de salida en el comando. Para obtener más información sobre los valores, consulte Enumeración OutputAssemblyType.

Los valores aceptables para este parámetro son los siguientes:

ConsoleApplication

Library

WindowsApplication

Tipo :

Tipo de ensamblaje de salida

Alias:

OT

Valores aceptados:

ConsolaAplicación, Biblioteca, Aplicación Windows

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-PassThru

Devuelve un objeto System.Runtime que representa los tipos que se agregaron. De forma predeterminada, este cmdlet no genera ningún resultado.

Tipo :

SwitchParameter

Posición:

Nombrado

Valor predeterminado:

False

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-Path

Especifica la ruta a los archivos de código fuente o archivos DLL de ensamblaje que contienen los tipos.

Si envía archivos de código fuente, Add-Type compila el código en los archivos y crea un ensamblado en memoria de los tipos. La extensión de archivo especificada en el valor de Path determina el compilador que utiliza Add-Type.

El uso de los parámetros Path o LiteralPath garantiza que está cargando el ensamblaje que pretendía cargar.

Tipo :

String[]

Posición:

0

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-ReferencedAssemblies

Especifica los ensamblajes de los que depende el tipo. De forma predeterminada, Add-Type hace referencia a System.dll y System.Management.Automation.dll. Se hace referencia a los ensamblados que especifica mediante este parámetro además de a los ensamblados predeterminados.

A partir de PowerShell 6, ReferencedAssemblies no incluye los ensamblados .NET predeterminados. Debe incluir una referencia específica a ellos en el valor pasado a este parámetro.

Tipo :

String[]

Alias:

RA

Posición:

Nombrado

Valor predeterminado:

None

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-TypeDefinition

Especifica el código fuente que contiene las definiciones de tipo. Ingrese el código fuente en una cadena o aquí-cadena, o ingrese una variable que contenga el código fuente. Para obtener más información sobre las cadenas aquí, consulte about_Quoting_Rules.

Incluya una declaración de espacio de nombres en su definición de tipo. Si omite la declaración del espacio de nombres, su tipo podría tener el mismo nombre que otro tipo o el acceso directo para otro tipo, lo que provocaría una sobrescritura no intencionada. Por ejemplo, si define un tipo llamado Exception, las secuencias de comandos que utilizan Exception como acceso directo para System.Exception fallarán.

Tipo :

String

Posición:

0

Valor predeterminado:

None

Requerido:

True

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

-UsingNamespace

Especifica otros espacios de nombres necesarios para la clase. Esto es muy parecido a la palabra clave de C#, Using.

De forma predeterminada, Add-Type hace referencia al espacio de nombres System. Cuando se utiliza el parámetro MemberDefinition, Add-Type también hace referencia al espacio de nombres System.Runtime.InteropServices de forma predeterminada. Se hace referencia a los espacios de nombres que agrega mediante el parámetro UsingNamespace además de los espacios de nombres predeterminados.

Tipo :

String[]

Alias:

Using

Posición:

Nombrado

Valor predeterminado:

Espacio de nombres del sistema

Requerido:

False

Aceptar entrada de canalización:

False

Aceptar caracteres comodín:

False

Entradas

Ninguno

No puede canalizar objetos a este cmdlet.

Salidas

Ninguno

De forma predeterminada, este cmdlet no devuelve ningún resultado.

Tipo

Cuando se utiliza el parámetro PassThru, este cmdlet devuelve un objeto System.Type que representa el nuevo tipo.

Notas

Los tipos que agrega existen solo en la sesión actual. Para usar los tipos en todas las sesiones, agréguelos a su perfil de PowerShell. Para obtener más información sobre el perfil, consulte about_Profiles.

Los nombres de tipo y los espacios de nombres deben ser únicos dentro de una sesión. No puede descargar un tipo ni cambiarlo. Si necesita cambiar el código de un tipo, debe cambiar el nombre o iniciar una nueva sesión de PowerShell. De lo contrario, el comando falla.

En Windows PowerShell (versión 5.1 y anteriores), debe usar Add-Type para cualquier cosa que aún no esté cargada. Por lo general, esto se aplica a los ensamblados que se encuentran en la caché de ensamblados global (GAC). En PowerShell 6 y superiores, no hay GAC, por lo que PowerShell instala sus propios ensamblados en $PSHOME. Estos ensamblados se cargan automáticamente a pedido, por lo que no es necesario usar Add-Type para cargarlos. Sin embargo, todavía se permite el uso de Add-Type para permitir que los scripts sean implícitamente compatibles con cualquier versión de PowerShell.

Los ensamblados en GAC se pueden cargar por nombre de tipo, en lugar de por ruta. Cargar ensamblados desde una ruta arbitraria requiere Add-Type, ya que esos ensamblados no se pueden cargar automáticamente.