Tutorial: Compilación de una aplicación de consola .NET para administrar datos de la cuenta de API de SQL de Azure Cosmos DBTutorial: Build a .NET console app to manage data in Azure Cosmos DB SQL API account

Le damos la bienvenida al tutorial de introducción a la API de SQL de Azure Cosmos DB.Welcome to the Azure Cosmos DB SQL API get started tutorial. Después de seguir este tutorial, tendrá una aplicación de consola que crea recursos de Azure Cosmos DB y los consulta.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

En este tutorial se usa la versión 3.0 o posterior del SDK de Azure Cosmos DB para .NET.This tutorial uses version 3.0 or later of the Azure Cosmos DB .NET SDK. Puede trabajar con .NET Framework o .NET Core.You can work with .NET Framework or .NET Core.

Esta tutorial abarca lo siguiente:This tutorial covers:

  • Creación de una cuenta de Azure Cosmos DB y conexión a ellaCreating and connecting to an Azure Cosmos account
  • Configuración del proyecto en Visual StudioConfiguring your project in Visual Studio
  • Creación de una base de datos y un contenedorCreating a database and a container
  • Adición de elementos al contenedorAdding items to the container
  • Consulta en el contenedorQuerying the container
  • Operaciones de creación, lectura, actualización y eliminación (CRUD) en el elementoPerforming create, read, update, and delete (CRUD) operations on the item
  • Eliminación de la base de datosDeleting the database

¿No tiene tiempo?Don't have time? ¡No se preocupe!Don't worry! La solución completa está disponible en GitHub.The complete solution is available on GitHub. Para obtener instrucciones rápidas, diríjase a la sección sobre cómo obtener la solución completa del tutorial.Jump to the Get the complete tutorial solution section for quick instructions.

Comencemos.Now let's get started!

Requisitos previosPrerequisites

Paso 1: Creación de una cuenta de Azure Cosmos DBStep 1: Create an Azure Cosmos DB account

