RESTful API con Swagger

Oggetto di questa nota sarà swagger, un set di strumenti e di specifiche Open Source che stanno diventando lo Standard de facto per quel che riguarda l’implementazione e la documentazione di un’API RESTful.

Per comprendere cosa swagger sia e quale utilità abbia nel processo di sviluppo di una API, esistono in rete molti articoli, tra i quali API con Swagger in 5 minuti, Swagger specification, e via dicendo.

Seguendo lo spirito del blog, invece, utilizzerò questo post per memorizzare una possibile serie di passi per introdurre l’utilizzo dello strumento in una Web API sviluppata con il framework ASP.NET Core.

A tal fine partiremo da uno dei progetti sviluppati a titolo di esempio nei post precedenti, e pubblicati su Azure.

Tra i possibili strumenti per l’integrazione di swagger nel nostro processo, ci serviremo di Swashbuckle.
In primo luogo, aggiungiamo al file project.json del nostro progetto, la dipendenza alla versione attuale di Swashbuckle.

...
"Swashbuckle": "6.0.0-beta901",
...

Quindi, configuriamo la nostra App affinché faccia uso dello strumento in questione, aggiungendo nel metodo ConfigureServices, le seguenti righe:

            // Inject an implementation of ISwaggerProvider with defaulted settings applied
            services.AddSwaggerGen();

            services.ConfigureSwaggerGen(options =>
            {
                options.SingleApiVersion(new Info
                {
                    Version = "v1",
                    Title = "BookStore API",
                    Description = "A sample API  for swagger usage demonstration",
                    TermsOfService = "None",
                    Contact = new Contact() { Name = "Maurizio Attanasi", Email = "", Url = "https://maurizioattanasi.blogspot.it/" },
                    License = new License() { Name = "Creative Commons Attribution 4.0", Url = "https://creativecommons.org/licenses/by/4.0/" }
                });

                //Determine base path for the application.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                //Set the comments path for the swagger json and ui.
                var xmlPath = Path.Combine(basePath, "BookApi.xml");
                // options.IncludeXmlComments(xmlPath);
            });        

Infine, nel metodo Configure, subito dopo aver avviato il pattern MVC, configuriamo l’uso sia di Swagger che della sua interfaccia utente:

            app.UseMvc();

            // Enable middleware to serve generated Swagger as a JSON endpoint
            app.UseSwagger();

            // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.)
            app.UseSwaggerUi();

Avviata la web application, e navigando all’indirizzo your-root-url/swagger/ui, nel nostro caso http://talking-things-api.azurewebsites.net/swagger/ui/, visualizzeremo la pagina di documentazione autogenerata

 Degno di nota è anche il fatto che la pagina fornisce anche un client che consente di testare il servizio senza ricorrere a tool esterni quali Postman o Fiddler. Espandendo infatti uno dei verbi visualizzati nella pagina, ed agendo sul pulsante Try it out, abbiamo

Enjoy.

Integrazione Continua su Azure con git e azure-cli (parte II)

Continuiamo la precedente nota su Integrazione Continua su Azure con git e azure-cli, nella quale ho illustrato una possibile procedura per l’implementazione di un ambiente di sviluppo per l’integrazione continua su Microsoft Azure. In quell’occasione il progetto pubblicato implementava sia la gestione del front-end (sviluppato in quell’occasione con un’applicazione Angular 2), che il back-end (implementato con ASP.NET Core) implementata su host IIS.

In questo post concentreremo la nostra attenzione solo sulla pubblicazione di una Web App Angular 2 implementata con Node.js. A tal fine ci avvarremo di angular-cli, un set di strumenti in linea di comando per lo sviluppo di un'app Angular 2.

Creazione della Web App

Seguendo le istruzioni riportate dal sito creiamo una Web App Angular 2 con angular-cli.

1. In primo luogo installiamo sul nostro sistema angular-cli:

$ npm install -g angular-cli

2. Quindi creiamo la nostra Web App:

$ ng new my-a2-app

3. Personalizziamone il contenuto, modificando:
   
   • il file app.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my angular 2 app!';
  sign = 'Maurizio Attanasi';
  year = '2016';
}

• il file app.component.html
  
