Rozpocznij pracę z ASP.NET Web API 2 (C#)

Autor: Mike Wasson

Pobieranie ukończonego projektu

W tym samouczku użyjesz ASP.NET Web API w celu stworzenia API internetowego zwracającego listę produktów.

Protokół HTTP nie jest przeznaczony tylko do obsługi stron internetowych. Http to również zaawansowana platforma do tworzenia interfejsów API, które uwidaczniają usługi i dane. Protokół HTTP jest prosty, elastyczny i wszechobecny. Prawie każda platforma, o której można myśleć, ma bibliotekę HTTP, więc usługi HTTP mogą dotrzeć do szerokiej gamy klientów, w tym przeglądarek, urządzeń przenośnych i tradycyjnych aplikacji klasycznych.

ASP.NET Web API to framework do tworzenia interfejsów API oparty na .NET Framework.

Wersje oprogramowania używane w samouczku

• Visual Studio 2017
• Web API 2

Zobacz Tworzenie internetowego interfejsu API przy użyciu platformy ASP.NET Core i programu Visual Studio dla systemu Windows, aby zapoznać się z nowszą wersją tego samouczka.

Projekt interfejsu API sieci Web

W tym samouczku użyjesz ASP.NET Web API do utworzenia interfejsu API sieci Web, który zwraca listę produktów. Strona internetowa front-end używa biblioteki jQuery do wyświetlania wyników.

Uruchom program Visual Studio i wybierz pozycję Nowy projekt na stronie Start . Lub w menu Plik wybierz pozycję Nowy , a następnie pozycję Projekt.

W okienku Szablony wybierz pozycję Zainstalowane szablony i rozwiń węzeł Visual C# . W obszarze Visual C# wybierz pozycję Sieć Web. Na liście szablonów projektów wybierz pozycję ASP.NET Aplikacja internetowa. Nadaj projektowi nazwę "ProductsApp" i kliknij przycisk OK.

W oknie dialogowym Nowy projekt ASP.NET wybierz szablon Pusty . W obszarze "Dodaj foldery i podstawowe odwołania dla" sprawdź Web API. Kliknij przycisk OK.

Uwaga / Notatka

Projekt internetowego interfejsu API można również utworzyć przy użyciu szablonu "Internetowy interfejs API". Szablon internetowego interfejsu API używa ASP.NET MVC do udostępniania stron pomocy interfejsu API. Używam pustego szablonu na potrzeby tego samouczka, ponieważ chcę wyświetlić internetowy interfejs API bez wzorca MVC. Ogólnie rzecz biorąc, nie musisz znać ASP.NET MVC, aby używać interfejsu API sieci Web.

Dodawanie modelu

Model to obiekt reprezentujący dane w aplikacji. ASP.NET interfejs API sieci Web może automatycznie serializować model do formatu JSON, XML lub innego formatu, a następnie zapisywać serializowane dane w treści wiadomości odpowiedzi HTTP. Tak długo, jak klient może odczytać format serializacji, może deserializować obiekt. Większość klientów może analizować kod XML lub JSON. Ponadto klient może wskazać żądany format, ustawiając nagłówek Accept w komunikacie żądania HTTP.

Zacznijmy od utworzenia prostego modelu reprezentującego produkt.

Jeśli Eksplorator rozwiązań nie jest jeszcze widoczny, kliknij menu Widok i wybierz pozycję Eksplorator rozwiązań. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy folder Models. Z menu kontekstowego wybierz pozycję Dodaj , a następnie wybierz pozycję Klasa.

Nadaj klasie nazwę "Product". Dodaj następujące właściwości do Product klasy .

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; }
    }
}

Dodawanie kontrolera

W internetowym interfejsie API kontroler jest obiektem obsługującym żądania HTTP. Dodamy kontroler, który może zwrócić listę produktów lub jeden produkt określony przez identyfikator.

Uwaga / Notatka

Jeśli używasz ASP.NET MVC, znasz już kontrolery. Kontrolery internetowego interfejsu API są podobne do kontrolerów MVC, ale dziedziczą klasę ApiController zamiast klasy Controller .

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy folder Controllers. Wybierz pozycję Dodaj , a następnie wybierz pozycję Kontroler.

W oknie dialogowym Dodaj szkielet wybierz pozycję kontroler Web API — pusty. Kliknij przycisk Dodaj.

W oknie dialogowym Dodawanie kontrolera nadaj kontrolerowi nazwę "ProductsController". Kliknij przycisk Dodaj.

Szkielet tworzy plik o nazwie ProductsController.cs w folderze Controllers.

Uwaga / Notatka

Kontrolery nie muszą być umieszczane w folderze o nazwie Controllers. Nazwa folderu to wygodny sposób organizowania plików źródłowych.

Jeśli ten plik nie jest jeszcze otwarty, kliknij dwukrotnie plik, aby go otworzyć. Zastąp kod w tym pliku następującym kodem:

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);
        }
    }
}

Aby zachować prosty przykład, produkty są przechowywane w stałej tablicy wewnątrz klasy kontrolera. Oczywiście w rzeczywistej aplikacji należy wykonać zapytanie dotyczące bazy danych lub użyć innego zewnętrznego źródła danych.

Kontroler definiuje dwie metody, które zwracają produkty:

• Metoda GetAllProducts zwraca całą listę produktów jako typ IEnumerable<Product>.
• Metoda GetProduct wyszukuje pojedynczy produkt według jego identyfikatora.

To wszystko! Masz działający internetowy interfejs API. Każda metoda na kontrolerze odpowiada co najmniej jednemu identyfikatorowi URI:

Metoda kontrolera	URI
GetAllProducts	/api/products
PobierzProdukt	/api/products/id