Vamos a crear una cuenta de Azure Cosmos DB.Let's create an Azure Cosmos DB account. Si ya tiene una cuenta que desea usar, omita esta sección.If you already have an account you want to use, skip this section. Para usar el Emulador de Azure Cosmos DB, siga los pasos que se describen en Emulador de Azure Cosmos DB para configurarlo.To use the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator. Después, vaya al paso 2: Configuración del proyecto de Visual Studio.Then skip ahead to Step 2: Set up your Visual Studio project.

  1. Vaya a Azure Portal para crear una cuenta de Azure Cosmos DB.Go to the Azure portal to create an Azure Cosmos DB account. Busque y seleccione Azure Cosmos DB.Search for and select Azure Cosmos DB.

    El panel de las bases de datos de Azure Portal

  2. Seleccione Agregar.Select Add.

  3. En la página Creación de una cuenta de Azure Cosmos DB , especifique la configuración básica de la nueva cuenta de Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ConfiguraciónSetting ValorValue DESCRIPCIÓNDescription
    SubscriptionSubscription Nombre de la suscripciónSubscription name Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Definición de un nombre de grupo de recursosResource group name Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nombre de cuentaAccount Name Un nombre únicoA unique name Escriba un nombre para identificar la cuenta de Azure Cosmos.Enter a name to identify your Azure Cosmos account. Dado que documents.azure.com se anexa al identificador que se proporciona para crear el identificador URI, debe usar un identificador único.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    El identificador solo puede contener letras minúsculas, números y el carácter de guion (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Debe tener una longitud de entre 3 y 31 caracteres.It must be between 3-31 characters in length.
    APIAPI El tipo de cuenta que se va a crearThe type of account to create Seleccione Core(SQL) para crear una base de datos de documentos y consultarla mediante la sintaxis SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    La API determina el tipo de cuenta que se va a crear.The API determines the type of account to create. Azure Cosmos DB proporciona cinco API: Core (SQL) y MongoDB para datos de documento, Gremlin para datos de gráfico, Azure Table y Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Actualmente, debe crear una cuenta independiente para cada API.Currently, you must create a separate account for each API.

    Más información acerca de SQL API.Learn more about the SQL API.
    LocationLocation Región más cercana a los usuariosThe region closest to your users Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.Use the location that is closest to your users to give them the fastest access to the data.

    Página de la nueva cuenta de Azure Cosmos DB

  4. Seleccione Revisar + crear.Select Review + create. Puede omitir las secciones Red y Etiquetas.You can skip the Network and Tags sections.

  5. Revise la configuración de la cuenta y seleccione Crear.Review the account settings, and then select Create. La operación de creación de la cuenta tarda unos minutos.It takes a few minutes to create the account. Espere hasta que la página del portal muestre Se completó la implementación .Wait for the portal page to display Your deployment is complete.

    El panel de las notificaciones de Azure Portal

  6. Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    La página de la cuenta de Azure Cosmos DB

Paso 2: Configuración del proyecto de Visual StudioStep 2: Set up your Visual Studio project

  1. Abra Visual Studio y seleccione Crear un proyecto.Open Visual Studio and select Create a new project.

  2. En Crear un proyecto, elija Aplicación de consola (.NET Framework) para C# y seleccione Siguiente.In Create a new project, choose Console App (.NET Framework) for C#, then select Next.

  3. Asigne al proyecto el nombre CosmosGettingStartedTutorial y seleccione Crear.Name your project CosmosGettingStartedTutorial, and then select Create.

    Configuración del proyecto

  4. En el Explorador de soluciones, haga clic con el botón derecho en la nueva aplicación de consola, que se encuentra en la solución de Visual Studio y, a continuación, seleccione Administrar paquetes NuGet.In the Solution Explorer, right-click your new console application, which is under your Visual Studio solution, and select Manage NuGet Packages.

  5. En Administrador de paquetes NuGet, seleccione Examinar y busque Microsoft.Azure.Cosmos.In the NuGet Package Manager, select Browse and search for Microsoft.Azure.Cosmos. Elija Microsoft.Azure.Cosmos y seleccione Instalar.Choose Microsoft.Azure.Cosmos and select Install.

    Instalación de NuGet para el SDK de cliente de Azure Cosmos DB

    El identificador del paquete de la biblioteca de cliente de la API de SQL de Azure Cosmos DB es Microsoft Azure Cosmos DB Client Library.The package ID for the Azure Cosmos DB SQL API Client Library is Microsoft Azure Cosmos DB Client Library.

Estupendo.Great! Ahora que hemos terminado la configuración, comencemos a escribir algo de código.Now that we finished the setup, let's start writing some code. Para ver el proyecto completado de este tutorial, consulte Desarrollo de una aplicación de consola de .NET con Azure Cosmos DB.For the completed project of this tutorial, see Developing a .NET console app using Azure Cosmos DB.

Paso 3: Conexión a una cuenta de Azure Cosmos DBStep 3: Connect to an Azure Cosmos DB account

  1. Reemplace las referencias que aparecen al principio de su aplicación de C#, en el archivo Program.cs, por estas otras:Replace the references at the beginning of your C# application in the Program.cs file with these references:

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
  2. Agregue estas constantes y variables a la clase Program.Add these constants and variables into your Program class.

    public class Program
    {
        // ADD THIS PART TO YOUR CODE
    
        // The Azure Cosmos DB endpoint for running this sample.
        private static readonly string EndpointUri = "<your endpoint here>";
        // The primary key for the Azure Cosmos account.
        private static readonly string PrimaryKey = "<your primary key>";
    
        // The Cosmos client instance
        private CosmosClient cosmosClient;
    
        // The database we will create
        private Database database;
    
        // The container we will create.
        private Container container;
    
        // The name of the database and container we will create
        private string databaseId = "FamilyDatabase";
        private string containerId = "FamilyContainer";
    }
    

    Nota

    Si ya está familiarizado con la versión anterior del SDK de .NET, puede que conozca los términos colección y documento.If you're familiar with the previous version of the .NET SDK, you may be familiar with the terms collection and document. Dado que Azure Cosmos DB admite varios modelos de API, todas las versiones del SDK de .NET posteriores a la 3.0 usan los términos genéricos contenedor y elemento.Because Azure Cosmos DB supports multiple API models, version 3.0 of the .NET SDK uses the generic terms container and item. Un contenedor puede ser una colección, un grafo o una tabla.A container can be a collection, graph, or table. Un elemento puede ser un documento, un vértice o borde, o una fila, y es el contenido que hay en un contenedor.An item can be a document, edge/vertex, or row, and is the content inside a container. Para más información, consulte Trabajo con bases de datos, contenedores y elementos en Azure Cosmos DB.For more information, see Work with databases, containers, and items in Azure Cosmos DB.

  3. Abra Azure Portal.Open the Azure portal. Busque la cuenta de Azure Cosmos DB y seleccione Claves.Find your Azure Cosmos DB account, and then select Keys.

    Obtención de las claves de Azure Cosmos DB en Azure Portal

  4. En Program.cs, reemplace <your endpoint URL> por el valor de URI.In Program.cs, replace <your endpoint URL> with the value of URI. Reemplace <your primary key> por el valor de CLAVE PRINCIPAL.Replace <your primary key> with the value of PRIMARY KEY.

  5. Debajo del método Main, agregue una nueva tarea asincrónica llamada GetStartedDemoAsync, que crea una instancia del nuevo CosmosClient.Below the Main method, add a new asynchronous task called GetStartedDemoAsync, which instantiates our new CosmosClient.

    public static async Task Main(string[] args)
    {
    }
    
    // ADD THIS PART TO YOUR CODE
    /*
        Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    */
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    }
    

    GetStartedDemoAsync se usa como punto de entrada que llama a los métodos que operan en recursos de Azure Cosmos DB.We use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

  6. Agregue el código siguiente para ejecutar la tarea asincrónica GetStartedDemoAsync desde su método Main.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. El método Main detecta las excepciones y las escribe en la consola.The Main method catches exceptions and writes them to the console.

    public static async Task Main(string[] args)
    {
        try
        {
            Console.WriteLine("Beginning operations...\n");
            Program p = new Program();
            await p.GetStartedDemoAsync();
    
        }
        catch (CosmosException de)
        {
            Exception baseException = de.GetBaseException();
            Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
    
  7. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

    La consola muestra el mensaje: Final de la demo, presione cualquier tecla para salir.The console displays the message: End of demo, press any key to exit. Este mensaje confirma que la aplicación realizó una conexión con Azure Cosmos DB.This message confirms that your application made a connection to Azure Cosmos DB. A continuación, puede cerrar la ventana de consola.You can then close the console window.

Felicidades.Congratulations! Se ha conectado correctamente a una cuenta de Azure Cosmos DB.You've successfully connected to an Azure Cosmos DB account.

Paso 4: Crear una base de datosStep 4: Create a database

Una base de datos es el contenedor lógico de elementos con particiones en contenedores.A database is the logical container of items partitioned across containers. El método CreateDatabaseIfNotExistsAsync o CreateDatabaseAsync de la clase CosmosClient puede crear una base de datos.Either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync method of the CosmosClient class can create a database.

  1. Copie y pegue el método CreateDatabaseAsync debajo del método GetStartedDemoAsync.Copy and paste the CreateDatabaseAsync method below your GetStartedDemoAsync method.

    /// <summary>
    /// Create the database if it does not exist
    /// </summary>
    private async Task CreateDatabaseAsync()
    {
        // Create a new database
        this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
        Console.WriteLine("Created Database: {0}\n", this.database.Id);
    }
    

    CreateDatabaseAsync crea una nueva base de datos con el identificador FamilyDatabase, si aún no existe, utilizando el identificador especificado en el campo databaseId.CreateDatabaseAsync creates a new database with ID FamilyDatabase if it doesn't already exist, that has the ID specified from the databaseId field.

  2. Copie y pegue el código siguiente donde se crea una instancia de CosmosClient para llamar al método CreateDatabase que acaba de agregar.Copy and paste the code below where you instantiate the CosmosClient to call the CreateDatabaseAsync method you just added.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateDatabaseAsync();
    }
    

    El archivo Program.cs debe tener ahora el siguiente aspecto, con el punto de conexión y la clave principal rellenados.Your Program.cs should now look like this, with your endpoint and primary key filled in.

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
    namespace CosmosGettingStartedTutorial
    {
        class Program
        {
            // The Azure Cosmos DB endpoint for running this sample.
            private static readonly string EndpointUri = "<your endpoint here>";
            // The primary key for the Azure Cosmos account.
            private static readonly string PrimaryKey = "<your primary key>";
    
            // The Cosmos client instance
            private CosmosClient cosmosClient;
    
            // The database we will create
            private Database database;
    
            // The container we will create.
            private Container container;
    
            // The name of the database and container we will create
            private string databaseId = "FamilyDatabase";
            private string containerId = "FamilyContainer";
    
            public static async Task Main(string[] args)
            {
                try
                {
                    Console.WriteLine("Beginning operations...");
                    Program p = new Program();
                    await p.GetStartedDemoAsync();
                }
                catch (CosmosException de)
                {
                    Exception baseException = de.GetBaseException();
                    Console.WriteLine("{0} error occurred: {1}\n", de.StatusCode, de);
                }
                catch (Exception e)
                {
                    Console.WriteLine("Error: {0}\n", e);
                }
                finally
                {
                    Console.WriteLine("End of demo, press any key to exit.");
                    Console.ReadKey();
                }
            }
    
            /// <summary>
            /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
            /// </summary>
            public async Task GetStartedDemoAsync()
            {
                // Create a new instance of the Cosmos Client
                this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
                await this.CreateDatabaseAsync();
            }
    
            /// <summary>
            /// Create the database if it does not exist
            /// </summary>
            private async Task CreateDatabaseAsync()
            {
                // Create a new database
                this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
                Console.WriteLine("Created Database: {0}\n", this.database.Id);
            }
        }
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

    Nota

    Si recibe una "excepción 503 de servicio no disponible", es posible que los puertos necesarios para el modo de conexión directa estén bloqueados por un firewall.If you get a "503 service unavailable exception" error, it's possible that the required ports for direct connectivity mode are blocked by a firewall. Para corregir este problema, abra los puertos necesarios o use la conectividad del modo de puerta de enlace como se indica en el código siguiente:To fix this issue, either open the required ports or use the gateway mode connectivity as shown in the following code:

      // Create a new instance of the Cosmos Client in Gateway mode
      this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey, new CosmosClientOptions()
             {
                 ConnectionMode = ConnectionMode.Gateway
             });
    

Felicidades.Congratulations! Ha creado correctamente una base de datos de Azure Cosmos.You've successfully created an Azure Cosmos database.

Paso 5: Crear un contenedorStep 5: Create a container

Advertencia

El método CreateContainerIfNotExistsAsync crea un nuevo contenedor, lo que tiene implicaciones en el precio.The method CreateContainerIfNotExistsAsync creates a new container, which has pricing implications. Para obtener más información, visite nuestra página de precios.For more details, please visit our pricing page.

Un contenedor se puede crear con los métodos CreateContainerIfNotExistsAsync o CreateContainerAsync en la clase CosmosDatabase.A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync method in the CosmosDatabase class. Un contenedor se compone de elementos (que en el caso de SQL API son documentos JSON) y una lógica de aplicación del servidor en JavaScript asociada, como por ejemplo procedimientos almacenados, funciones definidas por el usuario y desencadenadores.A container consists of items (JSON documents if SQL API) and associated server-side application logic in JavaScript, for example, stored procedures, user-defined functions, and triggers.

  1. Copie y pegue el método CreateContainerAsync debajo del método CreateDatabaseAsync.Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. CreateContainerAsync crea un nuevo contenedor con el identificador FamilyContainer, si aún no existe, utilizando el identificador especificado en el campo containerId particionado por la propiedad LastName.CreateContainerAsync creates a new container with the ID FamilyContainer if it doesn't already exist, by using the ID specified from the containerId field partitioned by LastName property.

    /// <summary>
    /// Create the container if it does not exist. 
    /// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
    /// </summary>
    /// <returns></returns>
    private async Task CreateContainerAsync()
    {
        // Create a new container
        this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
        Console.WriteLine("Created Container: {0}\n", this.container.Id);
    }
    
  2. Copie y pegue el código siguiente donde creó una instancia de CosmosClient para llamar al método CreateContainer que acaba de agregar.Copy and paste the code below where you instantiated the CosmosClient to call the CreateContainer method you just added.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateContainerAsync();
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha creado correctamente un contenedor de Azure Cosmos.You've successfully created an Azure Cosmos container.

Paso 6: Agregar elementos al contenedorStep 6: Add items to the container

El método CreateItemAsync de la clase CosmosContainer puede crear un elemento.The CreateItemAsync method of the CosmosContainer class can create an item. Cuando se usa SQL API, los elementos se proyectan como documentos, que son contenido JSON arbitrario definido por el usuario.When using the SQL API, items are projected as documents, which are user-defined arbitrary JSON content. Ya puede insertar un elemento en el contenedor de Azure Cosmos.You can now insert an item into your Azure Cosmos container.

En primer lugar, vamos a crear una clase llamada Family que representará los objetos almacenados en Azure Cosmos DB en este ejemplo.First, let's create a Family class that represents objects stored within Azure Cosmos DB in this sample. También crearemos las subclases Parent, Child, Pet, Address que se usan en Family.We'll also create Parent, Child, Pet, Address subclasses that are used within Family. El elemento debe tener una propiedad Id serializada como id en JSON.The item must have an Id property serialized as id in JSON.

  1. Seleccione Ctrl+Mayús+A para abrir Agregar nuevo elemento.Select Ctrl+Shift+A to open Add New Item. Agregue una nueva clase Family.cs al proyecto.Add a new class Family.cs to your project.

    Captura de pantalla de la adición de una nueva clase de Family.cs al proyecto

  2. Copie y pegue las clases Family, Parent, Child, Pet y Address a Family.cs.Copy and paste the Family, Parent, Child, Pet, and Address class into Family.cs.

    using Newtonsoft.Json;
    
    namespace CosmosGettingStartedTutorial
    {
        public class Family
        {
            [JsonProperty(PropertyName = "id")]
            public string Id { get; set; }
            public string LastName { get; set; }
            public Parent[] Parents { get; set; }
            public Child[] Children { get; set; }
            public Address Address { get; set; }
            public bool IsRegistered { get; set; }
            public override string ToString()
            {
                return JsonConvert.SerializeObject(this);
            }
        }
    
        public class Parent
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
        }
    
        public class Child
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
            public string Gender { get; set; }
            public int Grade { get; set; }
            public Pet[] Pets { get; set; }
        }
    
        public class Pet
        {
            public string GivenName { get; set; }
        }
    
        public class Address
        {
            public string State { get; set; }
            public string County { get; set; }
            public string City { get; set; }
        }
    }
    
  3. De nuevo en Program.cs, agregue el método AddItemsToContainerAsync después del método CreateContainerAsync.Back in Program.cs, add the AddItemsToContainerAsync method after your CreateContainerAsync method.

    /// <summary>
    /// Add Family items to the container
    /// </summary>
    private async Task AddItemsToContainerAsync()
    {
        // Create a family object for the Andersen family
        Family andersenFamily = new Family
        {
            Id = "Andersen.1",
            LastName = "Andersen",
            Parents = new Parent[]
            {
                new Parent { FirstName = "Thomas" },
                new Parent { FirstName = "Mary Kay" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FirstName = "Henriette Thaulow",
                    Gender = "female",
                    Grade = 5,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Fluffy" }
                    }
                }
            },
            Address = new Address { State = "WA", County = "King", City = "Seattle" },
            IsRegistered = false
        };
    
        try
        {
            // Read the item to see if it exists.  
            ItemResponse<Family> andersenFamilyResponse = await this.container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
            ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
        }
    
        // Create a family object for the Wakefield family
        Family wakefieldFamily = new Family
        {
            Id = "Wakefield.7",
            LastName = "Wakefield",
            Parents = new Parent[]
            {
                new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
                new Parent { FamilyName = "Miller", FirstName = "Ben" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FamilyName = "Merriam",
                    FirstName = "Jesse",
                    Gender = "female",
                    Grade = 8,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Goofy" },
                        new Pet { GivenName = "Shadow" }
                    }
                },
                new Child
                {
                    FamilyName = "Miller",
                    FirstName = "Lisa",
                    Gender = "female",
                    Grade = 1
                }
            },
            Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
            IsRegistered = true
        };
    
        try
        {
            // Read the item to see if it exists
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>(wakefieldFamily.Id, new PartitionKey(wakefieldFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", wakefieldFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.CreateItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", wakefieldFamilyResponse.Resource.Id, wakefieldFamilyResponse.RequestCharge);
        }
    }
    

    El código comprueba que no exista un elemento con el mismo identificador.The code checks to make sure an item with the same ID doesn't already exist. Se insertan dos elementos, uno para Andersen Family y otro para Wakefield Family.We'll insert two items, one each for the Andersen Family and the Wakefield Family.

  4. Agregue una llamada a AddItemsToContainerAsync en el método GetStartedDemoAsync.Add a call to AddItemsToContainerAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.AddItemsToContainerAsync();
    }
    
  5. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha creado correctamente dos elementos de Azure Cosmos.You've successfully created two Azure Cosmos items.

