Verwenden eines REST-basierten Webdiensts

Artikel
09/30/2024

Browse sample. Sehen Sie sich den Beispielcode an.

Representational State Transfer (REST) ist ein Architekturstil zum Erstellen von Webdiensten. REST-Anfragen werden in der Regel über HTTPS gestellt, wobei dieselben HTTP-Verben verwendet werden, die Webbrowser zum Abrufen von Webseiten und zum Senden von Daten an Server verwenden. Es gibt folgende Verben:

GET: Dieser Vorgang wird verwendet, um Daten aus dem Webdienst abzurufen.
POST: Dieser Vorgang wird verwendet, um ein neues Datenelement im Webdienst zu erstellen.
PUT: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu aktualisieren.
PATCH: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu aktualisieren, indem eine Reihe von Anweisungen zur Änderung des Elements beschrieben wird.
DELETE: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu löschen.

Webdienst-APIs, die dem REST-Standard entsprechen, werden wie folgt definiert:

Ein Basis-URI.
HTTP-Methoden wie GET, POST, PUT, PATCH oder DELETE.
Ein Medientyp für die Daten, wie etwa JavaScript Object Notation (JSON) oder XML.

REST-basierte Webdienste verwenden in der Regel JSON-Nachrichten, um Daten an den Client zurückzugeben. JSON ist ein textbasiertes Datenaustauschformat, das kompakte Nutzlasten erzeugt, was zu geringeren Bandbreitenanforderungen beim Senden von Daten führt. Die Einfachheit von REST hat dazu beigetragen, dass sie die primäre Methode für den Zugriff auf Webdienste in mobilen Apps ist.

Hinweis

Für den Zugriff auf einen Webdienst ist häufig eine asynchrone Programmierung erforderlich. Weitere Informationen zur asynchronen Programmierung finden Sie unter Asynchrone Programmierung mit async und await.

Webservicevorgänge

Der Beispiel-REST-Dienst wurde mit ASP.NET Core geschrieben und stellt die folgenden Vorgänge bereit:

Vorgang	HTTP-Methode	Relative URL	Parameter
Abrufen einer Liste von todo-Elementen	GET	/api/todoitems/
Erstellen eines neuen todo-Elements	POST	/api/todoitems/	Ein JSON-formatiertes todoItem-Objekt
Aktualisieren eines todo-Elements	PUT	/api/todoitems/	Ein JSON-formatiertes todoItem-Objekt
Löschen eines todo-Elements	DELETE	/api/todoitems/{id}

Die .NET MAUI-App und der Webdienst verwenden die TodoItem-Klasse, um die angezeigten und an den Webdienst gesendeten Daten für den Speicher zu modellieren:

public class TodoItem
{
    public string ID { get; set; }
    public string Name { get; set; }
    public string Notes { get; set; }
    public bool Done { get; set; }
}

Die ID-Eigenschaft dient der eindeutigen Identifizierung jedes TodoItem-Objekts und wird vom Webdienst zur Identifizierung der zu aktualisierenden oder zu löschenden Daten verwendet. Um beispielsweise TodoItem mit der ID 6bb8a868-dba1-4f1a-93b7-24ebce87e243 zu löschen, sendet die .NET MAUI-App eine DELETE-Anforderung an https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243.

Wenn das Web-API-Framework eine Anforderung empfängt, leitet es die Anforderung an eine Aktion weiter. Diese Aktionen sind öffentliche Methoden in der TodoItemsController-Klasse. Das Web-API-Framework verwendet Routing-Middleware, um die URLs eingehender Anfragen abzugleichen und sie Aktionen zuzuordnen. REST-APIs sollten Attribut-Routing verwenden, um die Funktionalität der App als eine Reihe von Ressourcen zu modellieren, deren Operationen durch HTTP-Verben dargestellt werden. Beim Attributrouting werden Aktionen mithilfe von Attributen direkt Routenvorlagen zugeordnet. Weitere Informationen zum Attribut-Routing finden Sie unter Attribut-Routing für REST-APIs. Weitere Informationen zum Erstellen des REST-Dienstes mit ASP.NET Core finden Sie unter Erstellen von Backend-Diensten für native mobile Anwendungen.

Erstellen des HTTPClient-Objekts

Eine .NET Multiplatform App UI (.NET MAUI)-App kann einen REST-basierten Webdienst nutzen, indem sie mit der HttpClient-Klasse Anfragen an den Webdienst sendet. Diese Klasse bietet Funktionen zum Senden von HTTP-Anfragen und Empfangen von HTTP-Antworten von einer URI-identifizierten Ressource. Jede Anfrage wird als asynchroner Vorgang gesendet.

Das HttpClient-Objekt sollte auf Klassenebene deklariert werden, damit es so lange besteht, wie die Anwendung HTTP-Anfragen stellen muss:

public class RestService
{
    HttpClient _client;
    JsonSerializerOptions _serializerOptions;

    public List<TodoItem> Items { get; private set; }

    public RestService()
    {
        _client = new HttpClient();
        _serializerOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        };
    }
    ...
}

