Wprowadzenie do usługi ASP.NET Web API 2 (C#)Get Started with ASP.NET Web API 2 (C#)

według Jan Wassonby Mike Wasson

Pobierz ukończony projektDownload Completed Project

W tym samouczku użyjesz internetowego interfejsu API platformy ASP.NET do tworzenia internetowego interfejsu API, który zwraca listę produktów.In this tutorial, you will use ASP.NET Web API to create a web API that returns a list of products.

Protokół HTTP nie jest używany tylko do obsługi stron internetowych.HTTP is not just for serving up web pages. Protokół HTTP to również zaawansowana platforma do tworzenia interfejsów API, które udostępniają dane i usługi.HTTP is also a powerful platform for building APIs that expose services and data. Protokół HTTP jest prosty, elastyczny i uniwersalny.HTTP is simple, flexible, and ubiquitous. Prawie każda platforma obsługuje bibliotekę HTTP, więc usługi HTTP mogą być stosowane dla szerokiej gamy klientów takich jak przeglądarki, urządzenia przenośne czy tradycyjne aplikacje komputerowe.Almost any platform that you can think of has an HTTP library, so HTTP services can reach a broad range of clients, including browsers, mobile devices, and traditional desktop applications.

Internetowy interfejs API platformy ASP.NET to architektura służąca do tworzenia internetowych interfejsów API w programie .NET Framework.ASP.NET Web API is a framework for building web APIs on top of the .NET Framework.

Wersje oprogramowania używane w samouczkuSoftware versions used in the tutorial

Aby uzyskać nowszą wersję tego samouczka , zobacz Tworzenie internetowego interfejsu API za pomocą ASP.NET Core i programu Visual Studio dla systemu Windows .See Create a web API with ASP.NET Core and Visual Studio for Windows for a newer version of this tutorial.

Tworzenie projektu interfejsu API sieci WebCreate a Web API Project

W tym samouczku użyjesz internetowego interfejsu API platformy ASP.NET do tworzenia internetowego interfejsu API, który zwraca listę produktów.In this tutorial, you will use ASP.NET Web API to create a web API that returns a list of products. Strona sieci Web frontonu używa technologii jQuery do wyświetlania wyników.The front-end web page uses jQuery to display the results.

Uruchom program Visual Studio i wybierz pozycję Nowy projekt na stronie startowej .Start Visual Studio and select New Project from the Start page. Lub w menu plik wybierz polecenie Nowy , a następnie pozycję projekt.Or, from the File menu, select New and then Project.

W okienku Szablony wybierz pozycję zainstalowane szablony i rozwiń węzeł Wizualizacja C# .In the Templates pane, select Installed Templates and expand the Visual C# node. W obszarze C#Wizualizacja wybierz pozycję Sieć Web.Under Visual C#, select Web. Na liście szablonów projektu wybierz pozycję aplikacja sieci Web ASP.NET.In the list of project templates, select ASP.NET Web Application. Nadaj projektowi nazwę "ProductsApp" i kliknij przycisk OK.Name the project "ProductsApp" and click OK.

W oknie dialogowym Nowy projekt ASP.NET wybierz pusty szablon.In the New ASP.NET Project dialog, select the Empty template. W obszarze "Dodaj foldery i podstawowe odwołania dla"Sprawdź, czy jest internetowy interfejs API.Under "Add folders and core references for", check Web API. Kliknij przycisk OK.Click OK.

Note

Projekt interfejsu API sieci Web można również utworzyć przy użyciu szablonu" "Web API.You can also create a Web API project using the "Web API" template. Szablon internetowego interfejsu API używa platformy ASP.NET MVC do udostępniania stron pomocy do interfejsu API.The Web API template uses ASP.NET MVC to provide API help pages. Używam pustego szablonu na potrzeby tego samouczka, ponieważ chcę pokazać internetowy interfejs API bez platformy MVC.I'm using the Empty template for this tutorial because I want to show Web API without MVC. Ogólnie rzecz biorąc, nie trzeba znać platformy ASP.NET MVC, aby korzystać z internetowego interfejsu API.In general, you don't need to know ASP.NET MVC to use Web API.

Dodawanie modeluAdding a Model

Model to obiekt, który reprezentuje dane w aplikacji.A model is an object that represents the data in your application. Internetowy interfejs API platformy ASP.NET może automatycznie zserializować model do formatu JSON, XML lub innego, a następnie wpisać te dane serializowane w treści komunikatu odpowiedzi HTTP.ASP.NET Web API can automatically serialize your model to JSON, XML, or some other format, and then write the serialized data into the body of the HTTP response message. Jeśli klient może odczytać format serializacji, może również wykonywać deserializację obiektu.As long as a client can read the serialization format, it can deserialize the object. Większość klientów może analizować albo format XML, albo JSON.Most clients can parse either XML or JSON. Ponadto klient może wskazać pożądany format, ustawiając nagłówek Accept w komunikacie żądania HTTP.Moreover, the client can indicate which format it wants by setting the Accept header in the HTTP request message.

Zacznijmy od utworzenia prostego modelu reprezentującego produkt.Let's start by creating a simple model that represents a product.

Jeśli Eksplorator rozwiązań nie jest jeszcze widoczna, kliknij menu Widok i wybierz pozycję Eksplorator rozwiązań.If Solution Explorer is not already visible, click the View menu and select Solution Explorer. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy folder Modele.In Solution Explorer, right-click the Models folder. Z menu kontekstowego wybierz pozycję Dodaj , a następnie wybierz pozycję Klasa.From the context menu, select Add then select Class.

Nazwij klasę ""produktu.Name the class "Product". Dodaj następujące właściwości do klasy Product.Add the following properties to the Product class.

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 kontroleraAdding a Controller

W interfejsie API sieci Web kontroler jest obiektem, który obsługuje żądania HTTP.In Web API, a controller is an object that handles HTTP requests. Dodamy kontroler, który może zwrócić listę produktów lub pojedynczy produkt określony przez identyfikator.We'll add a controller that can return either a list of products or a single product specified by ID.

Note

Jeśli używasz platformy ASP.NET MVC, znasz już kontrolery.If you have used ASP.NET MVC, you are already familiar with controllers. Kontrolery internetowego interfejsu API są podobne do kontrolerów MVC, ale dziedziczą klasę ApiController zamiast klasy Controller .Web API controllers are similar to MVC controllers, but inherit the ApiController class instead of the Controller class.

W Eksplorator rozwiązańkliknij prawym przyciskiem myszy folder controllers.In Solution Explorer, right-click the Controllers folder. Wybierz pozycję Dodaj , a następnie wybierz pozycję kontroler.Select Add and then select Controller.

W oknie dialogowym Dodawanie szkieletu wybierz pozycję kontroler interfejsu API sieci Web — puste.In the Add Scaffold dialog, select Web API Controller - Empty. Kliknij pozycję Add (Dodaj).Click Add.

W oknie dialogowym Dodawanie kontrolera nazwij kontroler "ProductsController".In the Add Controller dialog, name the controller "ProductsController". Kliknij pozycję Add (Dodaj).Click Add.

Funkcja tworzenia szkieletów utworzy plik o nazwie ProductsController.cs w folderze kontrolerów.The scaffolding creates a file named ProductsController.cs in the Controllers folder.

Note

Kontroler nie musi być umieszczany w folderze kontrolerów (Controllers).You don't need to put your controllers into a folder named Controllers. Nazwy folderów ułatwiają tylko organizowanie plików źródłowych.The folder name is just a convenient way to organize your source files.

Jeśli ten plik nie jest jeszcze otwarty, kliknij dwukrotnie, aby go otworzyć.If this file is not open already, double-click the file to open it. Zastąp kod w tym pliku zgodnie z poniższym przykładem:Replace the code in this file with the following:

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

W tym przykładzie w celu uproszczenia produkty są przechowywane w stałej tablicy wewnątrz klasy kontrolera.To keep the example simple, products are stored in a fixed array inside the controller class. Oczywiście w rzeczywistej aplikacji przesyłane jest zapytanie do bazy danych lub innego zewnętrznego źródła danych.Of course, in a real application, you would query a database or use some other external data source.

Kontroler definiuje dwie metody, które zwracają produkty:The controller defines two methods that return products:

  • Metoda GetAllProducts zwraca całą listę produktów jako typ >produktu IEnumerable< .The GetAllProducts method returns the entire list of products as an IEnumerable<Product> type.
  • Metoda GetProduct wyszukuje pojedynczy produkt według jego identyfikatora.The GetProduct method looks up a single product by its ID.

Gotowe.That's it! Masz działający internetowy interfejs API.You have a working web API. Każda metoda na kontrolerze odnosi się do co najmniej jednego identyfikatora URI:Each method on the controller corresponds to one or more URIs:

Controller — MetodaController Method Identyfikator URIURI
GetAllProductsGetAllProducts /api/products/api/products
GetproductGetProduct Identyfikator /API/Products//api/products/id

Dla metody GetProduct Identyfikator identyfikatora URI jest symbolem zastępczym.For the GetProduct method, the id in the URI is a placeholder. Na przykład aby uzyskać produkt o IDENTYFIKATORze 5, identyfikator URI jest api/products/5.For example, to get the product with ID of 5, the URI is api/products/5.

Aby uzyskać więcej informacji o sposobie, w jaki interfejs API sieci Web kieruje żądania HTTP do metod kontrolera, zobacz Routing in Web api ASP.NET.For more information about how Web API routes HTTP requests to controller methods, see Routing in ASP.NET Web API.

Wywoływanie interfejsu API sieci Web przy użyciu języków JavaScript i jQueryCalling the Web API with Javascript and jQuery

W tej sekcji dodamy stronę HTML używającą technologii AJAX do wywołania internetowego interfejsu API.In this section, we'll add an HTML page that uses AJAX to call the web API. Użyjemy technologii jQuery do wykonania wywołań AJAX oraz do zaktualizowania wyników na stronie.We'll use jQuery to make the AJAX calls and also to update the page with the results.

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt, a następnie wybierz pozycję Dodaj, a następnie wybierz pozycję nowy element.In Solution Explorer, right-click the project and select Add, then select New Item.

W oknie dialogowym Dodaj nowy element wybierz węzeł sieci Web w obszarze Wizualizacja C# , a następnie wybierz element strony HTML .In the Add New Item dialog, select the Web node under Visual C#, and then select the HTML Page item. Nazwij stronę "index. html".Name the page "index.html".

Zamień zawartość pliku na następującą:Replace everything in this file with the following:

<!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 uzyskania biblioteki jQuery.There are several ways to get jQuery. W tym przykładzie użyto usługi Microsoft Ajax CDN.In this example, I used the Microsoft Ajax CDN. Można go również pobrać z http://jquery.com/, a szablon projektu "Web API" ASP.NET "również obejmuje jQuery.You can also download it from http://jquery.com/, and the ASP.NET "Web API" project template includes jQuery as well.

Pobieranie listy produktówGetting a List of Products

Aby uzyskać listę produktów, Wyślij żądanie HTTP GET w celu ""/API/Products.To get a list of products, send an HTTP GET request to "/api/products".

Funkcja jQuery getJSON wysyła żądanie AJAX.The jQuery getJSON function sends an AJAX request. Odpowiedź zawiera tablicę obiektów JSON.The response contains array of JSON objects. Funkcja done określa wywołanie zwrotne, które jest wywoływane, jeśli żądanie zakończy się pomyślnie.The done function specifies a callback that is called if the request succeeds. W wywołaniu zwrotnym aktualizujemy model DOM informacjami o produkcie.In the callback, we update the DOM with the product information.

$(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 identyfikatoraGetting a Product By ID

Aby uzyskać produkt według identyfikatora, Wyślij żądanie HTTP GET do "Identyfikator /API/Products/", gdzie ID jest identyfikatorem produktu.To get a product by ID, send an HTTP GET request to "/api/products/id", where id is the product ID.

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 dzwonimy do getJSON, aby wysłać żądanie AJAX, ale ten czas jest umieszczany w IDENTYFIKATORze URI żądania.We still call getJSON to send the AJAX request, but this time we put the ID in the request URI. Odpowiedź na to żądanie jest reprezentacją JSON jednego produktu.The response from this request is a JSON representation of a single product.

Uruchamianie aplikacjiRunning the Application

Naciśnij klawisz F5, aby rozpocząć debugowanie aplikacji.Press F5 to start debugging the application. Strona internetowa powinna wyglądać następująco:The web page should look like the following:

Aby uzyskać produkt według identyfikatora, wprowadź identyfikator i kliknij przycisk Wyszukaj:To get a product by ID, enter the ID and click Search:

W przypadku wprowadzenia nieprawidłowego identyfikatora serwer zwróci błąd HTTP:If you enter an invalid ID, the server returns an HTTP error:

Używanie klawisza F12 do wyświetlania żądania i odpowiedzi HTTPUsing F12 to View the HTTP Request and Response

Podczas pracy z usługą HTTP może być bardzo przydatne, aby wyświetlić żądania HTTP i komunikaty odpowiedzi.When you are working with an HTTP service, it can be very useful to see the HTTP request and response messages. Można to zrobić w programie Internet Explorer 9 przy użyciu narzędzi deweloperskich uruchamianych za pomocą klawisza F12.You can do this by using the F12 developer tools in Internet Explorer 9. W programie Internet Explorer 9 Naciśnij klawisz F12 , aby otworzyć narzędzia.From Internet Explorer 9, press F12 to open the tools. Kliknij kartę Sieć , a następnie naciśnij pozycję Rozpocznij przechwytywanie.Click the Network tab and press Start Capturing. Teraz wróć do strony sieci Web, a następnie naciśnij klawisz F5 , aby ponownie załadować stronę sieci Web.Now go back to the web page and press F5 to reload the web page. Program Internet Explorer będzie przechwytywać ruch HTTP między przeglądarką a serwerem internetowym.Internet Explorer will capture the HTTP traffic between the browser and the web server. Widok podsumowania pokazuje cały ruch sieciowy dla strony:The summary view shows all the network traffic for a page:

Zlokalizuj wpis dla względnego identyfikatora URI "api/products//".Locate the entry for the relative URI "api/products/". Wybierz ten wpis, a następnie kliknij pozycję Przejdź do widoku szczegółowego.Select this entry and click Go to detailed view. Widok szczegółowy zawiera karty, na których są wyświetlane nagłówki i zawartość żądań oraz odpowiedzi.In the detail view, there are tabs to view the request and response headers and bodies. Na przykład po kliknięciu karty nagłówki żądań można zobaczyć, że klient zażądał "Application/JSON" w nagłówku Accept.For example, if you click the Request headers tab, you can see that the client requested "application/json" in the Accept header.

Po kliknięciu karty Treść odpowiedzi możesz zobaczyć, jak lista produktów została zserializowana do formatu JSON.If you click the Response body tab, you can see how the product list was serialized to JSON. Inne przeglądarki mają podobną funkcję.Other browsers have similar functionality. Innym przydatnym narzędziem jest programu Fiddler, serwer proxy debugowania sieci Web.Another useful tool is Fiddler, a web debugging proxy. Służy on do wyświetlania ruchu HTTP, a także do tworzenia żądań HTTP, co daje pełną kontrolę nad nagłówkami HTTP w żądaniu.You can use Fiddler to view your HTTP traffic, and also to compose HTTP requests, which gives you full control over the HTTP headers in the request.

Wyświetlanie aplikacji działającej na platformie AzureSee this App Running on Azure

Czy chcesz zobaczyć gotową witrynę działającą jako aplikacja internetowa na żywo?Would you like to see the finished site running as a live web app? Pełną wersję aplikacji możesz wdrożyć na koncie platformy Azure — wystarczy kliknąć poniższy przycisk.You can deploy a complete version of the app to your Azure account by simply clicking the following button.

Aby wdrożyć to rozwiązanie na platformie Azure, musisz mieć konto platformy Azure.You need an Azure account to deploy this solution to Azure. Jeśli nie masz jeszcze konta, możesz:If you do not already have an account, you have the following options:

Następne krokiNext Steps