DocumentDB: l'emulatore locale

pubblicato da , il 11/01/2017 alle 0.00

Data Access  Microsoft Azure  NoSQL 

DocumentDB è il database NoSQL disponibile su Azure. Alta affidabilità, scalabilità e possibilità di utilizzo di javascript e SQL come linguaggi di interrogazione dei dati sono solo alcune delle feature che lo caratterizzano.
Una delle funzionalità più richieste dagli sviluppatori, come si può vedere qui, era la possibilità di avere un "free tier" per poter testare e utilizzare DocumentDB senza incorrere nei costi del servizio. Il team di DocumentDB ha fatto di più: ha rilasciato un emulatore locale, per ora in public preview, che risolve anche un altro problema per gli sviluppatori, ovvero la possibilità di sviluppare codice, basato sulle funzionalità di DocumentDB, senza dover essere necessariamente online.

In questo articolo vedremo come installare l'emulatore, come utilizzarlo nello sviluppo e test locale delle nostre applicazioni e quali differenze ci sono rispetto alla versione online.

Installazione

E' possibile scaricare l'installer dell'emulatore di DocumentDB dal seguente url: https://aka.ms/documentdb-emulator.
Al termine dell'installazione una nuova applicazione sarà disponibile attraverso lo start menu di windows, come mostrato nell'immagine seguente:

local emulator app

Avviando l'applicazione una nuova icona compare nella taskbar notification area dalla quale è possibile gestire l'istanza dell'emulatore:

local emulator launcher

Di default l'emulatore è configurato per stare in ascolto sulla porta 8081. Accedendo all'url https://localhost:8081/_explorer/index.html o selezionando l'opzione "Open Data Explorer..." mostrato nell'immagine precedente, è possibile accedere ad una console web di "amministrazione" per monitorare lo stato di collection e documenti dello storage locale.

Come funziona?

L'utilizzo dell'emulatore locale nello sviluppo delle nostre applicazioni garantisce la stessa developer experience della versione online di DocumentDB: è quindi possibile, per esempio, creare e ricercare documenti JSON oppure creare ed invocare stored procedure e viste.
Essendo un emulatore ed essendo in esecuzione sul pc locale e non nell'environment tipico di DocumentDB, messo a disposizione da Azure ci sono comunque alcune differenze:

  • l'emulatore supporta una solo coppia di account/master key per l'accesso
  • l'emulatore non supporta un alto numero di collection e non è pensato per essere scalabile
  • l'emulatore non supporta le diverse tipologie di "consistenza" del servizio online. (Per una descrizione dettagliata di questa funzionalità si rimanda il lettore ai precedenti articoli pubblicati in merito a DocumentDB)

La connessione all'emulatore locale, tramite l'SDK del nostro linguaggio di riferimento, è stabilita nello stesso modo di quanto avviene per connettersi al servizio reale di DocumentDB, come mostra lo snippet di codice seguente:

var uri = new Uri("https://localhost:8081/");
var key = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";

var client = new DocumentClient(uri, key);

Come detto in precedenza, la porta 8081 è la porta di default a cui risponde l'emulatore locale, mentre il valore della variabile >key è il valore di default dell'authorization key per connettersi all'emulatore.
Sia la porta, sia il valore dell'authorization key possono essere customizzati in fase di avvio dell'emulatore, avviandolo da command line specificando opportuni parametri.

Lo snippet di codice seguente mostra come creare database, collection o documenti. Come si può notare nulla cambia utilizzando l'emulatore locale o il servizio online:

var database = await client.CreateDatabaseAsync(new Database { Id = "ugidotnet" });
var collection = await client.CreateDocumentCollectionAsync(database.Resource.SelfLink, new DocumentCollection { Id = "articles" });

var article = new Article
{
  Id = "1",
  Title = "DocumentDB: emulatore locale",
  Author = "Melchiori Alessandro",
  PublishDate = DateTime.Now
};
await client.CreateDocumentAsync(collection.Resource.DocumentsLink, article);

Il risultato è visibile dalla console web disponibile all'indirizzo https://localhost:8081/_explorer/index.html

local emulator webconsole

L'emulatore locale supporta anche il protocollo di comunicazione di MongoDB, così come il servizio online, come descritto in uno dei nostri precedenti articoli.
Il seguente snippet di codice dimostra come stabilire a connessione all'emulatore locale in modalità MongoDB:

var client = new MongoClient(@"mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10250/admin?ssl=true&3t.sslSelfSignedCerts=true");

La porta 10250 è la porta di default che l'emulatore usa per la comunicazione tramite il protocollo di MongoDB. Anche questo parametro è customizzabile avviando l'emulatore da command line.

Conclusioni

L'avvento dell'emulatore locale rende estremamente più naturale l'adozione di DocumentDB semplificando notevolmente la vita dello sviluppatore che non si trova più costretto ad essere online per sviluppare e testare la propria applicazione o dover pianificare costi anche per la fase di sviluppo.