Lo scorso 8 Luglio ho partecipato ad una giornata interamente dedicata ad ASP.NET Core 1.0, evento organizzato da Overnet Education, e portato a termine da Gabriele Gaggi ed Ugo Lattanzi. In quel frangente ovviamente si parlava di web, controller, web api, e via dicendo. Ricordo che Ugo ad un certo punto disse una cosa simile alla seguente: “secondo la convenzione, quando si invoca un metodo REST che aggiunge un oggetto al nostro repository, la response deve includere almeno due informazioni: l’ID dell’elemento appena aggiunto e l’URL al quale si possono reperire i dettagli dell’elemento stesso”. Scusate l’imprecisione, ma il web non è propriamente il mio campo. Ricordo di aver trovato interessante quell’affermazione di Ugo, al punto che lo interruppi chiedendogli…ma dove posso trovare queste regole, convenzioni, buone norme di implementazione di API di tipo REST?

Beh, oggi la risposta ce l’ho.

Su GitHub Microsoft ha pubblicato un repository denominato “Microsoft REST API Guidelines” ricco di documentazione, allo scopo di fornire a tutti gli sviluppatori le migliori guideline per l’implementazione di API REST. Tra gli autori figura un certo Mark Russinovich. Troverete informazioni su un po’ tutto: gestione degli errori, struttura degli URL, serializzazione in JSON, gestione corretta del versioning delle API, e molto altro ancora.

Sono piuttosto certo che troverete la lettura molto interessante!

Send to Kindle

I Cognitive Services sono un servizio relativamente nuovo che Microsoft ha reso disponibile. Grazie a questi servizi abbiamo a disposizione tutta una serie di API che ci permettono di effettuare riconoscimenti di immagini, emozioni, volti, testi, voci, riconoscimento degli speaker in un file audio, ed altro ancora. Trovate maggiori informazioni sul sito ufficiale.

Come sempre, per accedere a queste API è necessario registrarsi sul sito ed ottenere le Api Key da includere poi nelle chiamate REST. Nulla di particolarmente complicato.

Attenzione ad un particolare, però. Se un determinato servizio si appoggia su Azure, le Api Key non saranno quelle visibili sul portale dei Cognitive Services, ma saranno quelle visibili sul portale Azure. Mi spiego meglio. Se vado sul sito https://www.microsoft.com/cognitive-services/en-US/subscriptions e do un’occhiata al mio account, vedo la situazione seguente:

Sto facendo esperimenti con il servizio Speaker Recognition, che in forma gratuita prevede 10.000 transazioni al mese, 20 al minuto. Ho mantenuto nascoste le Api Key per privacy, ma anche facendole vedere sarebbe stato inutile, perchè queste API si appoggiano su Azure, e quindi le Api Key giuste vanno prelevate dal portale Azure. Notare infatti la presenza del bottone Buy On Azure proprio lì accanto. Cliccando su quel link viene aperto il marketplace su Azure che permette di completare l’acquisto del servizio vero e proprio. Ed è da Azure che dovrete copiare & incollare le Api Key corrette da utilizzare all’interno del proprio codice.

Notare che a me il servizio Cognitive Services risulta già attivo, nella sua forma FREE. Nel momento in cui vi scrivo, tale servizio è esposto solo dal data-center in West US. Una volta che avete attivato il servizio, esso sarà raggiungibile come tutte le altre risorse allocate sul cloud, e quindi da lì banalmente potete ottenere le Api Key corrette.

Send to Kindle

Un’app service è quel meccanismo di UWP che permette ad un’app di invocarne un’altra, di potergli passare determinati valori, per ottenere un risultato di qualche tipo. C’è quindi un legame tra “app client” ed “app service”, anche se tecnicamente si tratta di due app UWP che risiedono sullo stesso PC. Per poter dialogare, l’app client deve conoscere un po’ di informazioni:

• L’AppServiceName
• Il PackageFamilyName
• Di quali informazioni l’AppService necessita per poter svolgere il suo lavoro. Tra app client ed app service viaggia un’istanza di ValueSet, che può essere tranquillamente visto come un Dictionary<string, object>.

L’AppService deve essere implementato tramite un BackgroundTask, il quale però non ha bisogno di essere registrato come accadrebbe con un BackgroundTask tradizionale. Quindi, per riassumere:

• Abbiamo un’app UWP contenuta in una solution (l’AppService deve comunque sia essere hostato all’interno di un’app UWP tradizionale)
• All’interno di questa solution aggiungiamo un progetto di tipo “Windows Runtime Component”
• All’interno di questo progetto aggiungiamo una classe che implementa l’interfaccia IBackgroundTask, esattamente come un normalissimo BackgroundTask

Nel metodo Run previsto dall’interfaccia IBackgroundTask dobbiamo fare quanto segue:

• Dall’istanza IBackgroundTaskInstance che arriva in ingresso al metodo, dobbiamo sfruttare la proprietà TriggerDetails e farne il casting verso AppServiceTriggerDetails
• Sottoscriviamo l’evento RequestReceveid esposto dall’oggetto AppServiceConnection (ovvero, vedere la proprietà AppServiceConnection)
• All’interno dell’evento RequestReceveid, dobbiamo prelevare i valori che il client ci ha eventualmente passato. Questa cosa la si ottiene con:
  var message = args.Request.Message;
  int number = (int)message[“param1”];
  string strValue = message[“param2”].ToString();
