Tutorial: Desarrollo de una aplicación de consola de .NET con Azure Cosmos DB for NoSQL

SE APLICA A: NoSQL

• .NET

El SDK de Azure para .NET permite agregar datos a una API para contenedor NoSQL, ya sean operaciones individuales asincrónicas o un lote transaccional. Este tutorial le guía por el proceso de creación de una nueva aplicación de consola de .NET que agrega varios elementos a un contenedor.

En este tutorial, aprenderá a:

• Creación de una base de datos mediante la API for NoSQL
• Creación de una aplicación de consola de .NET y adición de Azure SDK para .NET
• Adición de elementos individuales a un contenedor de API for NoSQL
• Recuperación eficaz de elementos desde un contenedor de API for NoSQL
• Creación de una transacción con cambios por lotes para el contenedor de API for NoSQL

Requisitos previos

• Una cuenta existente de Azure Cosmos DB for NoSQL.
  • Si tiene una suscripción de Azure, cree una nueva cuenta.
  • ¿No tiene una suscripción de Azure? Puede probar Azure Cosmos DB de forma gratuita, sin necesidad de usar su tarjeta de crédito.
• Visual Studio Code
• .NET 8 o posterior
• Experiencia en la escritura de aplicaciones de C#.

Creación de recursos de API for NoSQL

En primer lugar, cree una base de datos vacía en la cuenta de API for NoSQL. Más adelante, creará un contenedor mediante Azure SDK para .NET.

1. Vaya a la cuenta de API for NoSQL existente en Azure Portal.

2. En el menú de recursos, seleccione Registros.

   

3. En la página Claves, compruebe y anote el valor de los campos URI y PRIMARY KEY. Estos valores se usarán a lo largo del tutorial.

   

4. En el menú de recursos, seleccione Explorador de datos.

   

5. En la página de Data Explorer, seleccione la opción Nueva base de datos en la barra de comandos.

   

6. En el cuadro de diálogo Nueva base de datos, cree un contenedor con esta configuración:

   	Value
   Id. de base de datos	cosmicworks
   Tipo de rendimiento de la base de datos	Manual
   Cantidad de rendimiento de la base de datos	400

   

7. Para crear la base de datos, seleccione Aceptar.

Creación de una aplicación de consola de .NET

Ahora, creará una nueva aplicación de consola de .NET e importará Azure SDK para .NET mediante la biblioteca Microsoft.Azure.Cosmos de NuGet.

1. Abra un terminal en un directorio vacío.

2. Creación de una nueva aplicación de consola mediante la plantilla integrada console

   dotnet new console --langVersion preview
   

3. Agregue la versión 3.31.1-preview del paquete Microsoft.Azure.Cosmos de NuGet.

   dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview
   

4. Agregue también la versión preliminar del paquete System.CommandLine De NuGet.

   dotnet add package System.CommandLine --prerelease
   

5. Agregue también el paquete Humanizer de NuGet.

   dotnet add package Humanizer
   

6. Compile el proyecto de la aplicación de consola.

   dotnet build
   

7. Abra Visual Studio Code mediante la carpeta del proyecto actual como área de trabajo.

   Sugerencia

   Puede ejecutar code . en el terminal para abrir Visual Studio Code e iniciar automáticamente el directorio de trabajo como área de trabajo actual.

8. Vaya al archivo Program.cs y ábralo. Elimine el código existente del archivo.

9. Agregue este código al archivo para usar la biblioteca System.CommandLine y analizar la línea de comandos para dos cadenas transferidas a través de las opciones --first y --last.

   using System.CommandLine;
   
   var command = new RootCommand();
   
   var nameOption = new Option<string>("--name") { IsRequired = true };
   var emailOption = new Option<string>("--email");
   var stateOption = new Option<string>("--state") { IsRequired = true };
   var countryOption = new Option<string>("--country") { IsRequired = true };
   
   command.AddOption(nameOption);
   command.AddOption(emailOption);
   command.AddOption(stateOption);
   command.AddOption(countryOption);
   
   command.SetHandler(
       handle: CosmosHandler.ManageCustomerAsync, 
       nameOption, 
       emailOption,
       stateOption,
       countryOption
   );
   
   await command.InvokeAsync(args);
   

   Nota:

   Para este tutorial, no es fundamental conocer el funcionamiento del analizador de línea de comandos. El analizador tiene cuatro opciones que se pueden especificar cuando se ejecuta la aplicación. Tres de las opciones son necesarias, ya que se usarán para generar los campos de id. y clave de partición.

