Créer une application console .NET pour gérer des données dans le compte de l’API SQL Azure Cosmos DB (kit SDK Version 3 - préversion)Build a .NET console app to manage data in Azure Cosmos DB SQL API account (SDK Version 3 Preview)

Bienvenue dans le didacticiel sur la prise en main de l’API SQL Azure Cosmos DB !Welcome to the Azure Cosmos DB SQL API getting started tutorial! À la fin de ce didacticiel, vous disposerez d’une application de console qui crée et interroge des ressources Azure Cosmos DB.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources. Ce tutoriel utilise la version 3.0+ du kit SDK .NET Azure Cosmos DB, qui cible .NET Standard 2.0.This tutorial uses Version 3.0+ of the Azure Cosmos DB .NET SDK, which targets .NET Standard 2.0.

Ce didacticiel contient les sections suivantes :This tutorial covers:

  • Création et connexion à un compte Azure CosmosCreating and connecting to an Azure Cosmos account
  • Configuration de votre projet dans Visual StudioConfiguring your project in Visual Studio
  • Création d’une base de données et d’un conteneurCreating a database and a container
  • Ajout d’éléments au conteneurAdding items to the container
  • Interrogation du conteneurQuerying the container
  • Opérations CRUD sur l’élémentCRUD operations on the item
  • Suppression de la base de donnéesDeleting the database

Vous n’avez pas le temps ?Don't have time? Ne vous inquiétez pas !Don't worry! La solution complète est disponible sur GitHub.The complete solution is available on GitHub. Pour obtenir des instructions rapides, allez à la section Obtenir la solution complète du tutoriel.Jump to the Get the complete tutorial solution section for quick instructions.

Commençons dès maintenant !Now let's get started!

PrérequisPrerequisites

Étape 1 : Création d’un compte Azure Cosmos DBStep 1: Create an Azure Cosmos DB account

