Esercitazione: Compilare un'app console .NET per gestire i dati in un account API SQL di Azure Cosmos DBTutorial: Build a .NET console app to manage data in Azure Cosmos DB SQL API account

Questa è un'esercitazione introduttiva per l'API SQL di Azure Cosmos DB.Welcome to the Azure Cosmos DB SQL API get started tutorial. Dopo aver seguito questa esercitazione, si otterrà un'applicazione console che consente di creare e ridefinire le query delle risorse Azure Cosmos DB.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

Questa esercitazione usa la versione 3.0 o successiva di Azure Cosmos DB .NET SDK.This tutorial uses version 3.0 or later of the Azure Cosmos DB .NET SDK. È possibile usare .NET Framework o .NET Core.You can work with .NET Framework or .NET Core.

Contenuto dell'esercitazione:This tutorial covers:

  • Creazione e connessione a un account Azure CosmosCreating and connecting to an Azure Cosmos account
  • Configurazione del progetto in Visual StudioConfiguring your project in Visual Studio
  • Creazione di un database e di un contenitoreCreating a database and a container
  • Aggiunta di elementi al contenitoreAdding items to the container
  • Esecuzione di query sul contenitoreQuerying the container
  • Esecuzione di operazioni di creazione, lettura, aggiornamento ed eliminazione dell'elementoPerforming create, read, update, and delete (CRUD) operations on the item
  • Eliminazione del databaseDeleting the database

Non si ha tempo?Don't have time? Nessun problema.Don't worry! La soluzione completa è disponibile in GitHub.The complete solution is available on GitHub. Per istruzioni rapide, vedere la sezione Ottenere la soluzione completa per l'esercitazione.Jump to the Get the complete tutorial solution section for quick instructions.

Ecco come procedere.Now let's get started!

PrerequisitiPrerequisites

Passaggio 1: Creare un account Azure Cosmos DBStep 1: Create an Azure Cosmos DB account

Creare prima di tutto un account Azure Cosmos DB.Let's create an Azure Cosmos DB account. Se si ha già un account che si vuole usare, ignorare questa sezione.If you already have an account you want to use, skip this section. Se si usa l'emulatore di Azure Cosmos DB, seguire la procedura illustrata in Emulatore di Azure Cosmos DB per configurarlo.To use the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator. Quindi procedere con il Passaggio 2: Configurare il progetto di Visual Studio.Then skip ahead to Step 2: Set up your Visual Studio project.

  1. Passare al portale di Azure per creare un account Azure Cosmos DB.Go to the Azure portal to create an Azure Cosmos DB account. Cercare e selezionare Azure Cosmos DB.Search for and select Azure Cosmos DB.

    Riquadro Database nel portale di Azure

  2. Selezionare Aggiungi.Select Add.

  3. Nella pagina Crea account Cosmos DB immettere le impostazioni base per il nuovo account Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ImpostazioneSetting valoreValue DescrizioneDescription
    SubscriptionSubscription Nome sottoscrizioneSubscription name Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Gruppo di risorseResource Group Nome del gruppo di risorseResource group name Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome accountAccount Name Un nome univocoA unique name Immettere un nome per identificare l'account Azure Cosmos.Enter a name to identify your Azure Cosmos account. Dato che al nome specificato viene aggiunto documents.azure.com per creare l'URI, usare un nome univoco.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Il nome può contenere solo lettere minuscole, numeri e il segno meno (-).The name can only contain lowercase letters, numbers, and the hyphen (-) character. Deve avere una lunghezza compresa tra 3 e 31 caratteri.It must be between 3-31 characters in length.
    APIAPI Il tipo di account da creareThe type of account to create Selezionare Core (SQL) per creare un database di documenti e una query con la sintassi SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API: Core (SQL) e MongoDB per dati dei documenti, Gremlin per i dati dei grafici, Tabelle di Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Attualmente, è necessario creare un account separato per ogni API.Currently, you must create a separate account for each API.

    Altre informazioni sull'API SQL.Learn more about the SQL API.
    LocationLocation Area più vicina ai propri utentiThe region closest to your users Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.Use the location that is closest to your users to give them the fastest access to the data.

    Pagina del nuovo account per Azure Cosmos DB

  4. Selezionare Rivedi e crea.Select Review + create. È possibile ignorare le sezioni Rete e Tag.You can skip the Network and Tags sections.

  5. Esaminare le impostazioni dell'account e quindi selezionare Crea.Review the account settings, and then select Create. La creazione dell'account richiede alcuni minuti.It takes a few minutes to create the account. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.Wait for the portal page to display Your deployment is complete.

    Riquadro Notifiche del portale di Azure

  6. Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Pagina dell'account Azure Cosmos DB

