Endpoints de la API de C#

Identificador: PowerShellUniversal.Language.CSharp

Este plugin crea un entorno basado en C# que puede utilizarse para crear endpoints de API con código C#. Las API creadas con C# son mucho más rápidas que los endpoints basados en PowerShell. Los endpoints se ejecutan directamente en el servicio de PowerShell Universal. Cualquier excepción lanzada desde su endpoint se gestionará y se devolverá un código de estado válido al llamante.

Debe crear los endpoints con el parámetro -Path y especificar el entorno C# para que el endpoint funcione correctamente.

New-PSUEndpoint -Url /csharp -Path csharp.cs -Environment 'C#'

Definir un endpoint

Dentro del endpoint de C#, hay dos clases de interés. La primera es la variable request que se pasa al endpoint. Es un objeto ApiRequest.

public class ApiRequest
{
    public long Id { get; set; }
    public ICollection<KeyValue> Variables { get; set; } = new List<KeyValue>();
    public IEnumerable<ApiFile> Files { get; set; } = new List<ApiFile>();
    public string Url { get; set; }
    public ICollection<KeyValue> Headers { get; set; } = new List<KeyValue>();
    public byte[] Data { get; set; }
    public int ErrorAction { get; set; }
    public ICollection<KeyValue> Parameters { get; set; } = new List<KeyValue>();
    public string Method { get; set; }
    public ICollection<KeyValue> Cookies { get; set; } = new List<KeyValue>();
    public string ClaimsPrincipal { get; set; }
    public string ContentType { get; set; }
    public string[] Roles { get; set; }
}

En su endpoint, puede acceder a esta variable automáticamente.

if (request.ContentType == "application/json")
{
     // Do some stuff with JSON
}

El endpoint debe devolver un objeto ApiResponse. Este objeto tiene la siguiente definición.

public class ApiResponse
{
    public int StatusCode { get; set; } = 200;
    public string Body { get; set; }
    public List<KeyValue> Cookies { get; set; } = new List<KeyValue>();
    public byte[] Data { get; set; } = Array.Empty<byte>();
    public string ContentType { get; set; } = "text/plain";
    public List<KeyValue> Headers { get; set; } = new List<KeyValue>();
    public ApiFile File { get; set; }
}

Puede devolver una respuesta creando un nuevo objeto y devolviéndolo desde su endpoint.

return new ApiResponse {
    StatusCode = 401
};

Al definir el contenido de un endpoint, tenga en cuenta que el código se añade a una clase con nombre dinámico que tiene una única función Execute. Su código debe tener una sintaxis válida para un fichero de origen de este tipo.

using PowerShellUniversal;

public class c{id} : ExecutionClass {{ 
    public static ApiResponse Execute(ApiRequest request) 
    {{ 
        {fileContents} 

        return new ApiResponse();
    }} 
}}";

Puede acceder al contenedor del servicio de PowerShell Universal dentro de su endpoint accediendo a la propiedad ServiceProvider en su endpoint. Actualmente no documentamos los servicios internos de PowerShell Universal.

var database = ServiceProvider.GetService(typeof(IDatabase));

Referencias

Puede controlar qué ensamblados se referencian utilizando la palabra clave #ref. El valor puede ser un fichero DLL en el directorio de instalación de PowerShell Universal, o la ruta completa a otro ensamblado.

#ref PowerShellUniversal.Apis.dll
#ref C:\assemblies\markdiag.dll

Uso de espacios de nombres

Puede referenciar un espacio de nombres utilizando la palabra clave #using.

#using System.Management.Automation

Variables

Puede acceder a las variables en los endpoints de C# con los métodos GetVariable, GetSecretString y GetSecretCredential.

return new ApiResponse {
    StatusCode = 200
    Body = GetVariable("MyVar").ToString()
};

Para acceder a un PSCredential, puede hacer lo siguiente.

#ref System  
#ref System.Management.Automation

return new ApiResponse { 
    StatusCode = 200, 
    Body = GetSecretCredential("MyCred").UserName.ToString() 
};