W przypadku metody GetProduct, id w identyfikatorze URI jest symbolem zastępczym. Na przykład aby uzyskać produkt o identyfikatorze 5, identyfikator URI to api/products/5.

Aby uzyskać więcej informacji na temat sposobu kierowania żądań HTTP przez internetowy interfejs API do metod kontrolera, zobacz Routing w interfejsie API sieci Web ASP.NET.

Wywoływanie internetowego interfejsu API przy użyciu języka Javascript i zestawu jQuery

W tej sekcji dodamy stronę HTML, która używa AJAX do wywoływania web API. Użyjemy biblioteki jQuery, aby wykonać wywołania AJAX, a także zaktualizować stronę przy użyciu wyników.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Dodaj, a następnie wybierz pozycję Nowy element.

W oknie dialogowym Dodawanie nowego elementu wybierz węzeł internetowy w obszarze Visual C#, a następnie wybierz element Strona HTML . Nadaj stronie nazwę "index.html".

Zastąp wszystkie elementy w tym pliku następującymi elementami:

<!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>

Istnieje kilka sposobów, aby uzyskać jQuery. W tym przykładzie użyto usługi Microsoft Ajax CDN. Możesz również pobrać go z http://jquery.com/, a szablon projektu ASP.NET "Web API" również zawiera jQuery.

Pobieranie listy produktów

Aby uzyskać listę produktów, wyślij żądanie HTTP GET do "/api/products".

Funkcja jQuery getJSON wysyła żądanie AJAX. Odpowiedź zawiera tablicę obiektów JSON. Funkcja done określa wywołanie zwrotne, które jest wywoływane, jeśli żądanie powiedzie się. W funkcji zwrotnej zaktualizujemy DOM przy użyciu informacji o produkcie.

$(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'));
            });
        });
});

Pobieranie produktu według identyfikatora

Aby uzyskać produkt według ID, wyślij żądanie HTTP GET do adresu "/api/products/id", gdzie id oznacza ID produktu.

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);
        });
}

Nadal wywołujemy getJSON w celu wysłania żądania AJAX, ale tym razem umieszczamy identyfikator w URI żądania. Odpowiedź z tego żądania jest reprezentacją w formacie JSON pojedynczego produktu.

Uruchamianie aplikacji

Naciśnij klawisz F5, aby rozpocząć debugowanie aplikacji. Strona internetowa powinna wyglądać następująco:

Aby uzyskać produkt według identyfikatora, wprowadź identyfikator i kliknij przycisk Wyszukaj:

Jeśli wprowadzisz nieprawidłowy identyfikator, serwer zwróci błąd HTTP:

Wyświetlanie żądania HTTP i odpowiedzi przy użyciu klawisza F12

Podczas pracy z usługą HTTP może być bardzo przydatne wyświetlanie komunikatów żądania HTTP i odpowiedzi. Można to zrobić przy użyciu narzędzi deweloperskich F12 w programie Internet Explorer 9. W programie Internet Explorer 9 naciśnij klawisz F12 , aby otworzyć narzędzia. Kliknij kartę Sieć i naciśnij przycisk Rozpocznij przechwytywanie. Teraz wróć do strony internetowej i naciśnij klawisz F5 , aby ponownie załadować stronę internetową. Program Internet Explorer przechwytuje ruch HTTP między przeglądarką a serwerem sieci Web. Widok podsumowania przedstawia cały ruch sieciowy dla strony:

Znajdź wpis względnego identyfikatora URI "api/products/". Wybierz ten wpis i kliknij pozycję Przejdź do widoku szczegółowego. W widoku szczegółów znajdują się karty do wyświetlania nagłówków i treści żądania i odpowiedzi. Jeśli na przykład klikniesz kartę Nagłówki żądania, zobaczysz, że klient zażądał "application/json" w nagłówku Accept.

Jeśli klikniesz kartę Treść odpowiedzi, zobaczysz, jak lista produktów została serializowana w formacie JSON. Inne przeglądarki mają podobne funkcje. Innym przydatnym narzędziem jest Fiddler, serwer proxy debugowania internetowego. Za pomocą programu Fiddler można wyświetlać ruch HTTP, a także tworzyć żądania HTTP, co zapewnia pełną kontrolę nad nagłówkami HTTP w żądaniu.

Zobacz tę aplikację działającą na platformie Azure

Czy chcesz zobaczyć zakończoną witrynę uruchomioną jako aplikacja internetowa na żywo? Możesz wdrożyć pełną wersję aplikacji na koncie platformy Azure.

Do wdrożenia tego rozwiązania na platformie Azure potrzebne jest konto platformy Azure. Jeśli nie masz jeszcze konta, masz następujące opcje:

• Otwórz bezpłatne konto platformy Azure — możesz uzyskać środki, których możesz użyć do wypróbowania płatnych usług platformy Azure, a nawet po ich użyciu możesz zachować konto i korzystać z bezpłatnych usług platformy Azure.
• Aktywowanie korzyści dla subskrybentów MSDN — subskrypcja MSDN zapewnia środki na korzystanie co miesiąc z płatnych usług platformy Azure.

Dalsze kroki

• Aby uzyskać bardziej kompletny przykład usługi HTTP obsługującej akcje POST, PUT i DELETE oraz zapisy w bazie danych, zobacz Using Web API 2 with Entity Framework 6 (Używanie internetowego interfejsu API 2 z programem Entity Framework 6).
• Aby uzyskać więcej informacji na temat tworzenia płynnych i dynamicznych aplikacji internetowych w oparciu o usługę HTTP, zobacz ASP.NET aplikacja jednostronicowa.
• Aby uzyskać informacje na temat wdrażania projektu internetowego programu Visual Studio w usłudze Azure App Service, zobacz Tworzenie ASP.NET aplikacji internetowej w usłudze Azure App Service.