Usare un database di documenti di Azure Cosmos DB in Xamarin.Forms

  • Articolo

Download Sample Scaricare l'esempio

Un database di documenti di Azure Cosmos DB è un database NoSQL che fornisce accesso a bassa latenza ai documenti JSON, offrendo un servizio di database veloce, a disponibilità elevata e scalabile per le applicazioni che richiedono scalabilità e replica globale senza problemi. Questo articolo illustra come usare la libreria client .NET Standard di Azure Cosmos DB per integrare un database di documenti di Azure Cosmos DB in un'applicazione Xamarin.Forms .

Video di Microsoft Azure Cosmos DB

È possibile effettuare il provisioning di un account del database di documenti di Azure Cosmos DB usando una sottoscrizione di Azure. Ogni account di database può avere zero o più database. Un database di documenti in Azure Cosmos DB è un contenitore logico per raccolte documenti e utenti.

Un database di documenti di Azure Cosmos DB può contenere zero o più raccolte documenti. Ogni raccolta documenti può avere un livello di prestazioni diverso, consentendo di specificare una maggiore velocità effettiva per le raccolte a cui si accede di frequente e una minore velocità effettiva per le raccolte a cui si accede raramente.

Ogni raccolta di documenti è costituita da zero o più documenti JSON. I documenti in una raccolta sono privi di schema e pertanto non è necessario condividere la stessa struttura o gli stessi campi. Man mano che i documenti vengono aggiunti a una raccolta documenti, Azure Cosmos DB li indicizza automaticamente e diventano disponibili per l'esecuzione di query.

Ai fini dello sviluppo, un database di documenti può essere utilizzato anche tramite un emulatore. Usando l'emulatore, le applicazioni possono essere sviluppate e testate in locale, senza creare una sottoscrizione di Azure o sostenere costi. Per altre informazioni sull'emulatore, vedere Sviluppo in locale con l'emulatore di Azure Cosmos DB.

Questo articolo e l'applicazione di esempio associata illustra un'applicazione elenco Todo in cui le attività vengono archiviate in un database di documenti di Azure Cosmos DB. Per altre informazioni sull'applicazione di esempio, vedere Informazioni sull'esempio.

Per altre informazioni su Azure Cosmos DB, vedere la documentazione di Azure Cosmos DB.

Nota

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Attrezzaggio

Il processo di integrazione di un database di documenti di Azure Cosmos DB in un'applicazione Xamarin.Forms è il seguente:

  1. Creare un account Azure Cosmos DB. Per altre informazioni, vedere Creare un account Azure Cosmos DB.
  2. Aggiungere il pacchetto NuGet della libreria client .NET Standard di Azure Cosmos DB ai progetti della piattaforma nella Xamarin.Forms soluzione.
  3. Aggiungere using direttive per gli spazi dei Microsoft.Azure.Documentsnomi , Microsoft.Azure.Documents.Cliente Microsoft.Azure.Documents.Linq alle classi che accederanno all'account Azure Cosmos DB.

Dopo aver eseguito questi passaggi, è possibile usare la libreria client .NET Standard di Azure Cosmos DB per configurare ed eseguire richieste nel database di documenti.

Nota

La libreria client .NET Standard di Azure Cosmos DB può essere installata solo nei progetti della piattaforma e non in un progetto PCL (Portable Class Library). Pertanto, l'applicazione di esempio è un progetto di accesso condiviso (SAP) per evitare la duplicazione del codice. Tuttavia, la DependencyService classe può essere usata in un progetto PCL per richiamare il codice della libreria client .NET Standard di Azure Cosmos DB contenuto in progetti specifici della piattaforma.

Utilizzo dell'account Azure Cosmos DB

Il DocumentClient tipo incapsula l'endpoint, le credenziali e i criteri di connessione usati per accedere all'account Azure Cosmos DB e viene usato per configurare ed eseguire richieste sull'account. Nell'esempio di codice seguente viene illustrato come creare un'istanza di questa classe:

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

L'URI di Azure Cosmos DB e la chiave primaria devono essere forniti al DocumentClient costruttore. Queste informazioni possono essere ottenute dal portale di Azure. Per altre informazioni, vedere Connessione a un account Azure Cosmos DB.

Creazione di un database

Un database di documenti è un contenitore logico per raccolte documenti e utenti e può essere creato nel portale di Azure o a livello di codice usando il DocumentClient.CreateDatabaseIfNotExistsAsync metodo :

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

Il CreateDatabaseIfNotExistsAsync metodo specifica un Database oggetto come argomento, con l'oggetto Database che specifica il nome del database come proprietà Id . Il CreateDatabaseIfNotExistsAsync metodo crea il database se non esiste o restituisce il database, se già esistente. Tuttavia, l'applicazione di esempio ignora tutti i dati restituiti dal CreateDatabaseIfNotExistsAsync metodo .

Nota

Il CreateDatabaseIfNotExistsAsync metodo restituisce un Task<ResourceResponse<Database>> oggetto e il codice di stato della risposta può essere controllato per determinare se è stato creato un database o se è stato restituito un database esistente.

Creazione di una raccolta documenti

Una raccolta di documenti è un contenitore per i documenti JSON e può essere creata nel portale di Azure o a livello di codice usando il DocumentClient.CreateDocumentCollectionIfNotExistsAsync metodo :

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