Commençons par créer un compte Azure Cosmos DB.Let's create an Azure Cosmos DB account. Si vous avez déjà un compte que vous souhaitez utiliser, vous pouvez passer directement à l’étape Configurer votre solution Visual Studio.If you already have an account you want to use, you can skip ahead to Setup your Visual Studio Solution. Si vous utilisez l’émulateur Azure Cosmos DB, suivez les étapes de la section Émulateur Azure Cosmos DB pour le configurer, puis passez directement à l’étape Configurer votre projet Visual Studio.If you are using the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to setup the emulator and skip ahead to Setup your Visual Studio project.

  1. Dans une nouvelle fenêtre du navigateur, connectez-vous au portail Azure.In a new browser window, sign in to the Azure portal.
  2. Cliquez sur Créer une ressource > Bases de données > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Volet Bases de données du portail Azure

  3. Dans la page Créer un compte Azure Cosmos DB, entrez les paramètres du nouveau compte Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ParamètreSetting ValeurValue DescriptionDescription
    AbonnementSubscription Votre abonnementYour subscription Sélectionnez l’abonnement Azure que vous souhaitez utiliser pour ce compte Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Groupe de ressourcesResource Group CréationCreate new

    Entrez un nom uniqueEnter a unique name
    Sélectionnez Créer, puis entrez le nom du nouveau groupe de ressources pour votre compte.Select Create New, then enter a new resource-group name for your account. Pour plus de simplicité, vous pouvez utiliser votre nom de compte.For simplicity, you can use the same name as your Account Name.
    Nom du compteAccount Name Entrez un nom uniqueEnter a unique name Entrez un nom unique pour identifier votre compte Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Étant donné que documents.azure.com est ajouté à l’ID que vous fournissez pour créer votre URI, utilisez un ID unique.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    L’ID ne peut contenir que des lettres minuscules, des chiffres et le caractère de trait d’union (-), et doit comporter entre 3 et 31 caractères.The ID can only contain lowercase letters, numbers, and the hyphen (-) character, and it must be between 3 and 31 characters in length..
    APIAPI Core (SQL)Core (SQL) L’API détermine le type de compte à créer.The API determines the type of account to create. Azure Cosmos DB fournit cinq API : SQL (base de données orientée document), Gremlin (base de données de graphe), MongoDB (base de données de document), API Table et API Cassandra.Azure Cosmos DB provides five APIs: SQL (document database), Gremlin (graph database), MongoDB (document database), Table API, and Cassandra API. Pour chaque API, vous devez créer un compte distinct.Each API currently requires you to create a separate account.

    Sélectionnez Core (SQL), car dans cet article, vous allez créer une base de données de documents et faire des requêtes avec une syntaxe SQL.Select Core (SQL) because in this article you will create a document database and query using SQL syntax.

    En savoir plus sur l’API SQLLearn more about the SQL API
    LieuLocation Sélectionner la région la plus proche de vos utilisateursSelect the region closest to your users Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Utilisez l’emplacement le plus proche de vos utilisateurs, pour leur donner l’accès le plus rapide possible aux données.Use the location that's closest to your users to give them the fastest access to the data.
    Activer la géoredondanceEnable geo-redundancy Laisser videLeave blank Ceci crée une version répliquée de votre base de données dans une seconde région (appairée).This creates a replicated version of your database in a second (paired) region. Laissez ce champ vide.Leave this blank.
    Écritures multirégionsMulti-region writes Laisser videLeave blank Ce paramètre permet de rendre vos régions de base de données accessibles en lecture et en écriture.This enables each of your database regions to be both a read and write region. Laissez ce champ vide.Leave this blank.

    Puis, cliquez sur Vérifier + créer.Then click Review + create. Vous pouvez ignorer les sections Réseau et Balises.You can skip the Network and Tags section.

    Page de nouveau compte pour Azure Cosmos DB

    Examinez les informations récapitulatives et cliquez sur Créer.Review the summary information and click Create.

    Page résumée de vérification de compte

  4. La création du compte prend quelques minutes.The account creation takes a few minutes. Attendez que le portail affiche le message Votre déploiement a été effectué et cliquez sur Accéder à la ressource.Wait for the portal to display the Your deployment is complete message and click Go to resource.

    Page indiquant que le compte été créé correctement

  5. Le portail affiche maintenant la page Félicitations ! Votre compte Azure Cosmos DB a été créé.The portal will now display the Congratulations! Your Azure Cosmos DB account was created page.

    Volet Notifications du portail Azure

Étape 2 : Configurer votre projet Visual StudioStep 2: Setup your Visual Studio project

  1. Ouvrez Visual Studio 2017 sur votre ordinateur.Open Visual Studio 2017 on your computer.
  2. Dans le menu Fichier, sélectionnez Nouveau, puis choisissez Projet.On the File menu, select New, and then choose Project.
  3. Dans la boîte de dialogue Nouveau projet, sélectionnez Visual C# / Application console (.NET Framework), donnez un nom à votre projet, puis cliquez sur OK.In the New Project dialog, select Visual C# / Console App (.NET Framework), name your project, and then click OK. Capture d’écran de la fenêtre Nouveau projetScreen shot of the New Project window
  4. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur votre nouvelle application console, qui se trouve sous votre solution Visual Studio, puis cliquez sur Gérer les packages NuGet…In the Solution Explorer, right click on your new console application, which is under your Visual Studio solution, and then click Manage NuGet Packages...

    Capture d'écran du menu du clic droit pour le projet

  5. Dans l’onglet NuGet, cliquez sur Parcourir et tapez Microsoft.Azure.Cosmos dans la zone de recherche.In the NuGet tab, click Browse, and type Microsoft.Azure.Cosmos in the search box. Assurez-vous de cocher Inclure la préversion pour obtenir la préversion.Be sure to check Include prelease to find the preview.
  6. Dans les résultats, trouvez Microsoft.Azure.Cosmos et cliquez sur Installer.Within the results, find Microsoft.Azure.Cosmos and click Install. L’ID de package de la bibliothèque cliente d’API SQL Azure Cosmos DB est 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. Capture d’écran du menu NuGet pour la recherche du Kit de développement logiciel (SDK) client Azure Cosmos DBScreen shot of the NuGet Menu for finding Azure Cosmos DB Client SDK

    Si vous obtenez un message concernant la vérification des modifications apportées à la solution, cliquez sur OK.If you get a message about reviewing changes to the solution, click OK. Si vous obtenez un message concernant l’acceptation de la licence, cliquez sur J’accepte.If you get a message about license acceptance, click I accept.

