Cómo crear, compilar, cargar y ejecutar una DLL desde PowerShell (PowerShell)

PowerShell permite trabajar con bibliotecas DLL de .NET para reutilizar código, consultar clases, inspeccionar métodos y ejecutar funcionalidades implementadas en C# sin necesidad de abrir Visual Studio.

En este tutorial veremos cómo crear una biblioteca de clases, compilarla desde PowerShell, cargarla con Add-Type o Reflection.Assembly, consultar los tipos exportados y ejecutar métodos estáticos y de instancia.

También aprenderemos a inspeccionar los parámetros de los métodos, invocar funciones mediante reflexión y solucionar los errores más habituales.

1. ¿Qué es una DLL?

Una DLL (Dynamic Link Library) es una biblioteca que contiene código y recursos que pueden utilizar otros programas. En el ecosistema .NET, una DLL puede ser un ensamblado que incluye clases, métodos, interfaces y otros tipos reutilizables.

Por ejemplo, una biblioteca puede contener una clase con operaciones matemáticas:

namespace MiBiblioteca
{
    public class Utilidades
    {
        public int Sumar(int a, int b)
        {
            return a + b;
        }
    }
}

Una aplicación compatible puede cargar esa biblioteca y utilizar sus métodos sin tener que incorporar el código fuente original.

En PowerShell podemos trabajar con DLL de .NET para:

• Reutilizar funciones implementadas en C#.
• Cargar bibliotecas propias o de terceros.
• Consultar los tipos públicos que contiene un ensamblado.
• Inspeccionar los métodos de una clase.
• Ejecutar métodos estáticos y de instancia.
• Consultar parámetros y tipos de retorno.
• Automatizar operaciones mediante código .NET.

Es importante tener en cuenta que no todas las DLL son iguales. Una biblioteca nativa de Windows no se puede utilizar directamente como si fuera una biblioteca administrada de .NET.

2. Requisitos previos

Para seguir los ejemplos utilizaremos Windows PowerShell 5.1 y el compilador de C# de .NET Framework.

Abre PowerShell y consulta la versión:

$PSVersionTable

Para comprobar específicamente la versión principal:

$PSVersionTable.PSVersion

Si aparece la versión 5.1, puedes continuar con los procedimientos basados en Windows PowerShell.

Comprobar el compilador de C#

En muchas instalaciones de Windows con .NET Framework están disponibles estas rutas:

Test-Path "$env:WINDIR\Microsoft.NET\Framework64\v4.0.30319\csc.exe"

Para comprobar también la versión de 32 bits:

Test-Path "$env:WINDIR\Microsoft.NET\Framework\v4.0.30319\csc.exe"

Si alguna devuelve True, puedes utilizar el compilador correspondiente.

Si ambas devuelven False, tendrás que utilizar otro compilador disponible o instalar el entorno de desarrollo de .NET adecuado.

3. Crear la carpeta del proyecto

Vamos a crear un directorio para guardar el código fuente y la biblioteca compilada.

New-Item -Path "C:\MiDLL" -ItemType Directory -Force

Set-Location "C:\MiDLL"

La estructura inicial será:

C:\MiDLL\

Dentro de esta carpeta guardaremos el archivo Utilidades.cs y generaremos MiBiblioteca.dll.

4. Crear el código fuente en C#

El primer paso consiste en crear una clase con varios métodos que después podremos utilizar desde PowerShell.

Ejecuta el siguiente bloque:

$codigo = @'
namespace MiBiblioteca
{
    public class Utilidades
    {
        public string Saludar(string nombre)
        {
            return "Hola, " + nombre;
        }

        public int Sumar(int a, int b)
        {
            return a + b;
        }

        public int Multiplicar(int a, int b)
        {
            return a * b;
        }

        public static string ObtenerVersion()
        {
            return "1.0.0";
        }
    }
}
'@

Set-Content 
    -Path "C:\MiDLL\Utilidades.cs" 
    -Value $codigo 
    -Encoding UTF8