Paso 7: Consulta de los recursos de Azure Cosmos DBStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB admite consultas enriquecidas en los documentos JSON que se almacenan en los contenedores.Azure Cosmos DB supports rich queries against JSON documents stored in each container. Para obtener más información, consulte Introducción a las consultas SQL.For more information, see Getting started with SQL queries. El ejemplo de código siguiente muestra cómo ejecutar una consulta en los elementos que se insertaron en el paso anterior.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Copie y pegue el método QueryItemsAsync después del método AddItemsToContainerAsync.Copy and paste the QueryItemsAsync method after your AddItemsToContainerAsync method.

    /// <summary>
    /// Run a query (using Azure Cosmos DB SQL syntax) against the container
    /// </summary>
    private async Task QueryItemsAsync()
    {
        var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";
    
        Console.WriteLine("Running query: {0}\n", sqlQueryText);
    
        QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
        FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);
    
        List<Family> families = new List<Family>();
    
        while (queryResultSetIterator.HasMoreResults)
        {
            FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
            foreach (Family family in currentResultSet)
            {
                families.Add(family);
                Console.WriteLine("\tRead {0}\n", family);
            }
        }
    }
    
  2. Agregue una llamada a QueryItemsAsync en el método GetStartedDemoAsync.Add a call to QueryItemsAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.QueryItemsAsync();
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha consultado correctamente un contenedor de Azure Cosmos.You've successfully queried an Azure Cosmos container.