Parfait !Great! L’installation étant terminée, nous pouvons passer à l’écriture du code.Now that we finished the setup, let's start writing some code. Vous trouverez le projet de code complet de ce didacticiel dans GitHub.You can find a completed code project of this tutorial at GitHub.

Étape 3 : Se connecter à un compte Azure Cosmos DBStep 3: Connect to an Azure Cosmos DB account

  1. Remplacez tout d’abord les références situées au début de votre application C#, dans le fichier Program.cs, par ces références :First, replace the references at the beginning of your C# application, in the Program.cs file with these references: csharp using System; using System.Threading.Tasks; using System.Configuration; using Microsoft.Azure.Cosmos; using System.Collections.Generic; using System.Net;
  2. À présent, ajoutez ces variables et ces constantes dans votre classe publique Program.Now, add these constants and variables into your public class Program.

    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 CosmosDatabase database;
    
        // The container we will create.
        private CosmosContainer container;
    
        // The name of the database and container we will create
        private string databaseId = "FamilyDatabase";
        private string containerId = "FamilyContainer";
    }
    

    Notez que si vous avez déjà utilisé la version précédente du kit SDK .NET, vous connaissez peut-être les termes « collection » et « document ».Note, if you are familiar with the previous version of the .NET SDK, you may be used to seeing the terms 'collection' and 'document.' Étant donné qu’Azure Cosmos DB prend en charge plusieurs modèles d’API, les versions postérieures à la version 3.0 du kit SDK .NET utilisent les termes génériques « conteneur » et « élément ».Because Azure Cosmos DB supports multiple API models, version 3.0+ of the .NET SDK uses the generic terms 'container' and 'item.' Un conteneur peut être une collection, un graphique ou une table.A container can be a collection, graph, or table. Un élément peut être un document, arête/sommet ou ligne, et correspond au contenu à l’intérieur d’un conteneur.An item can be a document, edge/vertex, or row, and is the content inside a container. En savoir plus sur les bases de données, les conteneurs et les éléments.Learn more about databases, containers, and items.

  3. Récupérez l’URL du point de terminaison et la clé primaire à partir du portail Azure.Retrieve your endpoint URL and primary key from the Azure portal.

    Dans le portail Azure, accédez à votre compte Azure Cosmos DB, puis cliquez sur Clés.In the Azure portal, navigate to your Azure Cosmos DB account, and then click Keys.

    Copiez l’URI à partir du portail et collez-le dans <your endpoint URL> dans le fichier Program.cs.Copy the URI from the portal and paste it into <your endpoint URL> in the Program.cs file. Copiez la CLÉ PRIMAIRE à partir du portail, puis collez-la dans <your primary key>.Copy the PRIMARY KEY from the portal and paste it into <your primary key>.

    Capture d’écran de l’obtention des clés Azure Cosmos DB depuis le portail Azure

  4. Ensuite, nous allons créer une nouvelle instance de CosmosClient et configurer une génération de modèles automatique pour notre programme.Next, we'll create a new instance of CosmosClient and set up some scaffolding for our program.

    Sous la méthode Main, ajoutez une nouvelle tâche asynchrone appelée GetStartedDemoAsync qui va instancier notre nouveau CosmosClient.Below the Main method, add a new asynchronous task called GetStartedDemoAsync, which will instantiate our new CosmosClient. Nous allons utiliser GetStartedDemoAsync comme point d’entrée appelant les méthodes qui opèrent sur les ressources Azure Cosmos DB.We will use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

    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);
    }
    
  5. Ajoutez le code suivant pour exécuter la tâche asynchrone GetStartedDemoAsync à partir de la méthode Main.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. La méthode Main va intercepter les exceptions et les consigner dans la console.The Main method will catch exceptions and write them to the console.

    public static async Task Main(string[] args)
    {
        // ADD THIS PART TO YOUR CODE
        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}\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();
        }
    }
    
  6. Sélectionnez F5 pour exécuter votre application.Select F5 to run your application. La sortie de la fenêtre de console affiche le message End of demo, press any key to exit. qui confirme que la connexion à Azure Cosmos DB a été établie.The console window output displays the message End of demo, press any key to exit. confirming that the connection to Azure Cosmos DB was made. Vous pouvez alors fermer la fenêtre de console.You can then close the console window.