$candidatos = @(
    "$env:WINDIR\Microsoft.NET\Framework64\v4.0.30319\csc.exe",
    "$env:WINDIR\Microsoft.NET\Framework\v4.0.30319\csc.exe"
)

$csc = $candidatos |
    Where-Object { Test-Path $_ } |
    Select-Object -First 1

if (-not $csc) {
    throw "No se encuentra csc.exe. Comprueba la instalación de .NET Framework."
}

Write-Host "Compilador encontrado: $csc"

& $csc 
    /nologo 
    /target:library 
    /out:"C:\MiDLL\MiBiblioteca.dll" 
    "C:\MiDLL\Utilidades.cs"

if ($LASTEXITCODE -ne 0) {
    throw "La compilación ha fallado."
}

Write-Host "DLL compilada correctamente."

Get-Item "C:\MiDLL\MiBiblioteca.dll" |
    Select-Object Name, Length, FullName, LastWriteTime

Test-Path "C:\MiDLL\MiBiblioteca.dll"

True

C:\MiDLL\
├── Utilidades.cs
└── MiBiblioteca.dll

Add-Type -Path "C:\MiDLL\MiBiblioteca.dll"

$objeto = New-Object MiBiblioteca.Utilidades

$objeto.Saludar("Windows")

Hola, Windows

$objeto.Sumar(10, 20)

30

$objeto.Multiplicar(5, 6)

30

[MiBiblioteca.Utilidades]::ObtenerVersion()

1.0.0

$carga = [Reflection.Assembly]::LoadFile(
    "C:\MiDLL\MiBiblioteca.dll"
)

$carga.FullName

$carga.Location

$carga | Select-Object ExportedTypes

$carga.ExportedTypes |
    Select-Object FullName

FullName
--------
MiBiblioteca.Utilidades

$carga.ExportedTypes |
    Select-Object Name

Name
----
Utilidades

foreach ($tipo in $carga.ExportedTypes) {
    Write-Host "Tipo: $($tipo.FullName)"
}

$tipo = $carga.GetType("MiBiblioteca.Utilidades")

$tipo

$tipo.GetMethods() |
    Select-Object Name, ReturnType

$tipo.GetMethods(
    [Reflection.BindingFlags] "Public, NonPublic, Instance, Static, DeclaredOnly"
) |
    Select-Object Name, IsStatic, ReturnType

$tipo.GetMethods().Name

$tipo.DeclaredMethods.Name

[MiBiblioteca.Utilidades].DeclaredMethods.Name

[ClassLibrary3.Class1].DeclaredMethods.Name

C:\Users\juan\source\repos\ClassLibrary3\ClassLibrary3\bin\Debug\ClassLibrary3.dll

$carga = [Reflection.Assembly]::LoadFile(
    "C:\Users\juan\source\repos\ClassLibrary3\ClassLibrary3\bin\Debug\ClassLibrary3.dll"
)

$carga | Select-Object ExportedTypes

$carga.ExportedTypes |
    Select-Object FullName

$tipo = $carga.GetType("ClassLibrary3.Class1")

if ($null -eq $tipo) {
    throw "No se ha encontrado ClassLibrary3.Class1 en la DLL."
}

$tipo.DeclaredMethods.Name

C:\Users\pepitogrillo\ejemplo.dll

$carga = [Reflection.Assembly]::LoadFile(
    "C:\Users\pepitogrillo\ejemplo.dll"
)

[Hola.Hola]::Main()

$carga = [Reflection.Assembly]::LoadFile(
    "C:\Users\pepitogrillo\ejemplo.dll"
)

$tipo = $carga.GetType("Hola.Hola")

if ($null -eq $tipo) {
    throw "No se ha encontrado el tipo Hola.Hola."
}

$tipo.GetMethods(
    [Reflection.BindingFlags] "Public, Static, DeclaredOnly"
) |
    Select-Object Name, ReturnType

$metodo = $tipo.GetMethod(
    "Main",
    [Reflection.BindingFlags] "Public, Static"
)