Paso 8: Sustitución de un elemento JSONStep 8: Replace a JSON item

Ahora, actualizaremos un elemento en Azure Cosmos DB.Now, we'll update an item in Azure Cosmos DB. Cambiaremos la propiedad IsRegistered de Family y la propiedad Grade de uno de los elementos secundarios.We'll change the IsRegistered property of the Family and the Grade of one of the children.

  1. Copie y pegue el método ReplaceFamilyItemAsync después del método QueryItemsAsync.Copy and paste the ReplaceFamilyItemAsync method after your QueryItemsAsync method.

    /// <summary>
    /// Replace an item in the container
    /// </summary>
    private async Task ReplaceFamilyItemAsync()
    {
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
        var itemBody = wakefieldFamilyResponse.Resource;
        
        // update registration status from false to true
        itemBody.IsRegistered = true;
        // update grade of child
        itemBody.Children[0].Grade = 6;
    
        // replace the item with the updated content
        wakefieldFamilyResponse = await this.container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
        Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Resource);
    }
    
  2. Agregue una llamada a ReplaceFamilyItemAsync en el método GetStartedDemoAsync.Add a call to ReplaceFamilyItemAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.ReplaceFamilyItemAsync();
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha sustituido correctamente un elemento de Azure Cosmos.You've successfully replaced an Azure Cosmos item.