Félicitations !Congratulations! Vous avez établi une connexion à un compte de base de données Azure Cosmos DB.You have successfully connected to an Azure Cosmos DB account.

Étape 4 : Créer une base de donnéesStep 4: Create a database

Vous pouvez créer une base de données à l’aide de la fonction CreateDatabaseIfNotExistsAsync ou CreateDatabaseAsync de la classe CosmosDatabases.A database can be created by using either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync function of the CosmosDatabases class. Une base de données est le conteneur logique d’éléments partitionnés entre les conteneurs.A database is the logical container of items partitioned across containers.

  1. Copiez et collez la méthode CreateDatabase sous votre méthode GetStartedDemoAsync.Copy and paste the CreateDatabase method below your GetStartedDemoAsync method. CreateDatabase crée une base de données avec l’ID FamilyDatabase s’il n’existe pas déjà, sinon avec l’ID spécifié dans le champ databaseId.CreateDatabase will create a new database with id FamilyDatabase if it does not already exist, with the id specified from the databaseId field.

    /*
        Create the database if it does not exist
    */    
    private async Task CreateDatabase()
    {
        // Create a new database
        this.database = await this.cosmosClient.Databases.CreateDatabaseIfNotExistsAsync(databaseId);
        Console.WriteLine("Created Database: {0}\n", this.database.Id);
    }
    
  2. Copiez et collez le code ci-dessous, dans lequel vous avez instancié le CosmosClient pour qu’il appelle la méthode CreateDatabase que vous venez d’ajouter.Copy and paste the code below where you instantiated the CosmosClient to call the CreateDatabase 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.CreateDatabase(); 
    }
    

    À ce stade, votre code doit désormais ressembler à ceci, avec vos point de terminaison et clé primaire renseignés.At this point, your code should now look like this, with your endpoint and primary key filled in.

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using Microsoft.Azure.Cosmos;
    using System.Collections.Generic;
    using System.Net;
    
    namespace CosmosGettingStarted
    {
        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 CosmosDatabase database;
    
            // The container we will create.
            private CosmosContainer 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();
                }
            }
    
            /*
                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);
                await this.CreateDatabase();
            }
    
            /*
                Create the database if it does not exist
            */    
            private async Task CreateDatabase()
            {
                // Create a new database
                this.database = await this.cosmosClient.Databases.CreateDatabaseIfNotExistsAsync(databaseId);
                Console.WriteLine("Created Database: {0}\n", this.database.Id);
            }
        }
    }
    

Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez créé une base de données Azure Cosmos DB.You have successfully created an Azure Cosmos DB database.

Étape 5 : Créez un conteneur.Step 5: Create a container

Avertissement

L’appel de la méthode CreateContainerIfNotExistsAsync crée un conteneur, ce qui a une incidence sur la tarification.Calling the method CreateContainerIfNotExistsAsync will create a new container, which has pricing implications. Pour plus d'informations, visitez notre page de tarification.For more details, please visit our pricing page.

