Consumo de una base de datos de documentos de Azure Cosmos DB enXamarin.Forms

Descarga del ejemplo

Una base de datos de documentos de Azure Cosmos DB es una base de datos NoSQL que proporciona acceso de baja latencia a los 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 azure Cosmos DB .NET Standard para integrar una base de datos de documentos de Azure Cosmos DB en una Xamarin.Forms aplicación.

vídeo Microsoft Azure Cosmos DB

Se puede aprovisionar una cuenta de base de datos de documentos de Azure Cosmos DB 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 de documentos y usuarios.

Una base de Cosmos 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 no tienen esquemas, por lo que no es necesario compartir la misma estructura o campos. A medida que los documentos se agregan a una colección de documentos, Cosmos DB los indexa automáticamente y están disponibles para su consulta.

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 más información sobre el emulador, consulte Desarrollo local con azure Cosmos DB Emulator.

En este artículo, y en la aplicación de ejemplo que lo acompaña, se muestra una aplicación de lista de tareas en la que 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, vea Descripción del ejemplo.

Para más información sobre Azure Cosmos DB, consulte la documentación de Azure Cosmos DB.

Configurar

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

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

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

Consumo de la cuenta de Azure Cosmos DB

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

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

El Cosmos URI de base de datos y la clave principal deben proporcionarse al DocumentClient constructor. Se pueden obtener en Azure Portal. Para obtener más información, consulte Conectar a 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 con el DocumentClient.CreateDatabaseIfNotExistsAsync método :

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

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

Crear 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 con el DocumentClient.CreateDocumentCollectionIfNotExistsAsync método :

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

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

Recuperar documentos de 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 DocumentClient.CreateDocumentQuery método :

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 forma asincrónica todos los documentos de la colección especificada y coloca los documentos en una List<TodoItem> colección para mostrarlos.

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

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

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

Los documentos se pueden filtrar en el lado servidor mediante la inclusión de una cláusula en la consulta, que aplica un predicado de filtrado a la consulta Where 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 Done propiedad es igual a false .

Insertar 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 DocumentClient.CreateDocumentAsync método :

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

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

Reemplazar un documento en una colección de documentos

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

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

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

Eliminar un documento de una colección de documentos

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

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

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

Eliminación de una colección de documentos

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

await client.DeleteDocumentCollectionAsync(collectionLink);

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

Eliminar una base de datos

Una base de datos se puede eliminar de una Cosmos base de datos de base de datos con el DocumentClient.DeleteDatabaesAsync método :

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

El DeleteDatabaseAsync método especifica un argumento que representa la base de datos que se va a Uri eliminar. Tenga en cuenta que al invocar este método también se eliminarán 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 Azure Cosmos DB .NET Standard para integrar una base de datos de documentos de Azure Cosmos DB en una Xamarin.Forms aplicación. Una base de datos de documentos de Azure Cosmos DB es una base de datos NoSQL que proporciona acceso de baja latencia a los 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.

Vínculos relacionados

• Todo Azure Cosmos DB (ejemplo)
• Documentación sobre Azure Cosmos DB
• Biblioteca cliente .NET Standard azure Cosmos DB
• API de Azure Cosmos DB