if ($null -eq $metodo) {
    throw "No se ha encontrado el método estático Main."
}

$metodo.Invoke($null, [object[]]@())

$codigoHola = @'
using System;

namespace Hola
{
    public class Hola
    {
        public static void Main()
        {
            Console.WriteLine("Hola desde una DLL ejecutada con PowerShell");
        }

        public static string ObtenerMensaje()
        {
            return "Biblioteca Hola cargada correctamente";
        }
    }
}
'@

Set-Content 
    -Path "C:\MiDLL\Hola.cs" 
    -Value $codigoHola 
    -Encoding UTF8

Compilamos la biblioteca con el compilador que hemos localizado anteriormente:

& $csc 
    /nologo 
    /target:library 
    /out:"C:\MiDLL\Hola.dll" 
    "C:\MiDLL\Hola.cs"

if ($LASTEXITCODE -ne 0) {
    throw "No se ha podido compilar Hola.dll."
}

Ahora la cargamos:

$cargaHola = [Reflection.Assembly]::LoadFile(
    "C:\MiDLL\Hola.dll"
)

Y ejecutamos el método estático:

$tipoHola = $cargaHola.GetType("Hola.Hola")

$metodoMain = $tipoHola.GetMethod(
    "Main",
    [Reflection.BindingFlags] "Public, Static"
)

$metodoMain.Invoke($null, [object[]]@())

La salida esperada es:

Hola desde una DLL ejecutada con PowerShell

También podemos llamar al método ObtenerMensaje():

$tipoHola.GetMethod("ObtenerMensaje").Invoke(
    $null,
    [object[]]@()
)

Resultado:

Biblioteca Hola cargada correctamente

En este ejemplo Main() es simplemente un método estático de una clase de biblioteca. No significa que la DLL sea un ejecutable independiente.

13. Invocar métodos de instancia mediante reflexión

No todos los métodos son estáticos. Cuando un método pertenece a una instancia, primero tenemos que crear el objeto correspondiente.

Podemos recuperar el tipo de nuestra biblioteca:

$carga = [Reflection.Assembly]::LoadFile(
    "C:\MiDLL\MiBiblioteca.dll"
)

$tipo = $carga.GetType("MiBiblioteca.Utilidades")

Creamos una instancia:

$objeto = [Activator]::CreateInstance($tipo)

Buscamos el método Saludar:

$metodo = $tipo.GetMethod("Saludar")

Lo invocamos con un parámetro:

$metodo.Invoke(
    $objeto,
    [object[]]@("PowerShell")
)

Resultado:

Hola, PowerShell

La diferencia es que Invoke() recibe el objeto de destino cuando se trata de un método de instancia. Para un método estático, el primer argumento debe ser $null.

14. Consultar los parámetros de los métodos

La reflexión permite conocer los parámetros que recibe cada método antes de ejecutarlo.

Por ejemplo:

$tipo = $carga.GetType("MiBiblioteca.Utilidades")

$tipo.GetMethods() |
    Where-Object {
        $_.DeclaringType.FullName -eq "MiBiblioteca.Utilidades"
    } |
    ForEach-Object {
        [PSCustomObject]@{
            Metodo = $_.Name
            Retorno = $_.ReturnType.Name
            Estatico = $_.IsStatic
            Parametros = (
                $_.GetParameters() |
                ForEach-Object {
                    "$($_.ParameterType.Name) $($_.Name)"
                }
            ) -join ", "
        }
    } |
    Format-Table -AutoSize

La salida mostrará información similar a esta:

Metodo          Retorno Estatico Parametros
------          ------- -------- ----------
Saludar         String     False String nombre
Sumar           Int32      False Int32 a, Int32 b
Multiplicar     Int32      False Int32 a, Int32 b
ObtenerVersion  String      True

La columna Estatico indica si el método se puede invocar directamente sobre la clase.

15. Compilar una DLL con Add-Type