Vous pouvez créer un conteneur en utilisant la fonction CreateContainerIfNotExistsAsync ou CreateContainerAsync dans la classe CosmosContainers.A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync function in the CosmosContainers class. Un conteneur est composé d’éléments (des documents JSON dans le cas de l’API SQL) et d’une logique d’application côté serveur JavaScript associée, par exemple des procédures stockées, des fonctions définies par l’utilisateur et des déclencheurs.A container consists of items (which in the case of the SQL API is JSON documents) and associated JavaScript server-side application logic, e.g. stored procedures, user-defined functions, and triggers.

  1. Copiez et collez la méthode CreateContainer sous votre méthode CreateDatabase.Copy and paste the CreateContainer method below your CreateDatabase method. CreateContainer crée un conteneur avec l’ID FamilyContainer s’il n’existe pas déjà, sinon avec l’ID spécifié dans le champ containerId.CreateContainer will create a new container with id FamilyContainer if it does not already exist, with the id specified from the containerId field.

    /*
        Create the container if it does not exist. 
        Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
    */
    private async Task CreateContainer()
    {
        // Create a new container
        this.container = await this.database.Containers.CreateContainerIfNotExistsAsync(containerId, "/LastName");
        Console.WriteLine("Created Container: {0}\n", this.container.Id);
    }
    
  2. Copiez et collez le code ci-dessous, dans lequel vous avez instancié le CosmosClient pour qu’il appelle la méthode CreateContainer que vous venez d’ajouter.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.CreateDatabase(); 
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateContainer();
    }
    

    Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez créé un conteneur Azure Cosmos DB.You have successfully created an Azure Cosmos DB container.

Étape 6 : Ajouter des éléments au conteneurStep 6: Add items to the container

Un élément peut être créé à l’aide de la fonction CreateItemAsync de la classe CosmosItems.An item can be created by using the CreateItemAsync function of the CosmosItems class. Lorsque vous utilisez l’API SQL, les éléments sont projetés sous forme de documents, à savoir du contenu JSON (arbitraire) défini par l’utilisateur.When using the SQL API, items are projected as documents, which are user-defined (arbitrary) JSON content. Vous pouvez maintenant insérer un élément dans votre conteneur Azure Cosmos DB.You can now insert an item into your Azure Cosmos DB container.

Nous devons tout d’abord créer une classe Family représentant les objets stockés dans Azure Cosmos DB dans cet exemple.First, we need to create a Family class that will represent objects stored within Azure Cosmos DB in this sample. Nous allons également créer les sous-classes Parent, Child, Pet et Address qui seront utilisées dans Family.We will also create Parent, Child, Pet, Address subclasses that are used within Family. Notez que les documents doivent avoir une propriété Id sérialisée comme id dans JSON.Note that documents must have an Id property serialized as id in JSON.

  1. Appuyez sur Ctrl + Maj + A pour afficher la boîte de dialogue Ajouter un nouvel élément.Select Ctrl+Shift+A to open the Add New Item dialog. Ajoutez une nouvelle classe Family.cs à votre projet.Add a new class Family.cs to your project.

    Capture d’écran de l’ajout d’une nouvelle classe Family.cs dans le projet

  2. Copiez et collez les classes Family, Parent, Child, Pet et Address dans Family.cs.Copy and paste the Family, Parent, Child, Pet, and Address class into Family.cs.

    using Newtonsoft.Json;
    
    namespace CosmosGettingStarted
    {
        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. Revenez à Program.cs et ajoutez la méthode AddItemsToContainer sous votre méthode CreateContainer.Navigate back to Program.cs and add the AddItemsToContainer method under your CreateContainer method. Le code procède à une vérification pour s’assurer qu’un élément doté du même ID n’existe pas déjà avant qu’il le crée.The code checks to make sure an item with the same id does not already exist before creating it. Nous allons insérer ensuite deux éléments, un pour la famille Andersen, l’autre pour la famille Wakefield.We will insert two items, one each for the Andersen Family and the Wakefield Family.

    /*
        Add Family items to the container
    */
    private async Task AddItemsToContainer()
    {
        // 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 = true
        };
    
        // Read the item to see if it exists. Note ReadItemAsync will not throw an exception if an item does not exist. Instead, we check the StatusCode property off the response object. 
        CosmosItemResponse<Family> andersenFamilyResponse = await this.container.Items.ReadItemAsync<Family>(andersenFamily.LastName, andersenFamily.Id);
    
        if (andersenFamilyResponse.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"
            andersenFamilyResponse = await this.container.Items.CreateItemAsync<Family>(andersenFamily.LastName, andersenFamily);
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the CosmosItemResponse. 
            //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);
        }
        else
        {
            Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Resource.Id);
        }
    
        // 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 = false
        };
    
        // Read the item to see if it exists
        CosmosItemResponse<Family> wakefieldFamilyResponse = await this.container.Items.ReadItemAsync<Family>(wakefieldFamily.LastName, wakefieldFamily.Id);
    
        if (wakefieldFamilyResponse.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"
            wakefieldFamilyResponse = await this.container.Items.CreateItemAsync<Family>(wakefieldFamily.LastName, wakefieldFamily);
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the CosmosItemResponse. 
            //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);
        }
        else
        {
            Console.WriteLine("Item in database with id: {0} already exists\n", wakefieldFamilyResponse.Resource.Id);
        }
    }
    
  4. Ajoutez un appel à AddItemsToContainer dans la méthode GetStartedDemoAsync.Add a call to AddItemsToContainer in the GetStartedDemoAsync method.

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

Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez créé deux éléments Azure Cosmos DB.You have successfully created two Azure Cosmos DB items.

