Consumo de una base de datos de documentos de Azure Cosmos DB en Xamarin.Forms

  • Artículo

Una base de datos de documentos de Azure Cosmos DB es una base de datos NoSQL que proporciona acceso de baja latencia a documentos JSON, lo que ofrece un servicio de base de datos rápido, altamente disponible y escalable para aplicaciones que requieren una escalabilidad sin problemas y una replicación global. En este artículo se explica cómo usar la biblioteca cliente de .NET Standard de Azure Cosmos DB para integrar una base de datos de documentos de Azure Cosmos DB en una aplicación de Xamarin.Forms.

Vídeo sobre Microsoft Azure Cosmos DB

Una cuenta de base de datos de documentos de Azure Cosmos DB se puede aprovisionar mediante una suscripción de Azure. Cada cuenta de base de datos puede tener cero o más bases de datos. Una base de datos de documentos en Azure Cosmos DB es un contenedor lógico para colecciones y usuarios de documentos.

Una base de datos de documentos de Azure Cosmos DB puede contener cero o más colecciones de documentos. Cada colección de documentos puede tener un nivel de rendimiento diferente, lo que permite especificar más rendimiento para las colecciones a las que se accede con frecuencia y menos rendimiento para las colecciones a las que se accede con poca frecuencia.

Cada colección de documentos consta de cero o más documentos JSON. Los documentos de una colección están libres de esquemas, por lo que no es necesario que compartan la misma estructura o campos. A medida que se agregan documentos a una colección de documentos, Azure Cosmos DB los indexa automáticamente y están disponibles para ser consultados.

Con fines de desarrollo, una base de datos de documentos también se puede consumir a través de un emulador. Con el emulador, las aplicaciones se pueden desarrollar y probar localmente, sin crear una suscripción de Azure ni incurrir en costos. Para obtener más información sobre el emulador, consulte Desarrollo local con el emulador de Azure Cosmos DB.

En este artículo, y la aplicación de ejemplo que acompaña, se muestra una aplicación de lista de tareas donde las tareas se almacenan en una base de datos de documentos de Azure Cosmos DB. Para obtener más información sobre la aplicación de ejemplo, consulte Descripción del ejemplo.

Para obtener más información sobre Azure Cosmos DB, consulte la Documentación sobre Azure Cosmos DB.

Nota:

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Configuración

El proceso para integrar una base de datos de documentos de Azure Cosmos DB en una aplicación Xamarin.Forms es el siguiente:

  1. Cree una cuenta de Azure Cosmos DB. Para obtener más información, consulte Creación de una cuenta de Azure Cosmos DB.
  2. Agregue el paquete NuGet de la biblioteca cliente de .NET Standard de Azure Cosmos DB a los proyectos de plataforma de la solución Xamarin.Forms.
  3. Agregue directivas using para los espacios de nombres Microsoft.Azure.Documents, Microsoft.Azure.Documents.Client y Microsoft.Azure.Documents.Linq a las clases que tendrán acceso a la cuenta de Azure Cosmos DB.

Después de realizar estos pasos, se puede usar la biblioteca cliente de .NET Standard de Azure Cosmos DB para configurar y ejecutar solicitudes en la base de datos de documentos.

Nota:

La biblioteca cliente de .NET Standard de Azure Cosmos DB solo se puede instalar en proyectos de plataforma y no en un proyecto de biblioteca de clases portable (PCL). Por lo tanto, la aplicación de ejemplo es un proyecto de acceso compartido (SAP) para evitar la duplicación de código. Sin embargo, la clase DependencyService se puede usar en un proyecto PCL para invocar el código de la biblioteca cliente de .NET Standard de Azure Cosmos DB contenido en proyectos específicos de la plataforma.

Consumo de la cuenta de Azure Cosmos DB

El tipo DocumentClient encapsula el punto de conexión, las credenciales y la directiva de conexión que se usan para acceder a la cuenta de Azure Cosmos DB y se usa para configurar y ejecutar solicitudes en la cuenta. En el siguiente ejemplo de código se muestra cómo crear una instancia de esta clase:

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

El URI de Azure Cosmos DB y la clave principal deben proporcionarse al constructor DocumentClient. Se pueden obtener desde Azure Portal. Para obtener más información, consulte Conexión de una cuenta de Azure Cosmos DB.

Crear una base de datos

Una base de datos de documentos es un contenedor lógico para colecciones de documentos y usuarios, y se puede crear en Azure Portal o mediante programación mediante el método DocumentClient.CreateDatabaseIfNotExistsAsync:

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

El método CreateDatabaseIfNotExistsAsync especifica un objeto Database como argumento, con el objeto Database que especifica el nombre de la base de datos como su propiedad Id. El método CreateDatabaseIfNotExistsAsync crea la base de datos si no existe o devuelve la base de datos si ya existe. Sin embargo, la aplicación de ejemplo omite los datos devueltos por el método CreateDatabaseIfNotExistsAsync.

Nota:

El método CreateDatabaseIfNotExistsAsync devuelve un objeto Task<ResourceResponse<Database>> y se puede comprobar el código de estado de la respuesta para determinar si se creó una base de datos o si se devolvió una base de datos existente.

Creación de una colección de documentos

Una colección de documentos es un contenedor para documentos JSON y se puede crear en Azure Portal o mediante programación mediante el método DocumentClient.CreateDocumentCollectionIfNotExistsAsync:

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
    });
  ...
}