Paso 9: Eliminar elementoStep 9: Delete item

Ahora, eliminaremos un elemento en Azure Cosmos DB.Now, we'll delete an item in Azure Cosmos DB.

  1. Copie y pegue el método DeleteFamilyItemAsync después del método ReplaceFamilyItemAsync.Copy and paste the DeleteFamilyItemAsync method after your ReplaceFamilyItemAsync method.

    /// <summary>
    /// Delete an item in the container
    /// </summary>
    private async Task DeleteFamilyItemAsync()
    {
        var partitionKeyValue = "Wakefield";
        var familyId = "Wakefield.7";
    
        // Delete an item. Note we must provide the partition key value and id of the item to delete
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
        Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
    }
    
  2. Agregue una llamada a DeleteFamilyItemAsync en el método GetStartedDemoAsync.Add a call to DeleteFamilyItemAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.DeleteFamilyItemAsync();
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha eliminado correctamente un elemento de Azure Cosmos.You've successfully deleted an Azure Cosmos item.

Paso 10: Eliminación de la base de datosStep 10: Delete the database

Ahora eliminaremos nuestra base de datos.Now we'll delete our database. Al eliminar la base de datos creada, se quitan la base de datos y todos los recursos secundarios.Deleting the created database removes the database and all children resources. Los recursos incluyen contenedores, elementos y cualquier procedimiento almacenado, funciones definidas por el usuario y desencadenadores.The resources include containers, items, and any stored procedures, user-defined functions, and triggers. También eliminamos la instancia CosmosClient.We also dispose of the CosmosClient instance.

  1. Copie y pegue el método DeleteDatabaseAndCleanupAsync después del método DeleteFamilyItemAsync.Copy and paste the DeleteDatabaseAndCleanupAsync method after your DeleteFamilyItemAsync method.

    /// <summary>
    /// Delete the database and dispose of the Cosmos Client instance
    /// </summary>
    private async Task DeleteDatabaseAndCleanupAsync()
    {
        DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
        // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();
    
        Console.WriteLine("Deleted Database: {0}\n", this.databaseId);
    
        //Dispose of CosmosClient
        this.cosmosClient.Dispose();
    }
    
  2. Agregue una llamada a DeleteDatabaseAndCleanupAsync en el método GetStartedDemoAsync.Add a call to DeleteDatabaseAndCleanupAsync in the GetStartedDemoAsync method.

    /// <summary>
    /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    /// </summary>
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
        await this.DeleteFamilyItemAsync();
        await this.DeleteDatabaseAndCleanupAsync();
    }
    
  3. Presione F5 para ejecutar la aplicación.Select F5 to run your application.

