Endpoint API C#

Identificatore: PowerShellUniversal.Language.CSharp

Questo plugin crea un ambiente basato su C# che può essere utilizzato per creare endpoint API con codice C#. Le API create con C# sono molto più veloci degli endpoint basati su PowerShell. Gli endpoint vengono eseguiti direttamente nel servizio PowerShell Universal. Qualsiasi eccezione generata dal suo endpoint verrà gestita e un codice di stato valido verrà restituito al chiamante.

Deve creare gli endpoint con il parametro -Path e specificare l'ambiente C# affinché l'endpoint funzioni correttamente.

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

Definizione di un endpoint

All'interno dell'endpoint C# ci sono due classi di interesse. La prima è la variabile request che viene passata all'endpoint. È un oggetto 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; }
}

Nel suo endpoint può accedere automaticamente a questa variabile.

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

L'endpoint deve restituire un oggetto ApiResponse. Questo oggetto ha la definizione seguente.

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; }
}

Può restituire una risposta creando un nuovo oggetto e restituendolo dal suo endpoint.

return new ApiResponse {
    StatusCode = 401
};

Quando definisce il contenuto di un endpoint, tenga presente che il codice viene aggiunto a una classe con nome generato dinamicamente con una singola funzione Execute. Il suo codice deve avere una sintassi valida per tale file sorgente.

using PowerShellUniversal;

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

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

Può accedere al contenitore di servizi di PowerShell Universal all'interno del suo endpoint accedendo alla proprietà ServiceProvider nell'endpoint. Attualmente non documentiamo i servizi interni di PowerShell Universal.

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

Riferimenti

Può controllare quali assembly vengono referenziati utilizzando la parola chiave #ref. Il valore può essere un file DLL nella directory di installazione di PowerShell Universal oppure il percorso completo di un altro assembly.

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

Using dei namespace

Può fare riferimento a un namespace utilizzando la parola chiave #using.

#using System.Management.Automation

Variabili

Può accedere alle variabili negli endpoint C# con i metodi GetVariable, GetSecretString e GetSecretCredential.

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

Per accedere a un PSCredential, può procedere come segue.

#ref System  
#ref System.Management.Automation

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