10. En este punto, el proyecto no se compilará, ya que aún no se ha definido el método estático CosmosHandler.ManageCustomerAsync.

11. Guarde el archivo Program.cs.

Adición de elementos a un contenedor mediante el SDK

A continuación, usará operaciones individuales para agregar elementos al contenedor de API for NoSQL. En esta sección, se definirá el método CosmosHandler.ManageCustomerAsync.

1. Cree un nuevo archivo CosmosHandler.cs.

2. En el archivo CosmosHandler.cs, agregue una nueva directiva con los espacios de nombres Humanizer y Microsoft.Azure.Cosmos.

   using Humanizer;
   using Microsoft.Azure.Cosmos;
   

3. Cree un nuevo método estático denominado CosmosHandler.

   public static class CosmosHandler
   { }
   

4. Con el fin de comprobar que la aplicación funciona, cree una breve implementación del método estático ManageCustomerAsync para imprimir la entrada de la línea de comandos.

   public static async Task ManageCustomerAsync(string name, string email, string state, string country)
   {
       await Console.Out.WriteLineAsync($"Hello {name} of {state}, {country}!");
   }
   

5. Guarde el archivo CosmosHandler.cs.

6. De nuevo en el terminal, ejecute la aplicación.

   dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
   

7. La salida del comando debe ser un saludo divertido.

   Hello Mica Pereira of Washington, United States!
   

8. Vuelva al archivo CosmosHandler.cs.

9. En la clase estática CosmosHandler, agregue un nuevo miembro private static readonly del tipo CosmosClient denominado _client.

   private static readonly CosmosClient _client;
   

10. Cree un nuevo constructor estático para la clase CosmosHandler.

    static CosmosHandler()
    { }
    

11. En el constructor, cree una nueva instancia de la clase CosmosClient pasando dos parámetros de cadena con los valores URI y PRIMARY KEY que registró anteriormente en el laboratorio. Almacene esta nueva instancia en el miembro _client.

    static CosmosHandler()
    {
        _client = new CosmosClient(
            accountEndpoint: "<uri>", 
            authKeyOrResourceToken: "<primary-key>"
        );
    }
    

12. De nuevo dentro de la clase estática CosmosHandler, cree un nuevo método asincrónico denominado GetContainerAsync que devuelva un valor Container.

    private static async Task<Container> GetContainerAsync()
    { }
    

13. Para los pasos siguientes, agregue este código dentro del método GetContainerAsync.

    1. Obtenga la base de datos cosmicworks y almacénela en una variable denominada database.

       Database database = _client.GetDatabase("cosmicworks");
       

    2. Cree una nueva variable List<> genérica de valores string en una lista de rutas de acceso de clave de partición jerárquica y almacénela en una variable denominada keyPaths.

       List<string> keyPaths = new()
       {
           "/address/country",
           "/address/state"
       };
       

    3. Cree una nueva variable ContainerProperties con el nombre del contenedor (customers) y la lista de rutas de acceso de clave de partición.

       ContainerProperties properties = new(
           id: "customers",
           partitionKeyPaths: keyPaths
       );
       

    4. Use el método CreateContainerIfNotExistsAsync para proporcionar las propiedades del contenedor y recuperar este. En función del nombre, este método creará de forma asincrónica el contenedor si aún no existe en la base de datos. Obtenga el resultado como la salida del método GetContainerAsync.

       return await database.CreateContainerIfNotExistsAsync(
           containerProperties: properties
       );
       

14. Elimine todo el código del método ManageCustomerAsync.

15. Para los pasos siguientes, agregue este código dentro del método ManageCustomerAsync.

    1. Llame de forma asincrónica al método GetContainerAsync y almacene el resultado en una variable denominada container.

       Container container = await GetContainerAsync();
       

    2. Cree una variable denominada id que use el método Kebaberize de Humanizer para transformar el parámetro de método name.

       string id = name.Kebaberize();
       

       Nota

       El método Kebaberize reemplazará todos los espacios por guiones y cambiará el texto a minúsculas.

    3. Cree un nuevo elemento con tipo anónimo mediante los parámetros de método name, statey country, junto con la variable id. Almacene el elemento como una variable denominada customer.

       var customer = new {
           id = id,
           name = name,
           address = new {
               state = state,
               country = country
           }
       };
       

    4. Use el método asincrónico CreateItemAsync del contenedor para crear un nuevo elemento en el contenedor y asignar los metadatos de respuesta HTTP a una variable denominada response.

       var response = await container.CreateItemAsync(customer);
       

    5. Escriba los valores de las propiedades StatusCode y RequestCharge de la variable response en la consola. Escriba también el valor de la variable id.

       Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
       