Il CreateDocumentCollectionIfNotExistsAsync metodo richiede due argomenti obbligatori: un nome di database specificato come Urie un DocumentCollection oggetto . L'oggetto DocumentCollection rappresenta un insieme di documenti il cui nome viene specificato con la Id proprietà . Il CreateDocumentCollectionIfNotExistsAsync metodo crea la raccolta documenti se non esiste o restituisce la raccolta documenti, se già esistente. Tuttavia, l'applicazione di esempio ignora tutti i dati restituiti dal CreateDocumentCollectionIfNotExistsAsync metodo .

Nota

Il CreateDocumentCollectionIfNotExistsAsync metodo restituisce un Task<ResourceResponse<DocumentCollection>> oggetto e il codice di stato della risposta può essere controllato per determinare se è stata creata una raccolta documenti o se è stata restituita una raccolta documenti esistente.

Facoltativamente, il CreateDocumentCollectionIfNotExistsAsync metodo può anche specificare un RequestOptions oggetto , che incapsula le opzioni che possono essere specificate per le richieste inviate all'account Azure Cosmos DB. La RequestOptions.OfferThroughput proprietà viene utilizzata per definire il livello di prestazioni della raccolta documenti e nell'applicazione di esempio è impostata su 400 unità richiesta al secondo. Questo valore deve essere aumentato o diminuito a seconda che la raccolta sia spesso o raramente accessibile.

Importante

Si noti che il CreateDocumentCollectionIfNotExistsAsync metodo creerà una nuova raccolta con una velocità effettiva riservata, con implicazioni sui prezzi.

Recupero di documenti di raccolta documenti

Il contenuto di una raccolta di documenti può essere recuperato creando ed eseguendo una query di documento. Viene creata una query di documento con il DocumentClient.CreateDocumentQuery metodo :

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

Questa query recupera in modo asincrono tutti i documenti dalla raccolta specificata e inserisce i documenti in una List<TodoItem> raccolta per la visualizzazione.

Il CreateDocumentQuery<T> metodo specifica un Uri argomento che rappresenta l'insieme su cui deve essere eseguita una query per i documenti. In questo esempio la collectionLink variabile è un campo a livello di classe che specifica l'oggetto Uri che rappresenta la raccolta documenti da cui recuperare i documenti:

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

Il CreateDocumentQuery<T> metodo crea una query eseguita in modo sincrono e restituisce un IQueryable<T> oggetto . Tuttavia, il AsDocumentQuery metodo converte l'oggetto IQueryable<T> in un IDocumentQuery<T> oggetto che può essere eseguito in modo asincrono. La query asincrona viene eseguita con il IDocumentQuery<T>.ExecuteNextAsync metodo , che recupera la pagina successiva dei risultati dal database di documenti, con la IDocumentQuery<T>.HasMoreResults proprietà che indica se sono presenti risultati aggiuntivi da restituire dalla query.

I documenti possono essere filtrati sul lato server includendo una Where clausola nella query, che applica un predicato di filtro alla query sulla raccolta documenti:

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

Questa query recupera tutti i documenti dall'insieme la cui Done proprietà è uguale a false.

Inserimento di un documento in una raccolta documenti

I documenti sono contenuti JSON definiti dall'utente e possono essere inseriti in una raccolta documenti con il DocumentClient.CreateDocumentAsync metodo :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

Il CreateDocumentAsync metodo specifica un Uri argomento che rappresenta l'insieme in cui inserire il documento e un object argomento che rappresenta il documento da inserire.

Sostituzione di un documento in una raccolta documenti

I documenti possono essere sostituiti in una raccolta documenti con il DocumentClient.ReplaceDocumentAsync metodo :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

Il ReplaceDocumentAsync metodo specifica un Uri argomento che rappresenta il documento nell'insieme che deve essere sostituito e un object argomento che rappresenta i dati aggiornati del documento.

Eliminazione di un documento da una raccolta documenti

Un documento può essere eliminato da una raccolta documenti con il DocumentClient.DeleteDocumentAsync metodo :

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

Il DeleteDocumentAsync metodo specifica un Uri argomento che rappresenta il documento nell'insieme che deve essere eliminato.

Eliminazione di una raccolta documenti

Una raccolta di documenti può essere eliminata da un database con il DocumentClient.DeleteDocumentCollectionAsync metodo :

await client.DeleteDocumentCollectionAsync(collectionLink);

Il DeleteDocumentCollectionAsync metodo specifica un Uri argomento che rappresenta l'insieme di documenti da eliminare. Si noti che richiamare questo metodo eliminerà anche i documenti archiviati nella raccolta.

Eliminazione di un database

È possibile eliminare un database da un account del database Azure Cosmos DB con il DocumentClient.DeleteDatabaesAsync metodo :

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

Il DeleteDatabaseAsync metodo specifica un Uri argomento che rappresenta il database da eliminare. Si noti che richiamare questo metodo eliminerà anche le raccolte documenti archiviate nel database e i documenti archiviati nelle raccolte documenti.

Riepilogo

Questo articolo ha illustrato come usare la libreria client .NET Standard di Azure Cosmos DB per integrare un database di documenti di Azure Cosmos DB in un'applicazione Xamarin.Forms . Un database di documenti di Azure Cosmos DB è un database NoSQL che fornisce accesso a bassa latenza ai documenti JSON, offrendo un servizio di database veloce, a disponibilità elevata e scalabile per le applicazioni che richiedono scalabilità e replica globale senza problemi.