Das JsonSerializerOptions-Objekt wird verwendet, um die Formatierung der JSON-Nutzlast zu konfigurieren, die von dem Webdienst empfangen und an den Webdienst gesendet wird. Weitere Informationen finden Sie unter Instanziieren von JsonSerializerOptions-Instanzen mit System.Text.Json.

Abrufen von Daten

Die HttpClient.GetAsync-Methode wird verwendet, um eine GET-Anforderung an den durch den URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen:

public async Task<List<TodoItem>> RefreshDataAsync()
{
    Items = new List<TodoItem>();

    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));
    try
    {
        HttpResponseMessage response = await _client.GetAsync(uri);
        if (response.IsSuccessStatusCode)
        {
            string content = await response.Content.ReadAsStringAsync();
            Items = JsonSerializer.Deserialize<List<TodoItem>>(content, _serializerOptions);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }

    return Items;
}

Die Daten werden vom Webdienst als HttpResponseMessage-Objekt empfangen. Sie enthält Informationen zur Antwort, einschließlich Statuscode, Headern und beliebigem Text. Der REST-Dienst sendet in seiner Antwort einen HTTP-Statuscode, der über die HttpResponseMessage.IsSuccessStatusCode-Eigenschaft abgerufen werden kann, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Bei diesem Vorgang sendet der REST-Dienst in der Antwort den HTTP-Statuscode 200 (OK), der anzeigt, dass die Anforderung erfolgreich war und die angeforderten Informationen in der Antwort enthalten sind.

War der HTTP-Vorgang erfolgreich, wird der Inhalt der Antwort gelesen. Die HttpResponseMessage.Content-Eigenschaft stellt den Inhalt der Antwort dar und ist vom Typ HttpContent. Die HttpContent-Klasse steht für den HTTP-Textkörper und die Inhaltsheader, wie etwa Content-Type und Content-Encoding. Der Inhalt wird dann mit der HttpContent.ReadAsStringAsync-Methode in ein string eingelesen. Die string wird dann von JSON zu einem List von TodoItem Objekten deserialisiert.

Warnung

Die Verwendung der ReadAsStringAsync-Methode zum Abruf einer umfangreichen Antwort kann negative Auswirkungen auf die Leistung haben. In solchen Fällen sollte die Antwort direkt deserialisiert werden, damit sie nicht vollständig gepuffert werden muss.

Daten erstellen

Die HttpClient.PostAsync-Methode wird verwendet, um eine POST-Anfrage an den durch den URI angegebenen Webdienst zu senden und anschließend die Antwort des Webdienstes zu empfangen:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));

    try
    {
        string json = JsonSerializer.Serialize<TodoItem>(item, _serializerOptions);
        StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = null;
        if (isNewItem)
            response = await _client.PostAsync(uri, content);
        else
            response = await _client.PutAsync(uri, content);

        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully saved.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

In diesem Beispiel wird die TodoItem-Instanz in eine JSON-Nutzlast serialisiert, die an den Webdienst gesendet wird. Diese Nutzlast wird dann in den Textkörper des HTTP-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anfrage mit der PostAsync-Methode gestellt wird.

Der REST-Dienst sendet in seiner Antwort einen HTTP-Statuscode, der über die HttpResponseMessage.IsSuccessStatusCode-Eigenschaft abgerufen werden kann, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die typischen Antworten für diesen Vorgang sind:

201 (CREATED): Die Anforderung führte dazu, dass eine neue Ressource erstellt wurde, bevor die Antwort gesendet wurde.
400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
409 (CONFLICT): Die Anforderung konnte aufgrund eines Konflikts auf dem Server nicht ausgeführt werden.

Daten aktualisieren

Die HttpClient.PutAsync-Methode wird verwendet, um eine PUT-Anforderung an den vom URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  response = await _client.PutAsync(uri, content);
  ...
}

Die Funktionsweise der PutAsync-Methode ist identisch mit der PostAsync-Methode, die für die Erstellung von Daten im Webdienst verwendet wird. Die möglichen Antworten, die vom Webdienst gesendet werden, unterscheiden sich jedoch.

204 (NO CONTENT): Die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.
400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
404 (NOT FOUND): Die angeforderte Ressource ist auf dem Server nicht vorhanden.

Löschen von Daten

Die HttpClient.DeleteAsync-Methode wird verwendet, um eine DELETE-Anforderung an den durch den URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen:

public async Task DeleteTodoItemAsync(string id)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, id));

    try
    {
        HttpResponseMessage response = await _client.DeleteAsync(uri);
        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully deleted.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

204 (NO CONTENT): Die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.
400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
404 (NOT FOUND): Die angeforderte Ressource ist auf dem Server nicht vorhanden.

Lokale Entwicklung

Wenn Sie einen REST-Webdienst mit einem Framework wie ASP.NET Core Web API lokal entwickeln, können Sie Ihren Webdienst und Ihre .NET MAUI-Anwendung gleichzeitig debuggen. Um in diesem Szenario Ihren Webdienst über HTTP von Android-Emulatoren und iOS-Simulatoren aus zu nutzen, müssen Sie den HTTP-Verkehr im Klartext in Ihrer .NET MAUI-App aktivieren. Weitere Informationen finden Sie unter Verbinden mit lokalen Webdiensten von Android-Emulatoren und iOS-Simulatoren.

Freigeben über