REST Services

Important

Dieses Feature ist aktuell noch nicht in vollwertigem Funktionsumfang verfügbar. Sie können sich bereits mit der neuen Lösung auseinandersetzen und Nutzungserfahrungen sammeln, ein produktiver Einsatz ist allerdings ausdrücklich noch nicht vorgesehen.

Es gibt die Möglichkeit in Framework Studio REST Services zu erstellen. Hierfür können die CodeFiles oder die Modular Components mit dem CompileStep RestService verwendet werden.

Die REST Services in Framework Studio basieren auf Microsoft.AspNetCore in Version 2.3.0. Diese Version bietet Zugang zu modernen REST Technologien und ist dabei net48 kompatibel. Beachten Sie allerdings die geltenden Einschränkungen.

Hinweise

Es wurde bewusst die Entscheidung getroffen die REST Services so offen wie möglich zu gestalten, wodurch viel Freiheit in der Programmierung ermöglicht wird. Allerdings bedeutet das auch, dass sich um viele Dinge selbst gekümmert werden muss:

Die Konfiguration muss eigenständig im Run- bzw. Publish-Wizard definiert werden!
Der für das Debugging notwendige Code inkl. Einstellung im Run-Wizard muss eigenständig hinzugefügt bzw. gesetzt werden!
Einsprungpunkte für Customizing müssen eigenständig implementiert werden!
Alle Elemente, wie z.B. Controller, Services, Middlewares, etc., müssen in der Startup-Klasse selbstständig hinzugefügt werden!
Um Dependency Injection nutzen zu können, müssen die entsprechenden Methoden im Service aufgerufen werden!
Um ein GlobalObject nutzen zu können, muss ein eigenes innerhalb der Requests erzeugt werden!

Zusammengefasst: Framework Studio bietet das Hosting des Services. Die Programmierung und die Konfiguration des REST Services liegt in der Verantwortung der Entwickler*innen.

Anlegen eines REST Services

Ein REST Service kann in Framework Studio auf zwei Arten angelegt werden:

als Modular Component mit dem CompileStep RestService
als Code File mit dem CompileStep RestService

In beiden Fällen muss die enthaltene Klasse das Interface IFSRestService implementieren.

Über Modular Component

Um den Einstieg mit REST Services zu vereinfachen, gibt es beim Hinzufügen eines neuen Elements die Optionen "RestService". Dies legt im aktuellen Namespace zwei Modular Component Klassen an:

mcRestService:

CompileStep: RestService
Interface: FS.Hosting.Shared.IFSRestService
Es werden zusätzlich folgende Methoden – teilweise mit Inhalt – angelegt:
- int Run(string[] args)
- IWebHostBuilder CreateWebHostBuilder(string[] args) — verweist per .UseStartup<mcStartup>() auf die Startup-Klasse

mcStartup:

Es werden folgende Methoden angelegt:
- virtual void ConfigureServices(IServiceCollection services)
- virtual void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)

Über Code File

Alternativ kann ein REST Service auch über ein Code File angelegt werden. Im Gegensatz zur Modular Component werden beim Anlegen eines Code Files keine Voreinstellungen vorgenommen — Interface, CompileStep und die benötigten Methoden müssen eigenständig hinzugefügt werden.

Note

Code Files können nicht gecustomized werden. Für Szenarien, in denen Customizing benötigt wird, sollte der REST Service als Modular Component angelegt werden.

Notwendiger Inhalt des Code Files:

Compile Step: muss auf RestService gesetzt werden — ansonsten wird der Service vom FS-Hosting nicht als REST Service erkannt und gestartet.
Klasse mit IFSRestService: die Klasse muss das Interface FS.Hosting.Shared.IFSRestService implementieren.
int Run(string[] args): zentraler Einstiegspunkt. Muss den WebHost bauen und starten (CreateWebHostBuilder(args).BuildFSHost().Run()) und einen Exit-Code zurückgeben.
IWebHostBuilder CreateWebHostBuilder(string[] args): baut den WebHost, verknüpft die Startup-Klasse über .UseStartup<Startup>() und übernimmt die Konfiguration aus args.
Startup-Klasse: die in ASP.NET Core übliche Aufteilung in eine Startup-Klasse mit ConfigureServices und Configure wird empfohlen, siehe Startup-Klasse.