Además de utilizar csc.exe, Windows PowerShell 5.1 permite compilar código C# con Add-Type cuando el compilador y el entorno de .NET necesarios están disponibles.

Por ejemplo:

$codigo = @'
namespace OtraBiblioteca
{
    public class Calculadora
    {
        public static int Restar(int a, int b)
        {
            return a - b;
        }
    }
}
'@

Add-Type 
    -TypeDefinition $codigo 
    -Language CSharp 
    -OutputAssembly "C:\MiDLL\OtraBiblioteca.dll" 
    -OutputType Library

Si la compilación finaliza correctamente, se generará OtraBiblioteca.dll.

Puedes comprobarlo:

Test-Path "C:\MiDLL\OtraBiblioteca.dll"

Y cargarla:

Add-Type -Path "C:\MiDLL\OtraBiblioteca.dll"

[OtraBiblioteca.Calculadora]::Restar(20, 5)

Resultado:

15

Este procedimiento es cómodo para bibliotecas pequeñas. Para proyectos más complejos, con dependencias, varias clases o diferentes versiones de .NET, resulta más apropiado utilizar un proyecto de biblioteca y compilarlo con el SDK de .NET.

16. Diferencias entre Add-Type y Assembly.LoadFile()

Aunque ambos mecanismos permiten cargar ensamblados, no son exactamente equivalentes.

Add-Type es una opción sencilla cuando queremos utilizar clases desde PowerShell. Assembly.LoadFile() resulta especialmente útil cuando queremos conservar una referencia al ensamblado e inspeccionarlo explícitamente.

17. Errores frecuentes al cargar DLL

Error: no se encuentra el archivo

Comprueba la ruta:

Test-Path "C:\MiDLL\MiBiblioteca.dll"

Si devuelve False, revisa el nombre y la ubicación de la biblioteca.

Error: no se encuentra el tipo

Consulta los tipos exportados:

$carga.ExportedTypes |
    Select-Object FullName

Es posible que el nombre completo de la clase sea distinto del que estás utilizando.

Error: no se encuentra el método

Inspecciona los métodos declarados:

$tipo.DeclaredMethods |
    Select-Object Name, IsStatic

Comprueba el nombre, la visibilidad, si el método es estático y los parámetros que necesita.

Error: no se puede cargar una dependencia

Una DLL puede depender de otros ensamblados. Comprueba que las dependencias necesarias estén disponibles y sean compatibles con el entorno de ejecución.

Error: incompatibilidad entre .NET Framework y .NET moderno

Una biblioteca compilada para .NET Framework no es necesariamente compatible con PowerShell 7, que utiliza .NET moderno.

Comprueba la versión de PowerShell:

$PSVersionTable.PSVersion

Para proyectos destinados a .NET moderno, utiliza el SDK de .NET y el sistema de compilación correspondiente.

Error: la DLL está cargada, pero el código no funciona

Cargar un ensamblado no garantiza que sus métodos se puedan ejecutar correctamente. Puede haber dependencias ausentes, parámetros incorrectos, excepciones internas o incompatibilidades.

Cuando se utiliza reflexión, las excepciones producidas por un método invocado suelen aparecer envueltas en una TargetInvocationException. La propiedad InnerException contiene la excepción original.

18. Consideraciones de seguridad

Las bibliotecas DLL pueden ejecutar código dentro del proceso que las carga. Por ello:

• No cargues DLL de origen desconocido o no confiable.
• Comprueba la procedencia y la integridad de los archivos.
• Revisa las dependencias antes de ejecutar métodos.
• Evita ejecutar PowerShell con privilegios de administrador cuando no sea necesario.
• No confundas la inspección de una DLL con una garantía de que su contenido sea seguro.
• Ten en cuenta que cargar código de terceros puede modificar el estado del proceso o acceder a recursos a los que este tenga permiso.

La reflexión no es un mecanismo de aislamiento de seguridad. Si necesitas ejecutar código no confiable, utiliza un entorno aislado adecuado.

19. Resumen de comandos

Estos son los comandos principales del tutorial: