Condividi tramite

Introduzione a API Web ASP.NET 2 (C#)

  • Articolo

di Mike Wasson

Scaricare il progetto completato

In questa esercitazione si userà API Web ASP.NET per creare un'API Web che restituisca un elenco di prodotti.

HTTP non è solo per gestire le pagine Web. HTTP è anche una piattaforma potente per la creazione di API che espongono servizi e dati. HTTP è semplice, flessibile e onnipresente. Quasi tutte le piattaforme che si possono pensare hanno una libreria HTTP, in modo che i servizi HTTP possano raggiungere un'ampia gamma di client, inclusi browser, dispositivi mobili e applicazioni desktop tradizionali.

API Web ASP.NET è un framework per la creazione di API Web in .NET Framework.

Versioni software usate nell'esercitazione

Per una versione più recente di questa esercitazione, vedere Creare un'API Web con ASP.NET Core e Visual Studio per Windows.

Creare un progetto API Web

In questa esercitazione si userà API Web ASP.NET per creare un'API Web che restituisca un elenco di prodotti. La pagina Web front-end usa jQuery per visualizzare i risultati.

Screenshot della finestra del browser host locale, che mostra il progetto di esempio con un elenco di prodotti, i relativi prezzi e una ricerca in base al campo e al pulsante ID.

Avviare Visual Studio e selezionare Nuovo progetto nella pagina Iniziale . In alternativa, scegliere Nuovo dal menu File e quindi Progetto.

Nel riquadro Modelli selezionare Modelli installati ed espandere il nodo Visual C# . In Visual C# selezionare Web. Nell'elenco dei modelli di progetto selezionare ASP.NET'applicazione Web. Assegnare al progetto il nome "ProductsApp" e fare clic su OK.

Screenshot delle opzioni del modello

Nella finestra di dialogo Nuovo progetto ASP.NET selezionare il modello Vuoto . In "Aggiungi cartelle e riferimenti di base per" selezionare l'API Web. Fare clic su OK.

Screenshot della finestra di dialogo nuovo progetto, con opzioni di modello diverse e tre selezioni per cartelle e riferimenti principali.

Nota

È anche possibile creare un progetto API Web usando il modello "API Web". Il modello api Web usa ASP.NET MVC per fornire pagine della Guida dell'API. Si usa il modello Vuoto per questa esercitazione perché si vuole visualizzare l'API Web senza MVC. In generale, non è necessario conoscere ASP.NET MVC per usare l'API Web.

Aggiunta di un modello

Un modello è un oggetto che rappresenta i dati nell'applicazione. API Web ASP.NET possibile serializzare automaticamente il modello in JSON, XML o in un altro formato e quindi scrivere i dati serializzati nel corpo del messaggio di risposta HTTP. Purché un client possa leggere il formato di serializzazione, può deserializzare l'oggetto. La maggior parte dei client può analizzare XML o JSON. Inoltre, il client può indicare il formato desiderato impostando l'intestazione Accept nel messaggio di richiesta HTTP.

Si inizierà creando un modello semplice che rappresenta un prodotto.

Se Esplora soluzioni non è ancora visibile, fare clic sul menu Visualizza e quindi selezionare Esplora soluzioni. In Esplora soluzioni fare clic con il pulsante destro del mouse sulla cartella Modelli. Nel menu di scelta rapida selezionare Aggiungi e quindi selezionare Classe.

Screenshot del menu Esplora soluzioni, che mostra le opzioni disponibili nella cartella models che mostra come aggiungere una classe.

Assegnare alla classe il nome "Product". Aggiungere le proprietà seguenti alla Product classe .

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

Aggiunta di un controller

Nell'API Web un controller è un oggetto che gestisce richieste HTTP. Verrà aggiunto un controller che può restituire un elenco di prodotti o un singolo prodotto specificato dall'ID.

Nota

Se è stato usato ASP.NET MVC, si ha già familiarità con i controller. I controller API Web sono simili ai controller MVC, ma ereditano la classe ApiController anziché la classe Controller .

In Esplora soluzioni fare clic sulla cartella Controller. Selezionare Aggiungi e quindi selezionare Controller.

Screenshot del menu Esplora soluzioni, che mostra indicazioni visive per l'aggiunta di una classe controller al progetto.

Nella finestra di dialogo Aggiungi scaffolding selezionare Controller Web API 2 - Vuoto. Scegliere Aggiungi.

Screenshot che mostra le opzioni di menu della finestra di dialogo aggiungi scaffolding, evidenziando l'opzione Web A P I Controller - vuota.

Nella finestra di dialogo Aggiungi controller assegnare al controller il nome "ProductsController". Scegliere Aggiungi.

Screenshot della finestra di dialogo

Lo scaffolding crea un file denominato ProductsController.cs nella cartella Controllers.

Screenshot delle opzioni di menu esplora soluzioni, che circonda l'opzione appena creata denominata 'products controller dot C S nella cartella controllers.

Nota

Non è necessario inserire i controller in una cartella denominata Controllers. Il nome della cartella è solo un modo pratico per organizzare i file di origine.

Se non è già aperto, fare doppio clic sul file per aprirlo. Sostituire il codice in questo file con quanto segue:

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

Per semplificare l'esempio, i prodotti vengono archiviati in una matrice fissa all'interno della classe controller. Naturalmente, in un'applicazione reale, è possibile eseguire query su un database o usare un'altra origine dati esterna.

Il controller definisce due metodi che restituiscono prodotti:

  • Il GetAllProducts metodo restituisce l'intero elenco di prodotti come tipo di prodotto> IEnumerable<.
  • Il GetProduct metodo cerca un singolo prodotto in base al relativo ID.

L'operazione è terminata. Si dispone di un'API Web funzionante. Ogni metodo nel controller corrisponde a uno o più URI:

Metodo controller URI
GetAllProducts /api/products
GetProduct /api/products/id

Per il GetProduct metodo , l'ID nell'URI è un segnaposto. Ad esempio, per ottenere il prodotto con ID 5, l'URI è api/products/5.

Per altre informazioni sul modo in cui l'API Web instrada le richieste HTTP ai metodi del controller, vedere Routing in API Web ASP.NET.

Chiamata all'API Web con Javascript e jQuery

In questa sezione verrà aggiunta una pagina HTML che usa AJAX per chiamare l'API Web. Si userà jQuery per effettuare le chiamate AJAX e anche per aggiornare la pagina con i risultati.

In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Aggiungi, quindi selezionare Nuovo elemento.

Screenshot del menu Esplora soluzioni, evidenziando l'opzione products app per visualizzare le selezioni di menu per aggiungere un nuovo elemento.

Nella finestra di dialogo Aggiungi nuovo elemento selezionare il nodo Web in Visual C# e quindi selezionare l'elemento Pagina HTML . Denominare la pagina "index.html".

Screenshot delle opzioni di menu

Sostituire tutti gli elementi in questo file con quanto segue:

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

È possibile ottenere jQuery in vari modi. In questo esempio è stata usata la rete CDN Microsoft Ajax. È anche possibile scaricarlo da http://jquery.com/e il modello di progetto "API Web" ASP.NET include anche jQuery.

Ottenere un elenco di prodotti

Per ottenere un elenco di prodotti, inviare una richiesta HTTP GET a "/api/products".

La funzione getJSON di jQuery invia una richiesta AJAX. La risposta contiene una matrice di oggetti JSON. La done funzione specifica un callback che viene chiamato se la richiesta ha esito positivo. Nel callback aggiorniamo il DOM con le informazioni sul prodotto.

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

Recupero di un prodotto in base all'ID

Per ottenere un prodotto in base all'ID, inviare una richiesta HTTP GET a "/api/products/id", dove ID è l'ID prodotto.

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

Viene comunque chiamato getJSON per inviare la richiesta AJAX, ma questa volta l'ID viene inserito nell'URI della richiesta. La risposta da questa richiesta è una rappresentazione JSON di un singolo prodotto.

Esecuzione dell'applicazione

Premere F5 per avviare il debug dell'applicazione. La pagina Web dovrebbe essere simile alla seguente:

Screenshot del Web browser, che mostra un modulo elenco tutti i prodotti, con i relativi prezzi, seguito dal campo 'search by I D' sotto di esso.

Per ottenere un prodotto in base all'ID, immettere l'ID e fare clic su Cerca:

Screenshot del browser, che mostra tutti i prodotti e i prezzi, in formato elenco, e il numero 2 nel campo 'cerca per ID'.

Se si immette un ID non valido, il server restituisce un errore HTTP:

Screenshot del browser, che elenca tutti i prodotti e i relativi prezzi e mostra il messaggio di errore 'not found' nel campo 'search by I D'.

Uso di F12 per visualizzare la richiesta e la risposta HTTP

Quando si usa un servizio HTTP, può essere molto utile visualizzare i messaggi di richiesta e risposta HTTP. A tale scopo, usare gli strumenti di sviluppo F12 in Internet Explorer 9. Da Internet Explorer 9 premere F12 per aprire gli strumenti. Fare clic sulla scheda Rete e premere Avvia acquisizione. Tornare alla pagina Web e premere F5 per ricaricare la pagina Web. Internet Explorer acquisisce il traffico HTTP tra il browser e il server Web. La visualizzazione di riepilogo mostra tutto il traffico di rete per una pagina:

Screenshot della finestra messaggio di richiesta e risposta H T T P, che mostra un elenco di U R Ls e tutte le risposte al traffico di rete.

Individuare la voce per l'URI relativo "api/products/". Selezionare questa voce e fare clic su Vai alla visualizzazione dettagliata. Nella visualizzazione dei dettagli sono disponibili schede per visualizzare le intestazioni e i corpi delle richieste e delle risposte. Ad esempio, se si fa clic sulla scheda Intestazioni richiesta , è possibile notare che il client ha richiesto "application/json" nell'intestazione Accept.

Screenshot della finestra di dialogo richiesta E messaggio di risposta H T T, che mostra un esempio di una singola risposta richiesta P.

Se si fa clic sulla scheda Corpo della risposta, è possibile vedere come l'elenco dei prodotti è stato serializzato in JSON. Altri browser hanno funzionalità simili. Un altro strumento utile è Fiddler, un proxy di debug Web. È possibile usare Fiddler per visualizzare il traffico HTTP e anche per comporre richieste HTTP, che offrono il controllo completo sulle intestazioni HTTP nella richiesta.

Vedere questa app in esecuzione in Azure

Si desidera visualizzare il sito completato in esecuzione come app Web attiva? È possibile distribuire una versione completa dell'app nell'account Azure.

Per distribuire questa soluzione in Azure è necessario un account Azure. Se non si dispone già di un account, sono disponibili le opzioni seguenti:

Passaggi successivi