Felicidades.Congratulations! Ha eliminado correctamente una base de datos de Azure Cosmos.You've successfully deleted an Azure Cosmos database.

Paso 11: Ejecutar la aplicación de consola de C#Step 11: Run your C# console application all together!

Presione F5 en Visual Studio para compilar y ejecutar la aplicación en modo de depuración.Select F5 in Visual Studio to build and run the application in debug mode.

Verá la salida de la aplicación entera en una ventana de consola.You should see the output of your entire app in a console window. La salida muestra los resultados de las consultas que hemos agregado.The output shows the results of the queries we added. Debe coincidir con el texto de ejemplo siguiente.It should match the example text below.

Beginning operations...

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.43 RUs.

Created item in database with id: Wakefield.7 Operation consumed 14.29 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"},{"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6,"Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1,"Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

Felicidades.Congratulations! Ha completado este tutorial y tiene una aplicación de consola de C# en funcionamiento.You've completed the tutorial and have a working C# console application!

Obtención de la solución completa del tutorialGet the complete tutorial solution

Puede descargar este tutorial si no tuvo tiempo para completar los pasos o simplemente desea descargar los ejemplos de código.If you didn't have time to complete the steps in this tutorial, or just want to download the code samples, you can download it.

Para compilar la solución GetStarted, necesita los siguientes requisitos previos:To build the GetStarted solution, you need the following prerequisites:

Para restaurar las referencias al SDK de Azure Cosmos DB para .NET en Visual Studio, haga clic con el botón derecho en la solución en el Explorador de soluciones y, después, seleccione Restaurar paquetes NuGet.To restore the references to the Azure Cosmos DB .NET SDK in Visual Studio, right-click the solution in Solution Explorer, and then select Restore NuGet Packages. Después, en el archivo App.config, actualice los valores de EndPointUri y PrimaryKey, tal y como se describe en el paso 3: Conexión a una cuenta de Azure Cosmos DB.Next, in the App.config file, update the EndPointUri and PrimaryKey values as described in Step 3: Connect to an Azure Cosmos DB account.

Y, eso es todo, compílelo y habrá terminado.That's it, build it, and you're on your way!

Pasos siguientesNext steps