Nutzen eines REST-Diensts mit HttpClient
Viele moderne Webdienste implementieren die REST-Architektur. Diese Struktur ermöglicht es einem Webdienst, Vorgänge und Daten über eine Reihe von klar definierten Endpunkten verfügbar zu machen. Die Anforderungen, die Client-Apps an einen REST-Webdienst senden, um Daten abzurufen, zu ändern, zu erstellen oder zu löschen, verwenden eine vordefinierte Gruppe von Verben. Ein REST-Webdienst antwortet auf diese Anforderungen auf standardisierte Weise. Dieser Ansatz erleichtert das Erstellen von Client-Apps.
Das REST-Modell basiert auf dem HTTP-Protokoll. Eine .NET MAUI-Anwendung kann Anforderungen mithilfe der HttpClient-Klasse an einen REST-Webdienst senden. In dieser Lerneinheit erfahren Sie mehr über HttpClient und wie Sie diese Klasse für die Interaktion mit einem REST-Webdienst verwenden.
Was ist die HttpClient-Klasse?
HttpClient ist eine .NET-Klasse, mit der eine App HTTP-Anforderungen senden und HTTP-Antworten von einem REST-Webdienst empfangen kann. Eine Reihe von URIs identifiziert die Ressourcen, die der Webdienst verfügbar macht. Ein URI kombiniert die Adresse des Webdiensts mit dem Namen einer Ressource, die unter dieser Adresse verfügbar ist.
Die HttpClient-Klasse verwendet eine taskbasierte API für die Leistung und bietet Ihnen Zugriff auf Informationen in Anforderungsnachrichten wie HTTP-Headern und Statuscodes sowie Nachrichtentexten, die die tatsächlich gesendeten und empfangenen Daten enthalten.
Die HttpClient-Klasse befindet sich im System.Net.Http-Namespace. Eine App kann ein HttpClient-Objekt mithilfe des Standardkonstruktors erstellen:
using System.Net.Http;
...
var client = new HttpClient();
Ausführen von CRUD-Vorgängen mit einem HttpClient-Objekt
Ein REST-Webdienst ermöglicht es einem Client, Vorgänge für Daten über eine Reihe von HTTP-Verben auszuführen. Die Aufgabe des HTTP-Verbs ist es, die gewünschte Aktion anzugeben, die für die Ressource ausgeführt werden soll. Es gibt viele HTTP-Verben. Die vier am häufigsten verwendeten sind jedoch POST, GET, PUT und DELETE. Ein Dienst kann diese Verben implementieren, um es einer Clientanwendung zu ermöglichen, den Lebenszyklus von Objekten zu verwalten, indem er CRUD-Vorgänge (Create, Read, Update, Delete) wie folgt ausführt:
Das
POST-Verb gibt an, dass Sie eine neue Ressource erstellen möchten.Das
GET-Verb gibt an, dass Sie eine Ressource abrufen möchten.Das
PUT-Verb gibt an, dass Sie eine Ressource aktualisieren möchten.Das
DELETE-Verb gibt an, dass Sie eine Ressource löschen möchten.
Erstellen einer neuen Ressource mit HttpClient
Um eine neue Ressource mithilfe von HttpClient zu erstellen, können Sie die SendAsync-Methode verwenden und ihr ein HttpRequestMessage-Objekt übergeben.
HttpRequestMessage soll die Anforderung modellieren, die an den Webdienst gesendet wird. Sie geben das HTTP-Verb und die URL des Webdiensts an und füllen die zu sendende Payload über die HttpRequestMessage.Content-Eigenschaft mit Daten auf.
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Dieses Codefragment führt die folgenden Aufgaben aus:
- Es erstellt eine Instanz von
HttpClientnamens client, die zum Senden einer Nachricht verwendet wird. - Es erstellt eine Instanz von
HttpRequestMessagenamens message, die zum Modellieren der Nachricht verwendet wird. message verfügt über das HTTP-Verb und die URL. - Es legt die
Content-Eigenschaft vonHttpRequestMessagemithilfe derJsonContent.Create-Funktion fest. Diese Funktion serialisiert die part-Variable automatisch in JSON, das zum Senden an den Webdienst geeignet ist. - Es sendet die Nachricht mithilfe des
HttpClient-Objekts. Es wird eineHttpResponseMessagezurückgegeben, die Informationen wie den Statuscode und vom Webdienst zurückgegebene Informationen enthält.
Lesen einer Ressource mit HttpClient
Sie können eine Ressource aus einem Webdienst mit der gleichen Technik wie zuvor beschrieben lesen, mit Ausnahme der Initialisierung von HttpRequestMessage mit HttpMethod.Get. HttpClient verfügt jedoch über eine Reihe von praktischen Methoden, die Abkürzungen bereitstellen.
Verwenden Sie zum Lesen einer Ressource mithilfe von HTTPClient die GetStringAsync-Methode wie im nächsten Beispiel gezeigt:
HttpClient client = new HttpClient();
string text = await client.GetStringAsync("https://...");
Die GetStringAsync-Methode nimmt einen URI an, der auf die Ressource verweist, und gibt eine Antwort als Zeichenfolge zurück. Die Zeichenfolgenantwort ist die Ressource, die die App angefordert hat. Das Format der Antwortdaten entspricht dem Standardformat für den angeforderten Dienst, z. B. JSON oder XML. Eine App kann den Webdienst darüber informieren, dass die Daten in einem bestimmten Format zurückgegeben werden müssen, indem sie den MediaTypeWithQualityHeaderValue-Header hinzufügt. Wenn die Anwendung beispielsweise verlangt, dass die Daten im JSON-Format zurückgesendet werden, kann der folgende Code verwendet werden:
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
In diesem Beispiel wird das Ergebnis als Zeichenfolge zurückgegeben und enthält nur den Nachrichtentext der Antwort. Rufen Sie die GetAsync-Methode auf, um die gesamte Antwort einschließlich Header, Textkörper und Statuscode abzurufen. Die Daten werden als HttpResponseMessage-Objekt zurückgegeben.
Aktualisieren einer Ressource mit HttpClient
Verwenden Sie zum Aktualisieren einer Ressource mithilfe von HttpClient eine mit einem PUT-Verb initialisierte HttpRequestMessage. Der folgende Code ähnelt dem Code, der zum Erstellen einer neuen Ressource erforderlich ist:
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Hinweis
Der grundlegende Unterschied zwischen POST und PUT ist Idempotenz. Wenn Sie dieselbe PUT-Anforderung mehrmals wiederholen, wird dieselbe Ressource mit denselben Daten aktualisiert, und der Effekt ist derselbe, als ob die Anforderung nur ein Mal gesendet worden wäre. Wenn Sie dieselbe POST-Anforderung mehrmals ausgeben, führt dies dazu, dass der REST-Dienst mehrere Kopien der Ressource erstellt.
Löschen einer Ressource mit HttpClient
Um eine Ressource mithilfe von HttpClient zu löschen, rufen Sie SendAsync mit einer HttpRequestMessage auf, die mit einem DELETE-Verb initialisiert wurde:
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);
HttpResponseMessage response = await client.SendAsync(message);
Die Antwort enthält den Header, den Statuscode und das gelöschte Objekt.
Verarbeiten von Antworten auf eine Anforderung
Alle HTTP-Anforderungen geben eine Antwortnachricht zurück. Die Daten in der Antwort hängen davon ab, welches Verb von der App gesendet wurde. Der Antworttext einer HTTP GET-Anforderung enthält beispielsweise die Daten für die angeforderte Ressource.
Die Antworttext der POST-Anforderung gibt eine Kopie der erstellten Ressource zurück. Der Antworttext einer PUT-Anforderung sollte jedoch leer sein.
Sie sollten den Statuscode in der Antwortnachricht immer überprüfen und verarbeiten. Liegt dieser Statuscode im Bereich 200 (200, 201, 202 usw.), gilt der Vorgang als erfolgreich, auch wenn zu einem späteren Zeitpunkt weitere Informationen erforderlich sein können.
Ein Statuscode im Bereich 300 gibt an, dass die Anforderung möglicherweise vom Webdienst an eine andere Adresse umgeleitet wurde, möglicherweise als Ergebnis einer Verschiebung einer Ressource an einen anderen Speicherort.
Ein Statuscode im Bereich 400 gibt einen Client- oder Anwendungsfehler an. Der Statuscode 403 bedeutet beispielsweise, dass der Webdienst die Authentifizierung des Benutzers verlangt, die App diese jedoch nicht vorgenommen hat. Der Statuscode 404 tritt auf, wenn die App versucht, auf eine Ressource zuzugreifen, die nicht vorhanden ist.
Statuscodes im Bereich 500 deuten auf einen serverseitigen Fehler hin, z. B. dass der Dienst nicht verfügbar oder zu ausgelastet ist, um die Anforderung zu verarbeiten.
Das HttpResponseMessage-Objekt, das von einer über ein HttpClient-Objekt gesendeten Anforderung zurückgegeben wird, kann einen Großteil der Komplexität der Verarbeitung der verschiedenen Statuscodes abstrahieren. Dieses Codefragment zeigt, wie überprüft wird, ob der Statuscode in einer Antwortnachricht auf Erfolg hinweist, und wie Statuscodes verarbeitet werden, die auf einen Fehler hindeuten.
static readonly HttpClient client = new HttpClient();
...
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
{
//... Initiate the HttpRequest
HttpResponseMessage response = await client.SendAsync(msg);
response.EnsureSuccessStatusCode(); // Check that the status code is in the 200 range. Throw an HttpRequestException if not
string responseBody = await response.Content.ReadAsStringAsync();
... // Handle the response
}
catch(HttpRequestException e)
{
... // Handle any status codes that indicate an error.
// The status code is available in the field e.StatusCode
}