Passaggio 2: Configurare il progetto di Visual StudioStep 2: Set up your Visual Studio project

  1. Aprire Visual Studio e selezionare Crea un nuovo progetto.Open Visual Studio and select Create a new project.

  2. In Crea un nuovo progetto scegliere App console (.NET Framework) per C#, quindi selezionare Avanti.In Create a new project, choose Console App (.NET Framework) for C#, then select Next.

  3. Assegnare al progetto il nome CosmosGettingStartedTutorial e quindi selezionare Crea.Name your project CosmosGettingStartedTutorial, and then select Create.

    Configurare il progetto

  4. In Esplora soluzioni fare clic con il pulsante destro del mouse sulla nuova applicazione console, disponibile nella soluzione di Visual Studio, quindi scegliere Gestisci pacchetti NuGet.In the Solution Explorer, right-click your new console application, which is under your Visual Studio solution, and select Manage NuGet Packages.

  5. In Gestione pacchetti NuGet selezionare Sfoglia e cercare Microsoft.Azure.Cosmos.In the NuGet Package Manager, select Browse and search for Microsoft.Azure.Cosmos. Scegliere Microsoft.Azure.Cosmos e selezionare Installa.Choose Microsoft.Azure.Cosmos and select Install.

    Installare NuGet per l'SDK client di Azure Cosmos DB

    L'ID pacchetto per la libreria client dell'API SQL di Azure Cosmos DB è 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.

L'installazione è riuscita.Great! Ora che abbiamo completato l'installazione, iniziamo a scrivere il codice.Now that we finished the setup, let's start writing some code. Per il progetto completo di questa esercitazione, vedere Sviluppo di un'app console .NET tramite Azure Cosmos DB.For the completed project of this tutorial, see Developing a .NET console app using Azure Cosmos DB.

Passaggio 3: collegarsi a un account di Azure Cosmos DBStep 3: Connect to an Azure Cosmos DB account

  1. Sostituire i riferimenti all'inizio dell'applicazione C#, nel file Program.cs, con questi riferimenti: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. Aggiungere queste costanti e variabili nella classe 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

    Se si ha familiarità con la versione precedente di .NET SDK, i termini raccolta e documento saranno già noti.If you're familiar with the previous version of the .NET SDK, you may be familiar with the terms collection and document. Poiché Azure Cosmos DB supporta più modelli di API, nella versione 3.0 di .NET SDK vengono usati i termini generici contenitore ed elemento.Because Azure Cosmos DB supports multiple API models, version 3.0 of the .NET SDK uses the generic terms container and item. Un contenitore può essere una raccolta, un grafo o una tabella.A container can be a collection, graph, or table. Un elemento può essere un documento, un arco/vertice o una riga ed è il contenuto all'interno di un contenitore.An item can be a document, edge/vertex, or row, and is the content inside a container. Per altre informazioni, vedere Uso di contenitori ed elementi di Azure Cosmos.For more information, see Work with databases, containers, and items in Azure Cosmos DB.

  3. Aprire il portale di Azure.Open the Azure portal. Trovare l'account Azure Cosmos DB e quindi selezionare Chiavi.Find your Azure Cosmos DB account, and then select Keys.

    Ottenere le chiavi di Azure Cosmos DB dal portale di Azure

  4. In Program.cs sostituire <your endpoint URL> con il valore di URI.In Program.cs, replace <your endpoint URL> with the value of URI. Sostituire <your primary key> con il valore di CHIAVE PRIMARIA.Replace <your primary key> with the value of PRIMARY KEY.

  5. Sotto il metodo Main aggiungere una nuova attività asincrona denominata GetStartedDemoAsync, che creerà un'istanza del nuovo 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);
    }
    

    Si usa GetStartedDemoAsync come punto di ingresso che chiama i metodi che agiscono sulle risorse di Azure Cosmos DB.We use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

  6. Aggiungere il codice seguente per eseguire l'attività asincrona GetStartedDemoAsync dal metodo Main.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. Il metodo Main rileva le eccezioni e le scrive nella console.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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

    La console visualizza il messaggio: End of demo, press any key to exit (Fine della demo, premere un tasto qualsiasi per uscire).The console displays the message: End of demo, press any key to exit. Questo messaggio conferma che l'applicazione ha stabilito una connessione con Azure Cosmos DB.This message confirms that your application made a connection to Azure Cosmos DB. È quindi possibile chiudere la finestra della console.You can then close the console window.