Étape 7 : Interroger les ressources Azure Cosmos DBStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB prend en charge les requêtes enrichies sur les documents JSON stockés dans chaque collection.Azure Cosmos DB supports rich queries against JSON documents stored in each collection. L’exemple de code suivant montre comment exécuter une requête sur les éléments que nous avons insérés à l’étape précédente.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Copiez et collez la méthode RunQuery sous votre méthode AddItemsToContainer.Copy and paste the RunQuery method below your AddItemsToContainer method.

    /*
        Run a query (using Azure Cosmos DB SQL syntax) against the container
    */
    private async Task RunQuery()
    {
        var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";
        var partitionKeyValue = "Andersen";
    
        Console.WriteLine("Running query: {0}\n", sqlQueryText);
    
        CosmosSqlQueryDefinition queryDefinition = new CosmosSqlQueryDefinition(sqlQueryText);
        CosmosResultSetIterator<Family> queryResultSetIterator = this.container.Items.CreateItemQuery<Family>(queryDefinition, partitionKeyValue);
    
        List<Family> families = new List<Family>();
    
        while (queryResultSetIterator.HasMoreResults)
        {
            CosmosQueryResponse<Family> currentResultSet = await queryResultSetIterator.FetchNextSetAsync();
            foreach (Family family in currentResultSet)
            {
                families.Add(family);
                Console.WriteLine("\tRead {0}\n", family);
            }
        }
    }
    
  2. Ajoutez un appel à RunQuery dans la méthode GetStartedDemoAsync.Add a call to RunQuery in the GetStartedDemoAsync method.

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

Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez interrogé un conteneur Azure Cosmos DB.You have successfully queried against an Azure Cosmos DB container.

Étape 8 : Remplacer un élément JSONStep 8: Replace a JSON item