Startup-Klasse

Die Aufteilung in eine Service- und eine Startup-Klasse entspricht dem in ASP.NET Core etablierten Pattern und wird von der automatischen Generierung direkt unterstützt (Optionen "RestService", siehe oben).

Die Service-Klasse enthält int Run(string[] args) und IWebHostBuilder CreateWebHostBuilder(string[] args), die Startup-Klasse enthält void ConfigureServices(IServiceCollection services) und void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory).

Die IWebHostBuilder CreateWebHostBuilder(string[] args) nutzt .UseStartup<mcStartup>(), um dem Service seine Startup-Klasse mitzugeben. Ein vollständiges Beispiel inkl. DI gibt es hier.

IFSRestService und Argumente

Damit Framework Studio die REST Services korrekt erkennt und starten kann, muss die CodeFile oder Modular Component die Methode IFSRestService.Run(string[] args) implementieren.

Die an Run(string[] args) übergebenen Argumente werden vom FS-Hosting bereitgestellt und enthalten folgende Parameter:

Index	Name	Beschreibung
0	`--configfilepath`	Key
1	(Pfad)	Pfad zur JSON-Konfigurationsdatei
2	`--applicationName`	Key
3	(Name)	FullName des REST Services (Namespace.Name)
4	`--environment`	Key
5	(Umgebung)	`Development` oder `Production`
6	`--debug`	Key
7	(Flag)	`True` oder `False`

Debugging

Note

Der REST Service kann nicht über das TrayIcon im Debug-Modus gestartet werden. Das Debugging muss über den RunWizard aktiviert werden.

Im Development-Modus wird über den RunWizard die Debug-Option gesetzt. Der Debug-Wert wird über args[7] an den REST Service übergeben. Ist der Wert "True", kann ein Debugger angehängt werden:

public int Run(string[] args)
{
   // ...
    if (args[7] == "True")
        System.Diagnostics.Debugger.Launch();
    // ...
}

HTTPS-Entwicklungszertifikat

Für die lokale Entwicklung mit HTTPS muss ein selbst signiertes Entwicklungszertifikat erstellt und als vertrauenswürdig hinzugefügt werden. Voraussetzung ist ein installiertes .NET SDK (ab .NET Core 3.1+).

Einrichtung:

Cmd oder PowerShell als Administrator öffnen und folgenden Befehl ausführen:

dotnet dev-certs https --trust

Sicherheitsdialog bestätigen – Windows fragt, ob das Zertifikat installiert werden soll → Ja klicken.

Falls es Probleme gibt, muss das alte Zertifikat zuerst entfernt werden:

dotnet dev-certs https --clean

Prüfen ob es funktioniert hat:

dotnet dev-certs https --check --trust

Das Zertifikat landet im Windows-Zertifikatspeicher unter Vertrauenswürdige Stammzertifizierungsstellen (Current User).

Authentifizierung

Wie bei den Service Hosts, kann auch bei den REST Services die Authentifizierung aktiviert werden. Die Konfiguration erfolgt im RunWizard bzw. im Publish Wizard / Publish2Go auf der Registerkarte Authentication des jeweiligen REST Services.

Verwendung im Controller

Wenn die Authentifizierung aktiviert ist, kann über den DI-Container auf den IFSAuthenticationService zugegriffen werden:

[Route("api/[controller]")]
public class SecureController : Controller
{
    [HttpGet]
    public IActionResult Get()
    {
        var authService = FSServiceProvider.Current
            .GetRequiredService<IFSAuthenticationService>();

        if (!authService.IsAuthenticationEnabled)
        {
            return Ok("Authentifizierung ist deaktiviert");
        }

        var authorization = FSServiceProvider.Current
            .GetRequiredService<IFSAuthorization>();

        if (!authorization.Granted(myAccessUnit))
        {
            return Unauthorized();
        }

        return Ok(result);
    }
}

Note

Damit der IFSAuthenticationService zur Verfügung steht, muss Dependency Injection (UseFSHosting() / BuildFSHost()) und die FSServiceProviderScopeMiddleware korrekt eingerichtet sein.