16. Guarde el archivo CosmosHandler.cs.

17. De nuevo en el terminal, vuelva a ejecutar la aplicación.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
    

18. La salida del comando deberá incluir un estado y un cargo asociado a la solicitud para la operación.

    [Created]       mica-pereira    7.05 RUs
    

    Nota

    El cargo asociado a la solicitud puede variar.

19. Ejecute la aplicación una vez más.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
    

20. Esta vez, el programa debería bloquearse. Si se desplaza por el mensaje de error, verá que el bloqueo se produjo debido a un conflicto en el identificador único de los elementos.

    Unhandled exception: Microsoft.Azure.Cosmos.CosmosException : Response status code does not indicate success: Conflict (409);Reason: (
        Errors : [
          "Resource with specified id or name already exists."
        ]
    );
    

Recuperación de un elemento mediante el SDK

Una vez que se ha creado el primer elemento en el contenedor, podrá usar el mismo SDK para recuperar el elemento. Consulte aquí el elemento para comparar la diferencia en el consumo de unidades de solicitud (RU).

1. Vuelva al archivo CosmosHandler.cs o ábralo.

2. Elimine todas las líneas de código del método ManageCustomerAsync, salvo por las dos primeras líneas.

   public static async Task ManageCustomerAsync(string name, string email, string state, string country)
   {
       Container container = await GetContainerAsync();
   
       string id = name.Kebaberize();
   }
   

3. Para los pasos siguientes, agregue este código dentro del método ManageCustomerAsync.

   1. Use el método asincrónico CreateItemAsync del contenedor para crear un nuevo elemento en el contenedor y asignar los metadatos de respuesta HTTP a una variable denominada response.

      var response = await container.CreateItemAsync(customer);
      

   2. Cree una nueva cadena denominada sql con una consulta SQL para recuperar elementos en los que coincida un filtro (@id).

      string sql = @"
      SELECT
          *
      FROM customers c
      WHERE c.id = @id
      ";
      

   3. Cree una nueva variable QueryDefinition denominada query que pase la cadena sql como el único parámetro de consulta. Además, use el método fluid WithParameter para aplicar el valor de la variable id al parámetro @id.

      var query = new QueryDefinition(
          query: sql
      )
          .WithParameter("@id", id);
      

   4. Use el método genérico GetItemQueryIterator<> y la variable query para crear un iterador que obtenga datos de Azure Cosmos DB. Almacene el elemento como una variable denominada feed. Encapsule esta expresión completa en una instrucción using para desechar el iterador más adelante.

      using var feed = container.GetItemQueryIterator<dynamic>(
          queryDefinition: query
      );
      

   5. Llame de forma asincrónica al método ReadNextAsync de la variable feed y almacene el resultado en una variable denominada response.

      var response = await feed.ReadNextAsync();
      

   6. Escriba los valores de las propiedades StatusCode y RequestCharge de la variable response en la consola. Escriba también el valor de la variable id.

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
      

4. Guarde el archivo CosmosHandler.cs.

5. De nuevo en el terminal, ejecute la aplicación para leer el elemento único mediante una consulta SQL.

   dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
   

6. La salida del comando debe indicar que la consulta requería varias unidades de solicitud (RU).

   [OK]    mica-pereira    2.82 RUs
   

7. De nuevo en el archivo CosmosHandler.cs, vuelva a eliminar todas las líneas de código del método ManageCustomerAsync, salvo por las dos primeras líneas.

   public static async Task ManageCustomerAsync(string name, string email, string state, string country)
   {
       Container container = await GetContainerAsync();
   
       string id = name.Kebaberize();
   }
   

8. Para los pasos siguientes, agregue este código dentro del método ManageCustomerAsync.

   1. Cree una nueva instancia de PartitionKeyBuilder agregando los parámetros state y country como un valor de clave de partición de varias partes.

      var partitionKey = new PartitionKeyBuilder()
          .Add(country)
          .Add(state)
          .Build();
      

   2. Use el método ReadItemAsync<> del contenedor para leer el elemento del contenedor mediante las variables id y partitionKey. Guarde el resultado en una variable denominada response.

      var response = await container.ReadItemAsync<dynamic>(
          id: id, 
          partitionKey: partitionKey
      );
      

   3. Escriba los valores de las propiedades StatusCode y RequestCharge de la variable response en la consola. Escriba también el valor de la variable id.

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");
      

9. Vuelva a guardar el archivo CosmosHandler.cs.

10. De nuevo en el terminal, ejecute la aplicación una vez más para que lea el elemento único.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
    

