© DrHitch/Shutterstock.com
.NET Core 1.0 und 1.1

2 Web-APIs mit ASP.NET Core


ASP.NET Core bietet dank seines Middleware-Konzepts einen mächtigen Unterbau für Webframeworks, die mehr Abstraktion bieten. Ein solches Framework ist MVC, das nun auch die erste Wahl für Web-APIs darstellt.

Mit ASP.NET Core hat das Produktteam bei Microsoft sein Webframework komplett neu geschrieben. Das Ziel ist es, auch für .NET Core eine leichtgewichtige und plattformunabhängige Lösung für die Webentwicklung anzubieten. Wenn .NET Core noch keine Option ist, kann man es auch mit dem klassischen .NET 4.x betreiben. In diesem Fall läuft die Lösung zwar nur unter Windows, dafür kann sie jedoch auch bestehende .NET-Bibliotheken nutzen. Das darauf aufbauende ASP.NET Core MVC ist der Nachfolger von ASP.NET MVC 5, aber auch von ASP.NET Web API. Deswegen bietet es sich sowohl für die Entwicklung von Webanwendungen als auch für die Entwicklung von Web-APIs an.

Dieses Kapitel geht auf die Funktionsweise von ASP.NET Core ein und zeigt, wie sich ein Web-API mit MVC erstellen lässt. Das dazu verwendete Beispiel steht unter [1] zur Verfügung

Projekt erzeugen

Um mit Visual Studio 2015 an ASP.NET-Core-Projekten arbeiten zu können, benötigt man zunächst das von Microsoft unter [2] bereitgestellte Tooling. Es richtet die Projektvorlage „ASP.NET Core Web Application“ unter Visual C# | .NET Core ein. Künftige Versionen von Visual Studio werden diese Vorlage ab Werk beinhalten. Sie führt zum in Abbildung 2.1 dargestellten Dialog, der verschiedene Arten von ASP.NET-Core-Projekten anbietet.

image

Abbildung 2.1: Arten von ASP.NET-Core-Projekten

Die Vorlagen „Web API“ und „Web Application“ stützen sich auf ASP.NET MVC. Erstere beschränkt sich auf Web-APIs, Letztere erlaubt zusätzlich das serverseitige Rendern von Seiten. Die Projektvorlage „Empty“ richtet hingegen kein auf ASP.NET Core basierendes Framework wie MVC ein. Sie können jedoch manuell, in der Regel per NuGet, installiert und eingerichtet werden.

Im weiteren Verlauf nutzt der vorliegende Text die Vorlage „Empty“ und erweitert sie manuell um alle Aspekte, die zum Betrieb von ASP.NET Core MVC benötigt werden. Auf diese Weise veranschaulicht er auch jene Aspekte, die von den anderen Vorlagen eingerichtet werden. Für erste Schritte mit ASP.NET Core empfiehlt es sich auch, unter Authentication die Option „No Authentication“ zu wählen und das automatische Deployment in die Azure-Cloud zu deaktivieren. Beide Einstellungen finden sich auf der rechten Seite des Dialogs.

Beim Starten dieser Anwendung öffnet Visual Studio einen Browser, der die Überschrift „Hallo Welt“ anzeigt. Der nächste Abschnitt erklärt, wie es dazu kommt.

Middleware-Komponenten

Um HTTP-Anfragen entgegenzunehmen, nutzt ASP.NET Core eine Serverkomponente (Abb. 2.2). Sie leitet alle Anfragen an eine Pipeline mit Middleware-Komponenten weiter. Jede dieser Komponenten kann nun die Anfrage direkt beantworten oder zur Beantwortung beitragen. Eine Middleware-Komponente kann die Anfrage auch an ein Webframework wie zum Beispiel MVC weiterleiten. Dieses stößt in weiterer Folge Code der Webapplikation an, die auf dem Framework basiert. Die erhaltene Antwort leitet ASP.NET Core erneut durch die Pipeline. Nun hat abermals jede Komponente die Möglichkeit, die Antwort zu ergänzen. Beispielsweise könnten sie Kopfzeilen hinzufügen oder im Fehlerfall auf eine Fehlerseite umleiten. Danach sendet die Serverkomponente die Antwort zurück zum Aufrufer.

image

Abbildung 2.2: Middleware-Pipeline bei ASP.NET Core

Das Definieren der Middleware-Pipeline ist die erste Aufgabe der Webanwendung nach dem Start. Dabei kann sie abhängig von der aktuellen Ausführungsumgebung unterschiedliche Middleware-Komponenten registrieren. Beispielsweise bietet sich in einer Entwicklungsumgebung der Einsatz von Middleware-Komponenten an, die im Fall einer Exception umfangreiche Diagnoseinformationen preisgeben. Im Produktivbetrieb ist so etwas in der Regel nicht erwünscht, da Angreifer solche Informationen für ihre Zwecke nutzen können.

Zum Aufbauen der gewünschten Pipeline nutzt eine ASP.NET-Core-Anwendung eine Klasse, die in der Regel den Namen Startup trägt und per Definition die Methoden ConfigureServices und Configure (Listing 2.1) aufweist.

public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
}

public void Configure(
IApplicationBuilder app,
IHostingEnvironment env,
ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole();

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.Run(async (context) =>
{
await context.Response.WriteAsync("Hello World!");
});
}
}

Listing 2.1

Innerhalb von ConfigureServices kann die Webanwendung so genannte Services registrieren. Dabei handelt es sich um Klassen und Objekte, die der gesamten Anwendung zur Verfügung stehen sollen. Auf diese Weise lassen sich unter anderem die Klassen von Frameworks bereitstellen. Der einfache hier betrachtete Fall kommt (noch) ohne solche Services aus.

Die Methode Configure hat die Aufgabe, die Middleware-Pipeline aufzubauen. Diese registriert sie in der gewünschten Reihenfolge beim übergebenen IApplicationBuilder. Das übergebene IHostingEnvironment informiert über die Umgebung, in der die Anwendung läuft. Die an den dritten Parameter übergebene ILoggerFactory steuert das Protokollierungsverhalten der Anwendung.

Die hier betrachtete Implementierung legt zunächst mit AddConsole fest, dass ASP.NET Core zur Protokollierung die Konsole nutzen soll. Für erste Gehversuche ist dies ausreichend. Für den Produktiveinsatz empfiehlt sich stattdessen der Einsatz anderer Logger, die im Lieferumfang von ASP.NET Core enthalten sind.

Die Methode UseDeveloperExceptionPage fügt eine Middleware-Komponente hinzu, die detaillierte Informationen zu eventuell auftretenden Exceptions liefert. Da diese Komponente nur in der Entwicklungsumgebung zum Einsatz kommen soll, prüft das Beispiel diesen Umstand zunächst mit IsDevelopment. Die Funktionsweise dieser Eigenschaft ist denkbar einfach: Existiert eine Umgebungsvariable ASPNETCORE_ENVIRONMENT mit dem Wert Development, liefert sie true. Glücklicherweise setzt Visual Studio automatisch diese Variable, und bei Bedarf lässt sie sich in den Projekteigenschaften anpassen.

Eingebundene Pakete

Selbst die leere Projektvorlage bindet einige Pakete via NuGet ein:

  • Microsoft.AspNetCore.Diagnostics kümmert sich um die Anzeige von Fehlermeldungen und beherbergt zum Beispiel die hier verwendete Methode UseDeveloperExceptionPage.
  • Microsoft.Extensions.Logging.Console ...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Gewinner-Teams

Wir bieten Lizenz-Lösungen für Teams jeder Größe: Finden Sie heraus, welche Lösung am besten zu Ihnen passt.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang