Erste Schritte mit ASP.NET Web-API 2 (C#)

von Mike Wasson

Abgeschlossenes Projekt herunterladen

In diesem Lernprogramm verwenden Sie ASP.NET Web-API, um eine Web-API zu erstellen, die eine Liste von Produkten zurückgibt.

HTTP dient nicht nur der Bereitstellung von Webseiten. HTTP ist auch eine leistungsstarke Plattform zum Erstellen von APIs, die Dienste und Daten verfügbar machen. HTTP ist einfach, flexibel und allgegenwärtig. Fast jede Plattform, die Sie sich vorstellen können, verfügt über eine HTTP-Bibliothek, sodass HTTP-Dienste eine breite Palette von Clients erreichen können, einschließlich Browsern, mobilen Geräten und herkömmlichen Desktopanwendungen.

ASP.NET Web-API ist ein Framework zum Erstellen von Web-APIs über .NET Framework.

Im Lernprogramm verwendete Softwareversionen

• Visual Studio 2017
• Web-API 2

Eine neuere Version dieses Lernprogramms finden Sie unter Erstellen einer Web-API mit ASP.NET Core und Visual Studio für Windows .

Erstellen eines Web-API-Projekts

In diesem Lernprogramm verwenden Sie ASP.NET Web-API, um eine Web-API zu erstellen, die eine Liste von Produkten zurückgibt. Die Front-End-Webseite verwendet jQuery zum Anzeigen der Ergebnisse.

Starten Sie Visual Studio, und wählen Sie auf der Startseite "Neues Projekt" aus. Oder wählen Sie im Menü "Datei " die Option "Neu " und dann "Projekt" aus.

Wählen Sie im Bereich "Vorlagen " die Option "Installierte Vorlagen " aus, und erweitern Sie den Knoten "Visual C# ". Wählen Sie unter Visual C#"Web" aus. Wählen Sie in der Liste der Projektvorlagen ASP.NET Webanwendung aus. Benennen Sie das Projekt "ProductsApp", und klicken Sie auf "OK".

Wählen Sie im Dialogfeld "Neues ASP.NET Projekt " die Vorlage "Leer " aus. Überprüfen Sie unter "Ordner und Kernverweise hinzufügen für" die Web-API. Klicke auf OK.

Hinzufügen eines Modells

Ein Modell ist ein Objekt, das die Daten in Ihrer Anwendung darstellt. ASP.NET Web-API kann Ihr Modell automatisch in JSON, XML oder ein anderes Format serialisieren und dann die serialisierten Daten in den Textkörper der HTTP-Antwortnachricht schreiben. Solange ein Client das Serialisierungsformat lesen kann, kann es das Objekt deserialisieren. Die meisten Clients können ENTWEDER XML oder JSON analysieren. Darüber hinaus kann der Client angeben, welches Format er möchte, indem er den Accept-Header in der HTTP-Anforderungsnachricht festlegt.

Beginnen wir mit dem Erstellen eines einfachen Modells, das ein Produkt darstellt.

Wenn der Projektmappen-Explorer noch nicht sichtbar ist, klicken Sie auf das Menü "Ansicht ", und wählen Sie den Projektmappen-Explorer aus. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Ordner "Modelle". Wählen Sie im Kontextmenü "Hinzufügen" und dann "Klasse" aus.

Nennen Sie die Klasse "Product". Fügen Sie der Klasse die folgenden Eigenschaften hinzu Product .

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

Hinzufügen eines Controllers

In der Web-API ist ein Controller ein Objekt, das HTTP-Anforderungen verarbeitet. Wir fügen einen Controller hinzu, der entweder eine Liste von Produkten oder ein einzelnes Produkt zurückgeben kann, das anhand der ID angegeben ist.

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Ordner "Controller". Wählen Sie "Hinzufügen" und dann " Controller" aus.

Wählen Sie im Dialogfeld " Gerüst hinzufügen " den Web-API-Controller " Leer" aus. Klicken Sie auf Hinzufügen.

Nennen Sie im Dialogfeld " Controller hinzufügen " den Controller "ProductsController". Klicken Sie auf Hinzufügen.

Das Gerüst erstellt eine Datei namens ProductsController.cs im Ordner "Controller".

Wenn diese Datei noch nicht geöffnet ist, doppelklicken Sie auf die Datei, um sie zu öffnen. Ersetzen Sie den Code in dieser Datei durch Folgendes:

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

Um das Beispiel einfach zu halten, werden Produkte in einem festen Array innerhalb der Controllerklasse gespeichert. In einer echten Anwendung würden Sie natürlich eine Datenbank abfragen oder eine andere externe Datenquelle verwenden.

Der Controller definiert zwei Methoden, die Produkte zurückgeben:

• Die GetAllProducts Methode gibt die gesamte Liste der Produkte als IEnumerable<Product> Type zurück.
• Die GetProduct Methode sucht ein einzelnes Produkt anhand seiner ID.

Das ist alles! Sie verfügen über eine funktionierende Web-API. Jede Methode auf dem Controller entspricht einer oder mehreren URIs:

Für die GetProduct Methode ist die ID im URI ein Platzhalter. Um z. B. das Produkt mit der ID 5 abzurufen, lautet api/products/5der URI .

Weitere Informationen dazu, wie Web-API HTTP-Anforderungen an Controllermethoden weiterleitet, finden Sie unter Routing in ASP.NET Web-API.

Aufrufen der Web-API mit Javascript und jQuery

In diesem Abschnitt fügen wir eine HTML-Seite hinzu, die AJAX zum Aufrufen der Web-API verwendet. Wir verwenden jQuery, um die AJAX-Aufrufe vorzunehmen und die Seite mit den Ergebnissen zu aktualisieren.

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie "Hinzufügen" und dann " Neues Element" aus.

Wählen Sie im Dialogfeld "Neues Element hinzufügen " den Webknoten unter Visual C# und dann das HTML-Seitenelement aus. Nennen Sie die Seite "index.html".

Ersetzen Sie alles in dieser Datei durch Folgendes:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

Es gibt mehrere Möglichkeiten, jQuery abzurufen. In diesem Beispiel habe ich das Microsoft Ajax CDN verwendet. Sie können es auch von http://jquery.com/ herunterladen, und die ASP.NET-"Web-API"-Projektvorlage enthält ebenfalls jQuery.

Abrufen einer Liste von Produkten

Um eine Liste von Produkten abzurufen, senden Sie eine HTTP GET-Anforderung an "/api/products".

Die jQuery getJSON-Funktion sendet eine AJAX-Anforderung. Die Antwort enthält ein Array von JSON-Objekten. Die done Funktion gibt einen Rückruf an, der aufgerufen wird, wenn die Anforderung erfolgreich ist. Im Rückruf aktualisieren wir das DOM mit den Produktinformationen.

$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

Abrufen eines Produkts anhand der ID

Um ein Produkt anhand der ID abzurufen, senden Sie eine HTTP GET-Anforderung an "/api/products/id", wobei die ID die Produkt-ID ist.

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

Wir rufen getJSON weiterhin auf, um die AJAX-Anforderung zu senden, aber dieses Mal setzen wir die ID in den Anforderungs-URI. Die Antwort dieser Anforderung ist eine JSON-Darstellung eines einzelnen Produkts.

Ausführen der Anwendung

Drücken Sie F5, um das Debuggen der Anwendung zu starten. Die Webseite sollte wie folgt aussehen:

Um ein Produkt anhand der ID zu erhalten, geben Sie die ID ein, und klicken Sie auf "Suchen":

Wenn Sie eine ungültige ID eingeben, gibt der Server einen HTTP-Fehler zurück:

Verwenden von F12 zum Anzeigen der HTTP-Anforderung und -Antwort

Wenn Sie mit einem HTTP-Dienst arbeiten, kann es sehr nützlich sein, die HTTP-Anforderungs- und Antwortnachrichten anzuzeigen. Dazu können Sie die F12-Entwicklertools in Internet Explorer 9 verwenden. Drücken Sie in Internet Explorer 9 F12 , um die Tools zu öffnen. Klicken Sie auf die Registerkarte "Netzwerk ", und drücken Sie " Aufzeichnung starten". Kehren Sie nun zur Webseite zurück, und drücken Sie F5 , um die Webseite neu zu laden. Internet Explorer erfasst den HTTP-Datenverkehr zwischen dem Browser und dem Webserver. Die Zusammenfassungsansicht zeigt den gesamten Netzwerkdatenverkehr für eine Seite an:

Suchen Sie den Eintrag für den relativen URI "api/products/". Wählen Sie diesen Eintrag aus, und klicken Sie auf "Zur detaillierten Ansicht wechseln". In der Detailansicht gibt es Reiter zum Anzeigen der Anforderungs- und Antwortheader und -inhalte. Wenn Sie beispielsweise auf die Registerkarte " Anforderungsheader " klicken, können Sie sehen, dass der Client "application/json" im Accept-Header angefordert hat.

Wenn Sie auf die Registerkarte "Antworttext" klicken, können Sie sehen, wie die Produktliste in JSON serialisiert wurde. Andere Browser verfügen über ähnliche Funktionen. Ein weiteres nützliches Tool ist Fiddler, ein Web-Debugging-Proxy. Sie können Fiddler verwenden, um Ihren HTTP-Datenverkehr anzuzeigen, und auch zum Verfassen von HTTP-Anforderungen, wodurch Sie die vollständige Kontrolle über die HTTP-Header in der Anforderung erhalten.

Sehen Sie diese App auf Azure laufen

Möchten Sie sehen, dass die fertige Website als Live-Web-App ausgeführt wird? Sie können eine vollständige Version der App in Ihrem Azure-Konto bereitstellen.

Sie benötigen ein Azure-Konto, um diese Lösung in Azure bereitzustellen. Wenn Sie noch nicht über ein Konto verfügen, haben Sie die folgenden Optionen:

• Öffnen Sie ein Kostenloses Azure-Konto – Sie erhalten Guthaben, mit dem Sie kostenpflichtige Azure-Dienste ausprobieren können, und auch nachdem sie verwendet wurden, können Sie das Konto behalten und kostenlose Azure-Dienste verwenden.
• Aktivieren sie die Vorteile von MSDN-Abonnenten – Ihr MSDN-Abonnement bietet Ihnen monatlich Gutschriften, die Sie für kostenpflichtige Azure-Dienste verwenden können.

Nächste Schritte

• Ein vollständiges Beispiel für einen HTTP-Dienst, der POST-, PUT- und DELETE-Aktionen unterstützt und in eine Datenbank schreibt, finden Sie unter Verwenden der Web-API 2 mit Entity Framework 6.
• Weitere Informationen zum Erstellen dynamischer und reaktionsfähiger Webanwendungen über einen HTTP-Dienst finden Sie unter ASP.NET Single Page Application.
• Informationen zum Bereitstellen eines Visual Studio-Webprojekts für Azure App Service finden Sie unter Erstellen einer ASP.NET Web-App in Azure App Service.