11. La salida del comando debería indicar que la consulta requería una única RU.

    [OK]    mica-pereira    1 RUs
    

Creación de una transacción con el SDK

Por último, seleccionará el elemento que creó, lo leerá y creará un elemento relacionado diferente como parte de una sola transacción mediante Azure SDK para .NET.

1. Vuelva al archivo CosmosHandler.cs o ábralo.

2. Elimine estas líneas de código del método ManageCustomerAsync.

   var response = await container.ReadItemAsync<dynamic>(
       id: id, 
       partitionKey: partitionKey
   );
   
   Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
   

3. Para los pasos siguientes, agregue este nuevo código dentro del método ManageCustomerAsync.

   1. Cree un nuevo elemento con tipo anónimo mediante los parámetros de método name, statey country, junto con la variable id. Almacene el elemento como una variable denominada customerCart. Este elemento representa un carro de la compra en tiempo real para el cliente que está vacío actualmente.

      var customerCart = new {
          id = $"{Guid.NewGuid()}",
          customerId = id,
          items = new string[] {},
          address = new {
              state = state,
              country = country
          }
      };
      

   2. Cree otro nuevo elemento de tipo anónimo mediante los parámetros de método name, statey country, y la variable id. Almacene el elemento como una variable denominada customerCart. Este elemento representa la información de envío y contacto del cliente.

      var customerContactInfo = new {
          id = $"{id}-contact",
          customerId = id,
          email = email,
          location = $"{state}, {country}",
          address = new {
              state = state,
              country = country
          }
      };
      

   3. Cree un nuevo lote mediante el método CreateTransactionalBatch del contenedor pasando la variable partitionKey. Almacene el lote como una variable denominada batch. Use métodos fluidos para realizar las siguientes acciones:

      Método	Parámetro
      ReadItem	variable de cadena id
      CreateItem	variable de tipo anónimo customerCart
      CreateItem	variable de tipo anónimo customerContactInfo

      var batch = container.CreateTransactionalBatch(partitionKey)
          .ReadItem(id)
          .CreateItem(customerCart)
          .CreateItem(customerContactInfo);
      

   4. Use el método ExecuteAsync del lote para iniciar la transacción. Guarde el resultado en una variable denominada response.

      using var response = await batch.ExecuteAsync();
      

   5. Escriba los valores de las propiedades StatusCode y RequestCharge de la variable response en la consola. Escriba también el valor de la variable id.

      Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");
      

4. Vuelva a guardar el archivo CosmosHandler.cs.

5. De nuevo en el terminal, ejecute la aplicación una vez más para que lea el elemento único.

   dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
   

6. La salida del comando debe mostrar las unidades de solicitud usadas para toda la transacción.

   [OK]    16.05 RUs
   

   Nota

   El cargo asociado a la solicitud puede variar.

Validación de los datos finales en Data Explorer

En resumen, usará Data Explorer en Azure Portal para ver los datos y el contenedor que creó en este tutorial.

1. Vaya a la cuenta de API for NoSQL en Azure Portal.

2. En el menú de recursos, seleccione Explorador de datos.

   

3. En la página de Data Explorer, expanda la base de datos cosmicworks y seleccione el contenedor customers.

   

4. En la barra de comandos, seleccione New SQL query.

   

5. En el editor de consultas, fíjese en esta cadena de consulta SQL.

   SELECT * FROM c
   

6. Seleccione Ejecutar consulta para efectuar la consulta y ver los resultados.

   

7. Los resultados deben incluir una matriz JSON con tres elementos creados en este tutorial. Observe que todos los elementos tienen el mismo valor de clave de partición jerárquica, pero campos de identificador únicos. La salida de ejemplo incluida se ha acortado para mayor brevedad.

   [
     {
       "id": "mica-pereira",
       "name": "Mica Pereira",
       "address": {
         "state": "Washington",
         "country": "United States"
       },
       ...
     },
     {
       "id": "33d03318-6302-4559-b5c0-f3cc643b2f38",
       "customerId": "mica-pereira",
       "items": [],
       "address": {
         "state": "Washington",
         "country": "United States"
       },
       ...
     },
     {
       "id": "mica-pereira-contact",
       "customerId": "mica-pereira",
       "email": null,
       "location": "Washington, United States",
       "address": {
         "state": "Washington",
         "country": "United States"
       },
       ...
     }
   ]
   

Limpieza de recursos

Elimine los recursos que utilizados en este artículo cuando ya no se necesiten. Para ello, vaya a la página de la cuenta, seleccione Data Explorer, la cosmicworks base de datos y Eliminar.