Exploración del SDK v3 de Microsoft .NET para Azure Cosmos DB

  • 3 minutos

Esta unidad se centra en el SDK v3 de .NET de Azure Cosmos DB para la API para NoSQL. (Paquete NuGet Microsoft.Azure.Cosmos). Si está familiarizado con la versión anterior del SDK de .NET, es posible que esté familiarizado con la colección de términos y el documento.

El repositorio azure-cosmos-dotnet-v3 GitHub incluye las soluciones de ejemplo de .NET más recientes. Utilice estas soluciones para realizar CRUD (crear, leer, actualizar y eliminar) y otras operaciones comunes en los recursos de Azure Cosmos DB.

Dado que Azure Cosmos DB admite varios modelos de API, la versión 3 del SDK de .NET usa los términos genéricos contenedor y elemento. Un contenedor puede ser una colección, un grafo o una tabla. Un elemento puede ser un documento, un borde o vértice, o una fila, y es el contenido dentro de un contenedor.

A continuación se muestran algunos de los ejemplos de las operaciones clave con las que debe estar familiarizado. Para ver más ejemplos, visite el vínculo de GitHub que se muestra anteriormente. En los ejemplos siguientes se usa la versión asincrónica de los métodos.

CosmosClient

Crea un nuevo elemento CosmosClient con una cadena de conexión. El elemento CosmosClient es seguro para subprocesos. La recomendación es mantener una única instancia de CosmosClient por duración de la aplicación que permite una administración y un rendimiento eficaces de las conexiones.

CosmosClient client = new CosmosClient(endpoint, key);

Ejemplos de base de datos

Crear una base de datos

El método CosmosClient.CreateDatabaseAsync emite una excepción si ya existe una base de datos con el mismo nombre.

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

CosmosClient.CreateDatabaseIfNotExistsAsync comprueba si existe una base de datos y, si no, la crea. Solo se usa el elemento id de la base de datos para comprobar si hay una base de datos existente.

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

Lectura de una base de datos por identificador

Lee una base de datos del servicio Azure Cosmos DB como una operación asincrónica.

DatabaseResponse readResponse = await database.ReadAsync();

Eliminación de una base de datos

Elimina una base de datos como una operación asincrónica.

await database.DeleteAsync();

Ejemplos de contenedor

Crear un contenedor

El método Database.CreateContainerIfNotExistsAsync comprueba si existe un contenedor y, si no, lo crea. Solo se usa el elemento id del contenedor para comprobar si hay un contenedor existente.

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

Obtención de un contenedor por el identificador

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

Eliminación de un contenedor

Elimina un contenedor como una operación asincrónica.

await database.GetContainer(containerId).DeleteContainerAsync();

Ejemplos de elementos

Crear un elemento

Use el método Container.CreateItemAsync para crear un elemento. El método requiere un objeto serializable JSON que debe contener una propiedad id y un elemento partitionKey.

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

Lectura de un elemento

Use el método Container.ReadItemAsync para leer un elemento. El método requiere el tipo para serializar el elemento en junto con una propiedad id y un elemento partitionKey.

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

Consulta de un elemento

El método Container.GetItemQueryIterator crea una consulta para los elementos de un contenedor en una base de datos de Azure Cosmos mediante una instrucción SQL con valores con parámetros. Devuelve FeedIterator.

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

Otros recursos