• All’interno dell’evento RequestReceveid, prima o poi dovremo restituire qualcosa al client. Questo si ottiene con la seguente riga:

ValueSet returnValue = new ValueSet();
returnValue["ReturnValue"] = result;
await args.Request.SendResponseAsync(returnValue);
Come si vede, “returnValue” è un’istanza di ValueSet al cui interno abbiamo inserito una o più chiavi con il corrispondente valore.

Questo delegate verrà invocato quando l’app client invocherà l’AppService. A proposito di client, come si attiva il dialogo tra client ed il nostro AppService? Il legame è molto loose coupled.

service = new AppServiceConnection();
service.AppServiceName = "randomNumberService";
service.PackageFamilyName = "bcbc4d41-504f-4d99-8a93-43f5b9d4c404_xe5ny6wrzrhn8";

var status = await this.service.OpenAsync();

if (status != AppServiceConnectionStatus.Success)
{
    return;
}

La proprietà AppServiceName deve coincidere con quanto stabilito nel file di manifest dell’app UWP che hosta l’AppService. Idem per il PackageFamilyName. La chiamata al metodo OpenAsync() della classe AppServiceConnection ci restituisce un valore tratto dall’enum AppServiceConnectionStatus. Se qualcosa è andato storto, allora interrompiamo immediatamente l’esecuzione.

Altrimenti:

var message = new ValueSet();
message.Add("Operation", "Random");
message.Add("NumberA", 1);
message.Add("NumberB", 100);
AppServiceResponse response = await this.service.SendMessageAsync(message);

if (response.Status == AppServiceResponseStatus.Success)
{
    int result = (int)response.Message["ReturnValue"];
}

Nel frammento di codice qui sopra, preparo un oggetto ValueSet, con alcune coppie di chiave/valore, ed invoco l’AppService. Notare che la chiamata a SendMessageAsync passa all’AppService il nostro ValueSet. Otteniamo un valore di risposta; se è Success possiamo prelevare il valore di ritorno.

Notare che all’interno di ValueSet possiamo inserire oggetti serializzabili: numeri, stringhe ma anche ovviamente classi complesse.

L’AppService va dichiarato nella sezione “Declarations” del file di manifest dell’app UWP che hosta il servizio. E’ necessario quantomeno specificare il Name e l’entrypoint. Quest’ultimo, come accade con i BackgroundTask tradizionali, deve contenere il nome della classe (compreso di namespace) che implementa l’AppService stesso. Ricordo ancora una volta che questo BackgroundTask non va registrato come accadrebbe con un BackgroundTask tradizionale.

Send to Kindle

La classe ThreadPoolTimer ci fornisce due metodi statici che creano e danno lo Start a due tipi differenti di Timer:

• CreateTimer: crea un’istanza di ThreadPoolTimer che esegue un metodo dopo X secondi. Poi il timer si ferma.
• CreatePeriodicTimer: crea un’istanza di ThreadPoolTimer che esegue un metodo ogni X secondi (timer periodico)

In entrambi i casi il metodo da eseguire è specificato tramite il delegate TimerElapsedHandler.

In entrambi i casi il secondo parametro è un’istanza di TimeSpan. Nel primo caso rappresenta dopo quanto tempo il metodo deve essere eseguito. Nel secondo caso rappresenta l’intervallo di tempo che scatena periodicamente l’esecuzione del timer.

Entrambi i metodi prevedono un terzo parametro, un delegate TimerDestroyedHandler, che è il metodo che viene eseguito quando il timer termina la propria esecuzione.

Nel caso di CreateTimer, questo metodo viene eseguito in due momenti:

• quando il timer raggiunge il TimeSpan: prima viene eseguito il metodo TimerElapsedHandler, e poi TimerDestroyedHandler
• quando il timer viene (eventualmente) annullato dall’utente, ad esempio cliccando su un bottone

Nel caso di CreatePeriodicTimer, il metodo TimerDestroyedHandler viene eseguito solo quando l’utente eventualmente annulla e ferma il timer. Trattandosi di un timer periodico, teoricamente potrebbe proseguire all’infinito.

Entrambi i metodi restituiscono un’istanza di ThreadPoolTimer, istanza che dobbiamo salvarci da qualche parte, ad esempio per poterne invocare il metodo Cancel(). L’oggetto ThreadPoolTimer, oltre a questo metodo, espone anche tre property read-only:

• Delay, che è l’oggetto TimeSpan utilizzato dal Timer
• Period, che è l’intervallo di tempo previsto dal Timer periodico

Nel caso di CreateTimer, Delay contiene l’intervallo di tempo, mentre Period è zero.

Nel caso di CreatePeriodTimer, le due property equivalgono. Un timer periodico attende X secondi prima di eseguire TimerElapsedHandler, e poi ripete ogni X secondi. Delay e Period coincidono.

All’interno di TimerElapsedHandler o TimerDestroyedHandler non abbiamo ovviamente accesso al thread della UI, per cui dobbiamo passare dal Dispatcher della Window e chiamarne il metodo RunAsync se dobbiamo aggiornare qualcosa sull’interfaccia utente dell’applicazione.

Send to Kindle