Congratulazioni!Congratulations! La connessione con un account di Azure Cosmos DB è stata stabilita correttamente.You've successfully connected to an Azure Cosmos DB account.

Passaggio 4: Creare un databaseStep 4: Create a database

Un database è un contenitore logico di elementi partizionati tra contenitori.A database is the logical container of items partitioned across containers. Il metodo CreateDatabaseIfNotExistsAsync o CreateDatabaseAsync della classe CosmosClient può creare un database.Either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync method of the CosmosClient class can create a database.

  1. Copiare e incollare il metodo CreateDatabaseAsync seguente sotto il metodo 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 un nuovo database con ID FamilyDatabase, se non esiste già, ossia l'ID specificato nel 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. Copiare e incollare il codice seguente nel punto in cui è stata creata l'istanza di CosmosClient per chiamare il metodo CreateDatabaseAsync appena aggiunto.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();
    }
    

    A questo punto il file Program.cs dovrebbe avere un aspetto simile al seguente, con l'endpoint e la chiave primaria compilati.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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

    Nota

    Se viene visualizzato un messaggio di errore analogo a "503 servizio non disponibile", è possibile che le porte necessarie per la modalità di connettività diretta siano bloccate da 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. Per risolvere questo problema, aprire le porte necessarie o usare la connettività in modalità gateway come illustrato nel codice seguente: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
             });
    

Congratulazioni!Congratulations! La creazione di un database Azure Cosmos è stata completata.You've successfully created an Azure Cosmos database.

Passaggio 5: Creare un contenitoreStep 5: Create a container

Avviso

Il metodo CreateContainerIfNotExistsAsync crea un nuovo contenitore, che presenta implicazioni per i prezzi.The method CreateContainerIfNotExistsAsync creates a new container, which has pricing implications. Per altre informazioni, visitare la pagina relativa ai prezzi.For more details, please visit our pricing page.

Un contenitore può essere creato usando il metodo CreateContainerIfNotExistsAsync o CreateContainerAsync della classe CosmosDatabase.A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync method in the CosmosDatabase class. Un contenitore è costituito da elementi (documenti JSON nel caso dell'API SQL) e dalla logica dell'applicazione lato server associata in JavaScript, ad esempio stored procedure, funzioni definite dall'utente e trigger.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. Copiare e incollare il metodo CreateContainerAsync seguente sotto il metodo CreateDatabaseAsync.Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. CreateContainerAsync crea un nuovo contenitore con l'ID FamilyContainer, se non esiste già, usando l'ID specificato nel campo containerId partizionato dalla proprietà 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. Copiare e incollare il codice seguente nel punto in cui è stata creata l'istanza di CosmosClient per chiamare il metodo CreateContainer appena aggiunto.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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! La creazione di un contenitore Azure Cosmos è stata completata.You've successfully created an Azure Cosmos container.

Passaggio 6: Aggiungere elementi al contenitoreStep 6: Add items to the container

Il metodo CreateItemAsync della classe CosmosContainer può creare un elemento.The CreateItemAsync method of the CosmosContainer class can create an item. Quando si usa l'API SQL, gli elementi vengono proiettati come documenti, che sono contenuti JSON arbitrari definiti dall'utente.When using the SQL API, items are projected as documents, which are user-defined arbitrary JSON content. È ora possibile inserire un elemento nel contenitore Azure Cosmos.You can now insert an item into your Azure Cosmos container.

Prima di tutto creare una classe Family che rappresenterà gli oggetti archiviati in Azure Cosmos DB in questo esempio.First, let's create a Family class that represents objects stored within Azure Cosmos DB in this sample. Creare inoltre le sottoclassi Parent, Child, Pet, Address usate all'interno di Family.We'll also create Parent, Child, Pet, Address subclasses that are used within Family. L'elemento deve avere una proprietà Id serializzata come id in JSON.The item must have an Id property serialized as id in JSON.

  1. Premere CTRL+MAIUSC+A per aprire la finestra di dialogo Aggiungi nuovo elemento.Select Ctrl+Shift+A to open Add New Item. Aggiungere una nuova classe Family.cs al progetto.Add a new class Family.cs to your project.

    Screenshot dell'aggiunta di una nuova classe Family.cs nel progetto

  2. Copiare e incollare le classi Family, Parent, Child, Pet e Address in 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. Nel file Program.cs aggiungere il metodo AddItemsToContainerAsync dopo il metodo 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);
        }
    }
    

    Il codice verifica che non esista già un elemento con lo stesso ID.The code checks to make sure an item with the same ID doesn't already exist. Verranno inseriti due elementi, uno per Andersen Family e l'altro per Wakefield Family.We'll insert two items, one each for the Andersen Family and the Wakefield Family.

  4. Aggiungere una chiamata a AddItemsToContainerAsync nel metodo 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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! La creazione di due elementi Azure Cosmos è stata completata.You've successfully created two Azure Cosmos items.