À présent, nous allons mettre à jour un élément dans Azure Cosmos DB.Now, we will update an item in Azure Cosmos DB.

  1. Copiez et collez la méthode ReplaceFamilyItem sous votre méthode RunQuery.Copy and paste the ReplaceFamilyItem method below your RunQuery method. Notez que nous modifions deux propriétés, IsRegistered de la famille, et Grade de l’un des enfants.Note we are changing the IsRegistered property of the Family and the Grade of one of the children.

    /*
    Update an item in the container
    */
    private async Task ReplaceFamilyItem()
    {
        CosmosItemResponse<Family> wakefieldFamilyResponse = await this.container.Items.ReadItemAsync<Family>("Wakefield", "Wakefield.7");
        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.Items.ReplaceItemAsync<Family>(itemBody.LastName, itemBody.Id, itemBody);
        Console.WriteLine("Updated Family [{0},{1}]\n. Body is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Resource);
    }
    
  2. Ajoutez un appel à ReplaceFamilyItem dans la méthode GetStartedDemo.Add a call to ReplaceFamilyItem in the GetStartedDemo method.

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

    Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez remplacé un élément Azure Cosmos DB.You have successfully replaced an Azure Cosmos DB item.

Étape 9 : Delete item (Supprimer un élément)Step 9: Delete item

À présent, nous allons supprimer un élément dans Azure Cosmos DB.Now, we will delete an item in Azure Cosmos DB.

  1. Copiez et collez la méthode DeleteFamilyItem sous votre méthode ReplaceFamilyItem.Copy and paste the DeleteFamilyItem method below your ReplaceFamilyItem method.

    /*
    Delete an item in the container
    */
    private async Task DeleteFamilyItem()
    {
        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
        CosmosItemResponse<Family> wakefieldFamilyResponse = await this.container.Items.DeleteItemAsync<Family>(partitionKeyValue, familyId);
        Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
    }
    
  2. Ajoutez un appel à DeleteFamilyItem dans la méthode GetStartedDemo.Add a call to DeleteFamilyItem in the GetStartedDemo method.

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

Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez supprimé un élément Azure Cosmos DB.You have successfully deleted an Azure Cosmos DB item.

Étape 10 : Supprimer la base de donnéesStep 10: Delete the database

Maintenant, nous allons supprimer notre base de données.Now we will delete our database. Supprimer la base de données créée revient à supprimer la base de données et toutes les ressources enfants (conteneurs, éléments, procédures stockées, fonctions définies par l’utilisateur et déclencheurs).Deleting the created database will remove the database and all children resources (containers, items, and any stored procedures, user-defined functions, and triggers). Nous allons également supprimer l’instance CosmosClient.We will also dispose of the CosmosClient instance.

  1. Copiez et collez la méthode DeleteDatabaseAndCleanup sous votre méthode DeleteFamilyItem.Copy and paste the DeleteDatabaseAndCleanup method below your DeleteFamilyItem method.

    /*
    Delete the database and dispose of the Cosmos Client instance
    */
    private async Task DeleteDatabaseAndCleanup()
    {
        CosmosDatabaseResponse 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. Ajoutez un appel à DeleteDatabaseAndCleanup dans la méthode GetStartedDemo.Add a call to DeleteDatabaseAndCleanup in the GetStartedDemo method.

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

Sélectionnez F5 pour exécuter votre application.Select F5 to run your application.

Félicitations !Congratulations! Vous avez supprimé une base de données Azure Cosmos DB.You have successfully deleted an Azure Cosmos DB database.

Étape 11 : Exécuter votre application de console C#Step 11: Run your C# console application all together!

Sélectionnez F5 dans Visual Studio pour générer et exécuter l’application en mode débogage.Select F5 in Visual Studio to build and run the application in debug mode.

La sortie de votre application entière doit s’afficher dans une fenêtre de console.You should see the output of your entire app in a console window. Celle-ci doit présenter les résultats des requêtes que nous avons ajoutées, qui doivent correspondre au texte d'exemple ci-dessous.The output will show the results of the queries we added and 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.

Félicitations !Congratulations! Vous avez terminé le didacticiel et vous disposez d’une application de console C# qui fonctionne !You've completed the tutorial and have a working C# console application!

Obtenir la solution complète du didacticielGet the complete tutorial solution

Si vous n’avez pas le temps de suivre les étapes de ce didacticiel, ou que vous voulez simplement télécharger les exemples de code, vous pouvez les obtenir à partir de GitHub.If you didn't have time to complete the steps in this tutorial, or just want to download the code samples, you can get it from GitHub.

Pour générer la solution GetStarted, vous aurez besoin des éléments suivants :To build the GetStarted solution, you will need the following:

Pour restaurer les références au kit SDK .NET Azure Cosmos DB dans Visual Studio, cliquez avec le bouton droit sur la solution GetStarted dans l’Explorateur de solutions, puis cliquez sur Restaurer des packages NuGet.To restore the references to the Azure Cosmos DB .NET SDK in Visual Studio, right-click the GetStarted solution in Solution Explorer, and then click Restore NuGet Packages. Ensuite, dans le fichier App.config, mettez à jour les valeurs EndPointUri et PrimaryKey, comme décrit dans Se connecter à un compte Azure Cosmos DB.Next, in the App.config file, update the EndPointUri and PrimaryKey values as described in Connect to an Azure Cosmos DB account.

Voilà, générez l’élément et c’est parti !That's it, build it, and you're on your way!

Étapes suivantesNext steps