El método CreateDocumentCollectionIfNotExistsAsync requiere dos argumentos obligatorios: un nombre de base de datos especificado como Uri y un objeto DocumentCollection. El objeto DocumentCollection representa una colección de documentos cuyo nombre se especifica con la propiedad Id. El método CreateDocumentCollectionIfNotExistsAsync crea la colección de documentos si no existe o devuelve la colección de documentos si ya existe. Sin embargo, la aplicación de ejemplo omite los datos devueltos por el método CreateDocumentCollectionIfNotExistsAsync.

Nota:

El método CreateDocumentCollectionIfNotExistsAsync devuelve un objeto Task<ResourceResponse<DocumentCollection>> y se puede comprobar el código de estado de la respuesta para determinar si se creó una colección de documentos o si se devolvió una colección de documentos existente.

De manera opcional, el método CreateDocumentCollectionIfNotExistsAsync también puede especificar un objeto RequestOptions, que encapsula las opciones que se pueden especificar para las solicitudes emitidas a la cuenta de Azure Cosmos DB. La propiedad RequestOptions.OfferThroughput se usa para definir el nivel de rendimiento de la colección de documentos y, en la aplicación de ejemplo, se establece en 400 unidades de solicitud por segundo. Este valor debe aumentarse o disminuirse en función de si se accederá con mayor o menor frecuencia a la colección.

Importante

Tenga en cuenta que el método CreateDocumentCollectionIfNotExistsAsync creará una nueva colección con un rendimiento reservado, lo que tiene implicaciones de precios.

Recuperación de documentos de una colección de documentos

El contenido de una colección de documentos se puede recuperar mediante la creación y ejecución de una consulta de documento. Se crea una consulta de documento con el método DocumentClient.CreateDocumentQuery:

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

Esta consulta recupera de manera asincrónica todos los documentos de la colección especificada y coloca los documentos en una colección List<TodoItem> para su visualización.

El método CreateDocumentQuery<T> especifica un argumento Uri que representa la colección que se debe consultar para los documentos. En este ejemplo, la variable collectionLink es un campo de nivel de clase que especifica el Uri que representa la colección de documentos de la que se van a recuperar documentos de:

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

El método CreateDocumentQuery<T> crea una consulta que se ejecuta de manera sincrónica y devuelve un objeto IQueryable<T>. Sin embargo, el método AsDocumentQuery convierte el objeto IQueryable<T> en un objeto IDocumentQuery<T> que se puede ejecutar de manera asincrónica. La consulta asincrónica se ejecuta con el método IDocumentQuery<T>.ExecuteNextAsync, que recupera la siguiente página de resultados de la base de datos de documentos, con la propiedad IDocumentQuery<T>.HasMoreResults que indica si hay resultados adicionales que se van a devolver desde la consulta.

Los documentos se pueden filtrar en el lado del servidor mediante la inclusión de una cláusula Where en la consulta, que aplica un predicado de filtrado a la consulta en la colección de documentos:

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

Esta consulta recupera todos los documentos de la colección cuya propiedad Done es igual a false.

Inserción de un documento en una colección de documentos

Los documentos son contenido JSON definido por el usuario y se pueden insertar en una colección de documentos con el método DocumentClient.CreateDocumentAsync:

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

El método CreateDocumentAsync especifica un argumento Uri que representa la colección en la que se debe insertar el documento y un argumento object que representa el documento que se va a insertar.

Reemplazo de un documento en una colección de documentos

Los documentos se pueden reemplazar en una colección de documentos mediante el método DocumentClient.ReplaceDocumentAsync:

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

El método ReplaceDocumentAsync especifica un argumento Uri que representa el documento de la colección que se debe reemplazar y un argumento object que representa los datos actualizados del documento.

Eliminación de un documento de una colección de documentos

Un documento se puede eliminar de una colección de documentos mediante el método DocumentClient.DeleteDocumentAsync:

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

El método DeleteDocumentAsync especifica un argumento Uri que representa el documento de la colección que se debe eliminar.

Eliminación de una colección de documentos

Una colección de documentos se puede eliminar de una base de datos mediante el método DocumentClient.DeleteDocumentCollectionAsync:

await client.DeleteDocumentCollectionAsync(collectionLink);

El método DeleteDocumentCollectionAsync especifica un argumento Uri que representa la colección de documentos que se va a eliminar. Tenga en cuenta que invocar este método también eliminará los documentos almacenados en la colección.

Eliminación de una base de datos

Se puede eliminar una base de datos de una cuenta de base de datos de Azure Cosmos DB mediante el método DocumentClient.DeleteDatabaesAsync:

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

El método DeleteDatabaseAsync especifica un argumento Uri que representa la base de datos que se va a eliminar. Tenga en cuenta que invocar este método también eliminará las colecciones de documentos almacenadas en la base de datos y los documentos almacenados en las colecciones de documentos.

Resumen

En este artículo se explica cómo usar la biblioteca cliente de .NET Standard de Azure Cosmos DB para integrar una base de datos de documentos de Azure Cosmos DB en una aplicación Xamarin.Forms. Una base de datos de documentos de Azure Cosmos DB es una base de datos NoSQL que proporciona acceso de baja latencia a documentos JSON, lo que ofrece un servicio de base de datos rápido, altamente disponible y escalable para aplicaciones que requieren una escalabilidad sin problemas y una replicación global.