Passaggio 7: eseguire query sulle risorse di Azure Cosmos DBStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB supporta le query complesse sui documenti JSON archiviati in ogni contenitore.Azure Cosmos DB supports rich queries against JSON documents stored in each container. Per altre informazioni, vedere Introduzione alle query SQL.For more information, see Getting started with SQL queries. Il codice di esempio seguente mostra come eseguire una query sugli elementi inseriti nella procedura precedente.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Copiare e incollare il metodo QueryItemsAsync dopo il metodo 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. Aggiungere una chiamata a QueryItemsAsync nel metodo 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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! Sono state eseguite query su un contenitore Azure Cosmos.You've successfully queried an Azure Cosmos container.

Passaggio 8: sostituire un elemento JSONStep 8: Replace a JSON item

Aggiornare ora un elemento in Azure Cosmos DB.Now, we'll update an item in Azure Cosmos DB. Cambiare la proprietà IsRegistered di Family e l'oggetto Grade di uno dei figli.We'll change the IsRegistered property of the Family and the Grade of one of the children.

  1. Copiare e incollare il metodo ReplaceFamilyItemAsync dopo il metodo 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. Aggiungere una chiamata a ReplaceFamilyItemAsync nel metodo 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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! La sostituzione di un elemento Azure Cosmos è stata completata.You've successfully replaced an Azure Cosmos item.

Passaggio 9: Elimina elementoStep 9: Delete item

Eliminare ora un elemento in Azure Cosmos DB.Now, we'll delete an item in Azure Cosmos DB.

  1. Copiare e incollare il metodo DeleteFamilyItemAsync dopo il metodo 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. Aggiungere una chiamata a DeleteFamilyItemAsync nel metodo 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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! L'eliminazione di un elemento Azure Cosmos è stata completata.You've successfully deleted an Azure Cosmos item.

Passaggio 10: eliminare il databaseStep 10: Delete the database

A questo punto verrà eliminato il database.Now we'll delete our database. Se si elimina il database creato, vengono rimosse tutte le risorse figlio,Deleting the created database removes the database and all children resources. come contenitori, elementi ed eventuali stored procedure, funzioni definite dall'utente e trigger.The resources include containers, items, and any stored procedures, user-defined functions, and triggers. Verrà anche eliminata l'istanza di CosmosClient.We also dispose of the CosmosClient instance.

  1. Copiare e incollare il metodo DeleteDatabaseAndCleanupAsync dopo il metodo 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. Aggiungere una chiamata a DeleteDatabaseAndCleanupAsync nel metodo 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. Premere F5 per eseguire l'applicazione.Select F5 to run your application.

Congratulazioni!Congratulations! L'eliminazione di un database Azure Cosmos è stata completata.You've successfully deleted an Azure Cosmos database.

Passaggio 11: eseguire l'intera applicazione console C#Step 11: Run your C# console application all together!

Premere F5 in Visual Studio per compilare ed eseguire l'applicazione in modalità di debug.Select F5 in Visual Studio to build and run the application in debug mode.

Dovrebbe essere visualizzato l'output dell'intera app in una finestra della console.You should see the output of your entire app in a console window. L'output mostra i risultati delle query aggiunte.The output shows the results of the queries we added. Dovrebbe essere analogo al testo di esempio seguente.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.

Congratulazioni!Congratulations! L'esercitazione è stata completata ed è stata creata un'applicazione console C# funzionante.You've completed the tutorial and have a working C# console application!

Ottenere la soluzione completa per l'esercitazioneGet the complete tutorial solution

Se non si ha tempo per completare le procedure dell'esercitazione o se si vogliono solo ottenere gli esempi di codice, è possibile scaricarli.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.

Per creare la soluzione GetStarted, è necessario soddisfare i prerequisiti seguenti:To build the GetStarted solution, you need the following prerequisites:

Per ripristinare i riferimenti ad Azure Cosmos DB .NET SDK in Visual Studio, fare clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni e quindi scegliere Ripristina pacchetti 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. Quindi, nel file App.config aggiornare i valori di EndPointUri e PrimaryKey come descritto in Passaggio 3: Connettersi a un account 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.

A questo punto non resta che procedere con la compilazione.That's it, build it, and you're on your way!

Passaggi successiviNext steps