ASP.NET Web API for Dummies

Dopo avere visto come utilizzare il formato JSON per scambiare dati tra la nostra applicazione e un servizio remoto, in questa nuova serie for dummies vedremo come creare un servizio remoto che possa servire dati alla nostra, o ad altre applicazioni.

Notiamo subito che basandosi i servizi REST, di questo stiamo parlando, sullo scambio di file di testo tramite semplici chiamate HTTP, la tecnologia che usiamo nella creazione del servizio remoto non è in nessun modo vincolata alla tecnologia usata nella creazione dell’app.

Utilizzeremo un progetto Web Api di ASP.NET MVC che potrà essere ospitato su un qualsiasi servizio web con IIS. Noi utilizzeremo Azure, il servizio cloud di Microsoft, che permette di creare gratuitamente fino a 10 siti web.

Da Visual Studio creiamo dunque un nuovo progetto web di tipo applicazione Web ASP.NET (Se avete VS 2013 questo è l’unico tipo di progetto web che potete creare, se invece avete Visual Studio 2012 dovrete scegliere un’applicazione MVC4).

Cattura di schermata (3)

Come modello scegliamo Web Api tra quelli disponibili.
Modifichiamo l’autenticazione impostando nessuna autenticazione.
Se avete un acount Azure possiamo gestire direttamente anche la connessione con il servizio cloud impostando la sottoscrizione su cui volete pubblicare il vostro sito web, ma questo lo vedremo in un’altra occasione. Per il momento deselezionate Host nel cloud

Cattura di schermata (2)

A questo punto il vostro servizio web è pronto. Se avviate il progetto con F5 il sito web verrà lanciato nel server IIS locale, pronto a rispondere alle chiamate remote. Il template MVC costruisce per voi tutto il sito web, compresa pagina di documentazione delle API.

image

Cliccando sulla barra in alto su API arriverete a questa pagina, in cui avete la documentazione della Web API creata di default dal template, che in seguito andremo a modificare. Come si vede, il template predispone due metodi GET, un metodo POST, uno PUT e un DELETE.

image

Per invocare il servizio potete scrivere l’indirizzo del server completato con l’indirizzo dell’API. Nel mio caso l’indirizzo della prima funzione GET è http://localhost:49039/api/Values che vi restituirà, indovinate? Un file JSON.

Il file restituito Values.json ha il seguente contenuto

[“value1″,”value2”]

Il codice che definisce le funzioni restituite dai metodi HTTP è racchiuso in una classe che eredita dalla classe ApiController. Nello specifico la classe è ValuesController, nel file ValuesController.cs nella cartella Controllers del progetto, e la funzione è

public IEnumerable<string> Get()
        {
            return new string[] { “value1”, “value2” };
        }

Come vedete la funzione restituisce un oggetto di tipo array di stringhe, che viene serializzato automaticamente in JSON e scritto nel file di uscita.

A questo punto vogliamo aggiungere un nuovo controller che chiameremo TestController. Clicchiamo con il tasto destro sulla cartella controller e scegliamo la voce
Aggiungi –> Controller

Scegliete Controller Web API con azioni di lettura/scrittura e date un nome al vostro controller. Il prefisso davanti alla parola Controller sarà il nome della vostra Web API (nel nostro caso Test. Aggiungiamo anche nella cartella Models  le classi che abbiamo già utilizzato nell’esempio di JSON for Dummies

public class MyStruct
    {
        public string Title { get; set; }
        public string Name { get; set; }
        public List<MyItem> List { get; set; }
    }

    public class MyItem
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Description { get; set; }
    }

A questo punto possiamo creare un nuovo oggetto di tipo MyStruct nel costruttore del Controller

public TestController()
        {
            Struct = new MyStruct()
            {
                Title = “test”,
                Name = “name”,
                List = new List<MyItem>()
                {
                    new MyItem(){Id = 0, Name=”name0″, Description= “description0”},
                    new MyItem(){Id = 1, Name=”name1″, Description= “description1”},
                    new MyItem(){Id = 2, Name=”name2″, Description= “description2”},
                }
            };
        }

e modificare il metodo Get() in modo che restituisca proprio il nostro oggetto Struct

public MyStruct Get()
        {
            return Struct;
        }

Lanciando il servizio web nella pagina di documentazione delle API è apparsa la nuova API Test con i suoi metodi

image

Cliccando sulla funzione GET api/Test da noi modificata vedrete la documentazione degli oggetti restituiti ed anche un esempio del file JSON ed XML generati dal servizio.

image

A questo punto possiamo commentare o cancellare le funzioni che non abbiamo implementato ed anche cancellare il controller di default ValuesController.cs.

L’ultimo tocco riguarda come migliorare la documentazione. Nella pagina che espone tutti i metodi delle Web API nel campo Descrizione è sempre riportato No Description Available. Per personalizzare la descrizione dobbiamo eseguire le seguenti operazioni:

1. Togliere il commento dalla riga

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath(“~/App_Data/XmlDocument.xml”)));

nel file Areas\HelpPage\App_Start\HelpPageConfig.cs 

2. Aggiungere il percorso del file XML App_Data/XmlDocument.xml  indicato in questa riga nelle proprietà del progetto web al tab Compila nell’opzione File di Documentazione XML.

image

3. Aggiungere commenti dentro il codice, sia nel controller che nelle classi, ad es.

        /// <summary>
        /// Descrizione funzione
        /// </summary>
        /// <returns>
        ///  output description
        /// </returns>
        public MyStruct Get()
       {
              …
       }

Basta scrivere /// e Visual Studio creerà la struttura per noi. Compilando e avviando il progetto anche la pagina di documentazione sarà completa.

In questo modo possiamo spostare parte della logica della nostra app in un servizio remoto e possiamo quindi aggiornare i contenuti della nostra app senza dover pubblicare una nuova versione.

E anche per oggi abbiamo terminato.

Annunci

Rispondi

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione / Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione / Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione / Modifica )

Google+ photo

Stai commentando usando il tuo account Google+. Chiudi sessione / Modifica )

Connessione a %s...