Začínáme s webovým rozhraním API 2 ASP.NET (C#)

Mike Wasson

Stáhnout dokončený projekt

V tomto kurzu použijete ASP.NET webové rozhraní API k vytvoření webového rozhraní API, které vrátí seznam produktů.

HTTP není jen pro obsluhu webových stránek. HTTP je také výkonná platforma pro vytváření rozhraní API, která zpřístupňují služby a data. HTTP je jednoduché, flexibilní a všudypřítomné. Téměř každá platforma, kterou si můžete představit, má knihovnu HTTP, takže služby HTTP mohou dosáhnout široké škály klientů, včetně prohlížečů, mobilních zařízení a tradičních desktopových aplikací.

ASP.NET webové rozhraní API je architektura pro vytváření webových rozhraní API nad rozhraním .NET Framework.

Verze softwaru používané v tomto kurzu

• Visual Studio 2017
• Webové rozhraní API 2

Viz Vytvoření webového rozhraní API s ASP.NET Core a sadou Visual Studio pro Windows pro novější verzi tohoto kurzu.

Vytvoření projektu webového rozhraní API

V tomto kurzu použijete ASP.NET webové rozhraní API k vytvoření webového rozhraní API, které vrátí seznam produktů. Front-endová webová stránka k zobrazení výsledků používá jQuery.

Spusťte Visual Studio a na úvodní stránce vyberte Nový projekt. Nebo v nabídce Soubor vyberte Nový a pak Project.

V podokně Šablony vyberte Nainstalované šablony a rozbalte uzel Visual C# . V části Visual C# vyberte Web. V seznamu šablon projektů vyberte ASP.NET webovou aplikaci. Pojmenujte projekt ProductsApp a klikněte na OK.

V dialogovém okně Nový ASP.NET Projekt vyberte prázdnou šablonu. V části Přidat složky a základní reference zkontrolujte Web API. Klikněte na OK.

Poznámka:

Projekt webového rozhraní API můžete vytvořit také pomocí šablony Webové rozhraní API. Šablona webového rozhraní API používá k poskytování stránek nápovědy k rozhraní API ASP.NET MVC. Pro účely tohoto kurzu používám prázdnou šablonu, protože chci zobrazit webové rozhraní API bez MVC. Obecně nemusíte znát ASP.NET MVC, aby bylo možné používat webové rozhraní API.

Přidání modelu

Model je objekt, který představuje data ve vaší aplikaci. ASP.NET webové rozhraní API může automaticky serializovat model do formátu JSON, XML nebo jiného formátu a pak zapsat serializovaná data do textu zprávy odpovědi HTTP. Pokud klient může číst formát serializace, může deserializovat objekt. Většina klientů může analyzovat XML nebo JSON. Klient navíc může označit požadovaný formát nastavením hlavičky Accept ve zprávě požadavku HTTP.

Začněme vytvořením jednoduchého modelu, který představuje produkt.

Pokud průzkumník řešení ještě není viditelný, klikněte na nabídku Zobrazení a vyberte Průzkumníka řešení. V Průzkumníku řešení klikněte pravým tlačítkem myši na složku Modely. V místní nabídce vyberte Přidat a pak vyberte Třídu.

Pojmenujte třídu Product. Do třídy přidejte následující vlastnosti 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; }
    }
}

Přidání kontroleru

Ve webovém rozhraní API je kontroler objekt, který zpracovává požadavky HTTP. Přidáme řadič, který může vrátit buď seznam produktů, nebo jeden produkt určený podle ID.

Poznámka:

Pokud jste použili ASP.NET MVC, už znáte kontrolery. Řadiče webového rozhraní API jsou podobné kontroleru MVC, ale dědí třídu ApiController místo třídy Controller .

V Průzkumníku řešení klikněte pravým tlačítkem myši na složku Kontrolery. Vyberte Přidat a pak vyberte Kontroler.

V dialogovém okně Přidat generátor vyberte Řadič webového rozhraní API – prázdný. Klikněte na tlačítko Přidat.

V dialogovém okně Přidat kontroler pojmenujte kontroler ProductsController. Klikněte na tlačítko Přidat.

Scaffolding vytvoří soubor s názvem ProductsController.cs ve složce Kontrolery.

Poznámka:

Řadiče nemusíte zadávat do složky s názvem Kontrolery. Název složky je jen pohodlný způsob, jak uspořádat zdrojové soubory.

Pokud tento soubor ještě není otevřený, otevřete ho poklikáním. Nahraďte kód v tomto souboru následujícím kódem:

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 byl příklad jednoduchý, produkty jsou uloženy v pevném poli uvnitř třídy kontroleru. Samozřejmě, v reálné aplikaci byste dotazovali databázi nebo použili jiný externí zdroj dat.

Kontroler definuje dvě metody, které vracejí produkty:

• Metoda GetAllProducts vrátí celý seznam produktů jako typ IEnumerable<Product> .
• Metoda GetProduct vyhledá jeden produkt podle jeho ID.

A je to! Máte funkční webové rozhraní API. Každá metoda na kontroleru odpovídá jedné nebo více identifikátorům URI:

Metoda kontroleru	identifikátor URI
GetAllProducts	/api/products
ZískatProdukt	/api/products/id

Pro metodu GetProduct je ID v identifikátoru URI zástupný symbol. Pokud například chcete získat produkt s ID 5, identifikátor URI je api/products/5.

Další informace o tom, jak webové rozhraní API směruje požadavky HTTP na metody kontroleru, naleznete v tématu Směrování v ASP.NET webové rozhraní API.

Volání webového rozhraní API pomocí JavaScriptu a jQuery

V této části přidáme stránku HTML, která používá AJAX k volání webového rozhraní API. Pomocí jQuery provedeme volání AJAX a také aktualizujeme stránku s výsledky.

V Průzkumníku řešení klikněte pravým tlačítkem myši na projekt a vyberte Přidat a pak vyberte Nová položka.

V dialogovém okně Přidat novou položku vyberte uzel Web v části Visual C# a pak vyberte položku HTML stránka. Pojmenujte stránku "index.html".

Všechny položky v tomto souboru nahraďte následujícím kódem:

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

Existuje několik způsobů, jak získat jQuery. V tomto příkladu jsem použil(a) microsoft Ajax CDN. Můžete si ho také stáhnout z http://jquery.com/a šablona projektu ASP.NET "Webové rozhraní API" obsahuje také jQuery.

Získání seznamu produktů

Pokud chcete získat seznam produktů, odešlete požadavek HTTP GET na /api/products.

Funkce jQuery getJSON odešle požadavek AJAX. Odpověď obsahuje pole objektů JSON. Funkce done určuje zpětné volání, které se volá, pokud požadavek proběhne úspěšně. V zpětném volání aktualizujeme DOM informacemi o produktu.

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

Získání produktu podle ID

Pokud chcete získat produkt podle ID, odešlete požadavek HTTP GET na /api/products/id, kde ID je 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);
        });
}

Stále voláme getJSON k odeslání požadavku AJAX, ale tentokrát vložíme ID do identifikátoru URI požadavku. Odpověď z tohoto požadavku je reprezentace jednoho produktu ve formátu JSON.

Spuštění aplikace

Stisknutím klávesy F5 spusťte ladění aplikace. Webová stránka by měla vypadat takto:

Pokud chcete získat produkt podle ID, zadejte ID a klikněte na Hledat:

Pokud zadáte neplatné ID, server vrátí chybu HTTP:

Zobrazení požadavku HTTP a odpovědi pomocí klávesy F12

Při práci se službou HTTP může být velmi užitečné zobrazit zprávy požadavku HTTP a odpovědi. Můžete to udělat pomocí vývojářských nástrojů F12 v Internet Exploreru 9. Z Internet Exploreru 9 otevřete nástroje stisknutím klávesy F12 . Klikněte na kartu Síť a stiskněte spustit zachytávání. Teď se vraťte na webovou stránku a stisknutím klávesy F5 webovou stránku znovu načtěte. Internet Explorer zachytí provoz HTTP mezi prohlížečem a webovým serverem. Souhrnné zobrazení zobrazuje veškerý síťový provoz stránky:

Vyhledejte záznam pro relativní URI "api/products/". Vyberte tuto položku a klikněte na Přejít k podrobnému zobrazení. V zobrazení podrobností jsou karty pro zobrazení hlaviček a těl požadavků a odpovědí. Pokud například kliknete na kartu Záhlaví požadavku, uvidíte, že klient v hlavičce Accept požadoval "application/json".

Pokud kliknete na kartu Text odpovědi, uvidíte, jak byl seznam produktů serializován do formátu JSON. Jiné prohlížeče mají podobné funkce. Dalším užitečným nástrojem je Fiddler, proxy pro ladění webu. Fiddler můžete použít k zobrazení provozu HTTP a také k vytváření požadavků HTTP, které vám umožní úplnou kontrolu nad hlavičkami HTTP v požadavku.

Zobrazit tuto aplikaci spuštěnou v Azure

Chcete vidět dokončený web spuštěný jako živou webovou aplikaci? Úplnou verzi aplikace můžete nasadit do svého účtu Azure.

K nasazení tohoto řešení do Azure potřebujete účet Azure. Pokud ještě účet nemáte, máte následující možnosti:

• Otevřete bezplatný účet Azure – získáte kredity, které můžete použít k vyzkoušení placených služeb Azure, a dokonce i po jejich využití můžete účet zachovat a používat bezplatné služby Azure.
• Aktivace výhod předplatitele MSDN – Předplatné MSDN vám každý měsíc poskytuje kredity, které můžete použít pro placené služby Azure.

Další kroky

• Podrobnější příklad služby HTTP, která podporuje akce POST, PUT a DELETE a zápisy do databáze, najdete v tématu Použití webového rozhraní API 2 s Entity Framework 6.
• Další informace o vytváření proměnlivých a responzivních webových aplikací nad službou HTTP najdete v tématu ASP.NET jednostráková aplikace.
• Informace o nasazení webového projektu sady Visual Studio do služby Azure App Service najdete v tématu Vytvoření webové aplikace ASP.NET ve službě Azure App Service.