Publish

Generell stehen den REST Services für den produktiven Betrieb alle Funktionen zur Verfügung, die auch die Service Hosts haben. Darunter zählen die Steuerung des ausführenden Users, Authentication mittels AuthService, RuntimeSupervisor-Kompatibilität, Trace-File-Support und Post-Publish-Commands.

Im Publish Wizard und in Publish2Go können die Einstellungen für das produktive Deployment der REST Services konfiguriert werden. |

Technische Hinweise & Troubleshooting

Aus technologischen Gründen haben die REST Services ein paar Eigenheiten, die beachtet werden sollten.

Isolierte AppDomain

Der jeweilige Development- bzw. Produktions-Host erstellt eine isolierte AppDomain (RestServiceDomain), in der die RestService-Assembly geladen und ausgeführt wird. Dies stellt sicher, dass der REST Service in einer sauberen Umgebung läuft.

Im Gegensatz zu den WCF-basierten Service Hosts haben die REST Services kein Port Sharing. Diese technische Möglichkeit gibt es bei den ASP.NET Core REST Services nicht 'out of the box'. Daher ist zu beachten, dass jedem REST Service (auch beim Start über den Run-Wizard) ein eigener Port zur Verfügung steht. Ist dies nicht der Fall, wird der Service entweder gar nicht oder nicht korrekt starten.

Default Port

Die ASP.NET Core REST Services werden über Kestrel gehostet. Das hat zur Folge, dass bei fehlendem oder fehlerhaftem Port die Default Port-Konfiguration zieht. Der Service hört dann auf folgende Endpunkte:

http://localhost:5000
https://localhost:5001

ASP.NET Core 2.3 auf net48

Die REST Services verwenden Microsoft.AspNetCore in Version 2.3.0 auf .NET Framework 4.8. Die 2.3.0 war die letzte ASP.NET Core Version, die auf dem klassischen .NET Framework lauffähig ist — ab Version 3.0 wird ausschließlich .NET Core / .NET 5+ unterstützt.

Das hat folgende praktische Auswirkungen:

Hosting-Modell: Es muss WebHost.CreateDefaultBuilder() mit IWebHostBuilder verwendet werden. Das neuere Host.CreateDefaultBuilder() (ab 3.0) steht nicht zur Verfügung.
Startup-Pattern: Es wird das klassische Startup-Klassen-Pattern mit ConfigureServices() und Configure() verwendet. Minimal Hosting und Top-Level Statements gibt es erst ab .NET 6.
MVC-Registrierung: services.AddMvc() und app.UseMvc() statt AddControllers() / MapControllers().
Environment-Interface: Es wird IHostingEnvironment verwendet (nicht IWebHostEnvironment, das ab 3.0 eingeführt wurde).
JSON-Serializer: Standard ist Newtonsoft.Json. System.Text.Json ist erst ab ASP.NET Core 3.0 verfügbar.
Kein Endpoint Routing: Das in 3.0 eingeführte Endpoint Routing (app.UseRouting() / app.UseEndpoints()) steht nicht zur Verfügung.
NuGet-Pakete: Zusätzlich eingebundene Pakete müssen net48-kompatibel sein. Viele neuere ASP.NET Core Pakete setzen .NET 6+ voraus und können nicht verwendet werden.

Warning

Viele aktuelle ASP.NET Core Tutorials und Beispiele im Internet basieren auf .NET 6+ und verwenden APIs, die auf der hier verwendeten Version 2.3 nicht verfügbar sind. Achten Sie bei der Recherche darauf, Dokumentation für ASP.NET Core 2.3 zu verwenden.

Table of Contents

REST Services

Important

Hinweise

Anlegen eines REST Services

Über Modular Component

Über Code File

Note

Startup-Klasse

IFSRestService und Argumente

Debugging

Note

HTTPS-Entwicklungszertifikat

Authentifizierung

Verwendung im Controller

Note

Publish

Technische Hinweise & Troubleshooting

Isolierte AppDomain

Port Sharing

Default Port

ASP.NET Core 2.3 auf net48

Warning