4. Avviamo il server in locale con il comando

$ ng serve


.
5. Aggiungiamo nella directory root del progetto il file .deployment che configurerà la directory di avvio del progetto, e contenente le righ che seguono:

[config]

project = dist

Preparazione e pubblicazione della Web App su azure

1. Utilizzando le funzionalità di azure-cli viste nel post precedente, creiamo la Web App

$ azure site create my-a2-app --git --gitusername ***

2. Aggiorniamo le modifiche del repository locale, eseguiamo il commit ed infine eseguiamo il push verso il repository remoto di azure

$ git add .

$ git commit -m "Initial commit"

$ git push azure master

Se la è andata a buon fine, la nostra shell di comando sarà simile a quella seguente

Ulteriore conferma dell’avvenuta pubblicazione possiamo averla navigando il portale di azure al percoso my-a2-app > Deployment options

Ed infine, raggiungendo l’indirizzo http://my-a2-app.azurewebsites.net/

Enjoy

Integrazione Continua su Azure con git e azure-cli

In un precedente post (Integrazione Continua con Visual Studio Team Service) avevo condiviso il link ad un tutorial che illustrava il servizio di Continuous Integration offerto da Visual Studio Team Services. In questa nota riporterò gli step necessari ad ottenere un risultato analogo
per la pubblicazione su una Web Application su Azure sfruttando git come sistema di versioning, e azure-cli, un’interfaccia della riga di comando di Azure.
Gli strumenti necessari per raggiungere il nostro fine sono:

• node.js (del quale utilizzeremo il gestore dei pacchetti, npm, per l’installazione, tra l’altro, di angular-cli);
• git;
• azure-cli;
• un account Azure valido (anche un free trial);

Data la natura degli strumenti sopra elencati, la procedura che andremo a descrivere vale per tutti i sistemi operativi per i quali tali strumenti sono disponibili, e quindi Windows, Linux e osX/macOS.
In primo luogo verifichiamo che sul sistema sia installato Node.js eseguendo su una shell di comando

bash-3.2$ node --version
v7.2.0

Nel caso in cui Node.js non sia presente sul sistema procederemo alla sua installazione seguendo le istruzioni presenti sul sito.
Allo stesso modo verifichiamo la presenza sul nostro sistema di git

bash-3.2$ git --version
git version 2.9.3 (Apple Git-75)

e azure-cli

bash-3.2$ azure --version
0.10.7 (node: 7.2.0)

Nel caso in cui questo pacchetto non sia presente sul sistema, utilizzeremo npm per la sua installazione

npm install -g azure-cli

Preparati gli strumenti necessari, procediamo alla realizzazione di una Web Application ed alla sua pubblicazione su Azure.

1. Login
   Per eseguire il login dalla linea di comando di azure, eseguiamo:

$ azure login

e seguiamo le istruzioni riportate nella risposta

2. Impostazione Gestione servizi di Azure (asm)
Per abilitare i comandi della modalità Service Management dell’interfaccia della riga di comando di Azure, eseguire il comando.

bash-3.2$ azure config mode asm

1. Impostazione dell’utente per la pubblicazione
   Per impostare nome utente e password per la pubblicazione della Web Application, eseguire il comando:

azure site deployment user set --username <username> --pass <password>

Creazione della Web Application

Tra le varie possibilità disponibili, (html, asp.net, Node.js, …), realizzeremo una Web Application faremo con l’ultima nata delle tecnologie ASP.NET:
ASP.NET Core.
Verifichiamo la presenza dell’sdk sul nostro sistema con il comando

bash-3.2$ dotnet --version
1.0.0-preview2-1-003177

Nel caso in cui .net non sia presente, seguiamo le istruzioni
relative al sistema operativo di nostro interesse.

Yeoman

Per semplificare l’implementazione della web app utilizzeremo Yeoman, il set di strumenti per la creazione di progetti web già visto in un precedente post.
In primo luogo procederemo all’installazione del generator necessario alla realizzazione di un progetto .net Core con il comando

$ sudo npm install -g generator-aspnet

Procediamo quindi alla creazione del nostro progetto creando la seguente gerarchia di directories:

$ mkdir CloudWorkbenchWebApplication
$ mkdir CloudWorkbenchWebApplication/src
$ mkdir CloudWorkbenchWebApplication/test
$ cd CloudWorkbenchWebApplication/

Nella cartella root del nostro progetto, creiamo il file global.json
che conterrà il seguente oggetto json

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-preview2-1-003177"
  }
}

Spostandoci nella cartella src, eseguiamo il comando

$ yo aspnet

in risposta al quale verrà avviata una procedura guidata per la creazione del nostro progetto

Selezionando la voce Empty Web Application, e, in seguito assegnando il nome CloudWorkbenchWebApplication,
verrà creata l’infrastruttura di una semplice Web Application ASP.NET Core.
Spostandoci nella cartella appena creata (CloudWorkbenchWebApplication), eseguiamo in sequenza i comandi

dotnet restore
dotnet run

In questo modo abbiamo avviato, sulla nostra macchina un Web Server che risponderà all’indirizzo riportato (nel nostro caso http://localhost:5000/).
Avviando un browser e puntando all’indirizzo di cui sopra avremo:

Et voilà, abbiamo la nostra Web Application!

Creazione del repository git

Tornando nella directory root del nostro progetto (quella contenente la cartelle src e test ed il file global.json),
1. creiamo il repository git

$ git init

1. aggiungiamo tutti i files e le cartelle create

$ git add .

1. eseguiamo il primo commit

$ git commit -m "Initial commit"

Creazione della Web Application su Azure

Mediante la linea di comando di azure, creiamo la nostra web application

 azure site create <app_name> --git --gitusername <username>

dove app_name è il nome che assegneremo alla web application, e username è il nome utente impostato nel passaggio precedente.

Selezioniamo il server sul quale pubblicheremo la nostra applicazione (nel nostro caso 3. West Europe).
Al termine dell’operazione, accedendo al portale di Azure, avremo, tra le risorse disponibili, quella appena creata

Visualizzando i dettagli della nostra App, abbiamo

e, selezionando il pulsante Browse siamo in grado di visualizzare la web app appena creata (anche se vuota).

Pubblicazione della web application

Siamo pronti per eseguire il primo push verso il repository azure creato in precedenza.
A tal fine eseguiamo il comando

$ git push azure master

Oltre che copiare i file dal nostro repository locale al site di azure, il processo avvierà le operazioni di restore e build dell’applicazione, ed infine alla pubblicazione dell’app.
Se l’operazione è andata a buon fine, ricaricando il browser all’indirizzo precedente, abbiamo:

Et voilà ancora!!! Abbiamo ottenuto il risultato voluto, ovvero siamo riusciti a pubblicare la nostra web application raggiungibile all'indirizzo http://cloud-workbench.azurewebsites.net/ utilizzando git e la linea di comando di azure.

Configurazione versione di Node.js

Poiché la web application che abbiamo appena creato sarà il punto di partenza per una serie prove per verificare le potenzialità di Azure per le applicazioni IoT, per provare Angular 2 in combinazione con .net core, ed altro ancora, facciamo un ulteriore passaggio per aggiornare la versione di Node.js di della nostra app azure con quella installata sul nostro sistema di sviluppo (la 7.2.0, come abbiamo visto all’inizio del post).
Tra gli Application Settings della nostra Web App individuiamo la chiave WEBSITE_NODE_DEFAULT_VERSION e modifichiamone il valore a 7.2.0, come illustrato nell’immagine seguente.
.
Salvando le modifiche effettuate il sito verrà riavviato e, se non ci sono problemi, ricaricando la pagina otterremo ancora il nostro Hello World.

Enjoy

Visual Studio Dev Essentials

Per chi come me è costantemente alla ricerca di nuovi stimoli per migliorare le proprie conoscenze e di tenersi al passo con lo stato dell’arte, voglio condividere un suggerimento utile a chi vuole implementare soluzioni con il meglio delle tecnologie Microsoft.
Visual Studio Dev Essentials, il cui claim è Everything you need all in one place, ed effettivamente è un po’ un *santo graal* dal quale attingere strumenti di sviluppo, formazione di livello altissimo, e *last but not least*, un credito mensile di 25€ da spendere in servizi Microsoft Azure.

Tra le risorse messe a disposizione, quella, a mio avviso, più preziosa, è proprio l’accesso temporaneo o a tempo indeterminato ai corsi, del quale ho già cominciato ad usufruire, approfondendo gli argomenti relativi allo stato dell’arte del nuovo stack per applicazioni web di Microsoft ASP.Net Core con il corso Building a Web App with ASP.NET Core, MVC 6, EF Core, and Angular.

Enjoy

Internet of Things & M.E.A.N Stack - (Part IV)

Continuiamo con l'esplorazione delle varie tecnologie legate al mondo dell'Internet Of Things, valutando un altro dei protocolli utilizzati nella comunicazione M2M, il protocollo CoAP. Come al solito, ho seguito un approccio hand-on, la cui implementazione è disponibile su GitHub al link.

Enjoy

Integrazione Continua con Visual Studio Team Service

Nel video che segue viene proposta un'interessante dissertazione su una delle nuove features introdotte da Visual Studio Team Services, l'Integrazione Continua, o CI (Continuous Integration), ovvero la pratica che prevede l'utilizzo "intensivo" di un sistema di versioning, spesso con il supporto di un tool di Build automatico.



Have fun

Internet of Things & M.E.A.N Stack - (Part III)

Finalmente siamo arrivati al momento in cui tenteremo di togliere parte della simulazione dai nostri test. A tal fine torna utile un Arduino Due che riposava in un cassetto da troppo tempo.

L’approccio ufficiale per la programmazione di questo giocattolo, passa per l’utilizzo dell’IDE ufficiale scaricabile dal link,

che, sebbene sia un ottimo strumento per far approcciare chi non ha grandi esperienze di programmazione al mondo del DIY, per la realizzazione di questo esempio, abbiamo utilizzato Atom, un ottimo editor di testo disponibile gratuitamente per i maggiori sistemi operativi, unitamente al plugin PlatformIO.

Come al solito, per la descrizione dettagliata dell’implementazione di questo nuovo step, si rimanda al repository GitHub creato per questa serie di note, raggiungibile dal link.

Nel video seguente viene data una dimostrazione riassuntiva dei risultati ottenuti in questa serie di note su IoT e M.E.A.N. Stack.

Have Fun.

Internet of Things & M.E.A.N Stack - (Part II)

Continuiamo il discorso iniziato con la nota precedente, Internet of Things & M.E.A.N Stack, nel quale abbiamo esplorato alcune opzioni per implementare un web server che fornisse il nostro sistema delle funzionalità C.R.U.D necessarie per interfacciarci al database NoSQL mongoDB.
Lo step successivo è quello di utilizzare il framework M.E.A.N. per creare una Single Page Application che ci consenta di visualizzare i dati storici e real-time prodotti dal nostro sistema IoT.
Per i dettagli relativi all’implementazione, rimandiamo al repository GitHub, nel quale sono disponibili sia i sorgenti che la descrizione degli strumenti utilizzati e dei passi seguiti.
La web app realizzata si compone di una home page che si presenta come:

La seconda pagina, dedicata alla visualizzazione dei dati storici salvati dal client mqtt realizzato in precedenza mediante il servizio REST, ha una visualizzazione tabellare dei dati

ed una grafica

Infine, last but not least, abbiamo una vista nella quale i dati provenienti dal campo, vengono visualizzati in tempo reale.

Il prossimo obiettivo, è quello di realizzare un caso non simulato di dispositivo IoT. A tal fine proveremo ad utilizzare l’implementazione Embedded C++ del progetto paho,

in abbinamento ad un controller Arduino Due.


Have Fun

Internet of Things & M.E.A.N Stack

Approfittando degli esperimenti sui protocolli di comunicazione legati al mondo dell’IoT, iniziati con la nota Internet Of Things - Protocolli di Comunicazione, cogliamo l’occasione per valutare il grado di integrabilità, tra le tecnologie che ruotano intorno a questo mondo, ed un insieme di strumenti che ha attirato la mia attenzione durante quest anno, che vanno sotto la denominazione di M.E.A.N Stack, che si propongono come la miglior alternativa ai classici stack per lo sviluppo di applicazioni web (.NET, LAMP, ...).

M.	E.	A.	N.

Tra le varie risorse utilizzate per apprendere le basi delle tecnologie coinvolte, una menzione speciale va alla piattaforma di e-learning gratuita Microsoft Virtual Academy
ed in particolare ai seguenti tutorial:

• MEAN Stack Jump Start;
• MongoDB and Redis Caching;
• Introduction to AngularJS;
• Mastering Node.js Modules and Packages with Visual Studio Code;

Un’altra preziosa fonte di informazioni è stata il video tutorial ed il blog di Travis Tidwell che introduce degli strumenti formidabili per la realizzazione rapida sia delle funzionalità lato server (le API REST che consentiranno, nel nostro caso, si salvare su db i dati provenienti dal campo), che lato client, rendendo possibile la realizzazione di un front-end che sfrutti appieno le tecnologie dello stack in esame.



Il primo risultato di tale integrazione, per i cui dettagli si rimanda al repository creato in occasione della precedente nota, è stato quello di realizzare un’infrastruttura in grado di persistere le letture dal campo del nostro termostato intelligente, su un database mongoDB.
In particolare è stato implementato un server REST che consente le operazioni C.R.U.D. sul db, ed è stato modificato il comportamento dell’oggetto remote in modo da esguire una scrittura sul database per ogni dato ricevuto dall’oggetto thermostat. L’esito di un run della simulazione è quello di avere i dati serializzati nel nostro database NoSQL pronti per eventuali analisi successive.

Eseguendo una query sulla collection thermostats dal prompt dei comandi, l’esito è:



oppure utilizzando il client visuale Robomongo,



Have fun.

Internet Of Things - Protocolli di Comunicazione

Riprendendo il discorso iniziato nella nota Industry 4.0. -To boldly go where no man has gone before… (Part II), entro la fine del 2020, 20.8 miliardi di dispositivi saranno connessi ad internet per formare l’Internet delle Cose. Considerando che, per lo stesso anno è prevista una popolazione mondiale di poco superiore a 7.5 miliardi, avremo, connessi ad internet, circa tre dispositivi per abitante sulla terra.

Sulla base di questa considerazione, la domanda che sorge spontanea, è: “come si connetteranno tutti questi dispositivi tra loro, ai provider di servizi o, più in generale al cloud, considerando che, in generale, il requisito principale sarà quello di garantire una minima occupazione di banda, e massima efficienza energetica, e che le risorse computazionali disponibili saranno, nella quasi totalità dei casi, molto ridotte?“.
Una risposta alla domanda, ci viene dalla seguente tabella, che riassume i requisiti minimi dell’hardware e delle infrastrutture di rete per consentire l’implementazione di un’efficace comunicazione M2M.

fonte Electronic Design
Obiettivo di questa nota è quello di esplorare, con un approccio hands-on, alcuni degli strumenti attualmente disponibili per l’implementazione di tale comunicazione, simulando l’implementazione di un termostato intelligente, e di diversi tipi di controllo remoto dello stesso. I risultati, e le note dei vari step intermedi saranno disponibili su un repository Internet Of Things creato per l’occasione su GitHub.

Have fun

Industry 4.0. -To boldly go where no man has gone before... (Part II)

Dopo un’introduzione generale dell’argomento, definiamo le due aree della rivoluzione Industry 4.0 che meglio si sposano con i miei interessi, ovvero:

• Internet of Things;
• Additive Manufacturing (stampa 3D ed affini).

Iniziamo a definire, per grandi linee, il primo dei due, l’Internet of Things (o IoT).

Una prima definizione di Internet of Things venne data nel 1999 da Kevin Ashton, allora a capo dell’Auto-ID Center del Massachusetts Institute of Technology, che legava la nascita dell’IoT alla diffusione dei dispositivi RFID. In altre parole, per parlare di IoT, ogni oggetto doveva poter essere univocamente identificato e/o catalogato. In tal senso, più che di IoT è giusto parlare di Unique Addressability of Things, che però rappresenta correttamente solo uno dei requirements, l’identificabilità univoca di ogni attore del sistema. Con riferimento a tale aspetto, accanto alle tecnologie RFID, citiamo, per completezza due tecnologie più recenti per l’identificazione:

• Near Field Communication (NFC);
• Codici visivi mono e bidimensionali (barcodes, QR codes, e via dicendo); 

Una descrizione più adeguata, è, a mio parere, quella che definisce l’IoT come “una miscela inestricabile di hardware, software, dati e servizi“, in quanto focalizza l’attenzione su

• i requisiti di interconnessione tra dispostivi (M2M);
• tra dispositivi e servizi, software di gestione/controllo (Business Intelligence - BI);
• lo storage dei dati acquisiti (Data/Cloud);

rendendo di fatto indispensabile, per poter parlare di IoT, una connessione ad Internet stabile, veloce e continua.

Spostando l’attenzione sull’ultima lettera dell’acronimo, un oggetto/dispositivo (Thing),

si caratterizza o definisce per le capacità d’interazione con l’ambiente circostante (sistema) che gli consentono di

• ‘leggerne’ lo stato attuale mediante un’opportuna serie di sensori;
• generare un flusso consistente di dati utili alla definizione di modelli in grado di descrivere tale sistema e prevederne l’evoluzione futura al variare delle condizioni al contorno;
• modificarne lo stato mediante un’adeguata disponibilità di attuatori.

Le possibilità di applicazione dell’IoT sono praticamente illimitate, spaziando dal controllo ambientale alla domotica, dal settore biomedicale ai trasporti, all’efficientamento energetico e all’organizzazione/ottimizzazione dei contesti urbani (Smart Cities), e via dicendo, il che fa si che anche l’interesse in tale settore coinvolge i maggiori attori privati ed istituzionali dell’economia mondiale. A tal proposito, una classificazione utile a definire attori e campi d’intervento è la seguente:

• Enterprise che raggruppa tutte le categorie dell’Industrial Internet of Things (IIoT);
• Home (Domotica, wearables, …);
• Government (Smart Cities, Energy, Biomedicale, …)

Criticità

Studi di settore (Gartner Inc.) prevedono che 20,8 miliardi di dispositivi formeranno l’Internet of Things entro il 2020, aprendo scenari totalmente nuovi che obbligheranno ognuno dei protagonisti sopra citati a rivedere, secondo le proprie competenze/responsabilità, il modo di concepire il mondo come lo conosciamo ora.

Una tra le maggiori sfide è certamente quella riguardante il tema della sicurezza. Poiché Internet è intrinsecamente insicuro, non possiamo aspettarci livelli di sicurezza maggiori dall’IoT. Anzi, il problema è ancora più evidente quando le implementazioni prevedono l’utilizzo di microcontrollori di fascia bassa che inevitabilmente non hanno una potenza di calcolo sufficiente, per esempio, all’esecuzione di opportuni algoritmi di criptaggio dei dati.

Quando poi l’IoT ha la possibilità di modificare lo stato dei sistemi nei quali è integrato, il problema della sicurezza è legato non tanto ai dati scambiati, ma anche all’incolumità delle persone che si trovano in prossimità di tali sistemi.

Per citare un esempio, l’anno scorso fece scalpore la pubblicazione di diversi articoli nei quali si dimostrava la vulnerabilità di un sistema di infotainment installato su molte vetture del gruppo FCA (Hackers Remotely Kill A Jeep On The Highway - With Me In IT ).

L’argomento è vasto e va oltre le finalità di questa nota (oltre che delle mie competenze), ad ogni modo è bene sapere che il problema esiste e va tenuto in conto in fase di studio/progettazione di un sistema IoT.

Maggiori informazioni a tal proposito possono essere trovate nelle seguenti fonti

• Insecure Internet of Things
• Internet of Crappy Things
• Searching For The Silver Bullet

Enabling technologies

Dopo aver inquadrato sinteticamente il tema dell’IoT, elenchiamo rapidamente quelle che saranno le tecnologie che avranno maggior impatto negli sviluppi futuri, in modo da avere una mappa di possibili argomenti sui quali investigare e/o sperimentare.

• 4G LTE;
• WiFi;
• ZigBee;
• Bluetooth Low Energy;
• Sensoristica miniaturizzata più efficiente;
• CPU multiprocessore più efficienti;
• Microcontrollori e SOC sempre più economici.

Enjoy