C#-API-Endpunkte

Identifier: PowerShellUniversal.Language.CSharp

Dieses Plugin erstellt eine C#-basierte Umgebung, mit der API-Endpunkte mit C#-Code erstellt werden können. Mit C# erstellte APIs sind viel schneller als PowerShell-basierte Endpunkte. Endpunkte werden direkt im PowerShell Universal-Dienst ausgeführt. Jede von Ihrem Endpunkt ausgelöste Ausnahme wird behandelt und ein gültiger Statuscode wird an den Aufrufer zurückgegeben.

Sie müssen Endpunkte mit dem Parameter -Path erstellen und die C#-Umgebung angeben, damit der Endpunkt ordnungsgemäß funktioniert.

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

Einen Endpunkt definieren

Innerhalb des C#-Endpunkts sind zwei Klassen von Interesse. Die erste ist die Variable request, die an den Endpunkt übergeben wird. Es handelt sich um ein ApiRequest-Objekt.

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

In Ihrem Endpunkt können Sie automatisch auf diese Variable zugreifen.

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

Der Endpunkt muss ein ApiResponse-Objekt zurückgeben. Dieses Objekt hat die folgende Definition.

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

Sie können eine Antwort zurückgeben, indem Sie ein neues Objekt erstellen und es von Ihrem Endpunkt zurückgeben.

return new ApiResponse {
    StatusCode = 401
};

Beachten Sie beim Definieren des Inhalts eines Endpunkts, dass der Code einer dynamisch benannten Klasse mit einer einzelnen Execute-Funktion hinzugefügt wird. Ihr Code sollte eine für eine solche Quelldatei gültige Syntax aufweisen.

using PowerShellUniversal;

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

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

Sie können auf den PowerShell Universal-Dienstcontainer innerhalb Ihres Endpunkts zugreifen, indem Sie in Ihrem Endpunkt auf die Eigenschaft ServiceProvider zugreifen. Wir dokumentieren derzeit nicht die internen Dienste von PowerShell Universal.

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

Referenzen

Sie können mit dem Schlüsselwort #ref steuern, welche Assemblys referenziert werden. Der Wert kann eine DLL-Datei im PowerShell Universal-Installationsverzeichnis oder der vollständige Pfad zu einer anderen Assembly sein.

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

Namespace Using

Sie können einen Namespace mit dem Schlüsselwort #using referenzieren.

#using System.Management.Automation

Variablen

Sie können in C#-Endpunkten mit den Methoden GetVariable, GetSecretString und GetSecretCredential auf Variablen zugreifen.

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

Um auf ein PSCredential zuzugreifen, können Sie Folgendes tun.

#ref System  
#ref System.Management.Automation

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