Tworzenie aplikacji konsolowej .NET do zarządzania danymi w Azure Cosmos DB koncie interfejsu API SQLBuild a .NET console app to manage data in Azure Cosmos DB SQL API account

Witamy w samouczku wprowadzenie do interfejsu API SQL Azure Cosmos DB.Welcome to the Azure Cosmos DB SQL API get started tutorial. W ramach tego samouczka zostanie utworzona aplikacja konsolowa, która tworzy zasoby usługi Azure Cosmos DB i wykonuje dla nich zapytania.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources. W tym samouczku jest używana wersja 3.0 programu Azure Cosmos DB .NET SDK, która może być przeznaczona dla .NET Framework lub .NET Core.This tutorial uses Version 3.0+ of the Azure Cosmos DB .NET SDK, which can be targeted to .NET Framework or .NET Core.

W tym samouczku opisano następujące czynności:This tutorial covers:

  • Tworzenie konta usługi Azure Cosmos i łączenie się z nimCreating and connecting to an Azure Cosmos account
  • Konfigurowanie projektu w programie Visual StudioConfiguring your project in Visual Studio
  • Tworzenie bazy danych i konteneraCreating a database and a container
  • Dodawanie elementów do konteneraAdding items to the container
  • Wykonywanie zapytań względem konteneraQuerying the container
  • Wykonywanie operacji CRUD na elemencieCRUD operations on the item
  • Usuwanie bazy danychDeleting the database

Nie masz czasu?Don't have time? Nie martw się!Don't worry! Kompletne rozwiązanie jest dostępne w witrynie GitHub.The complete solution is available on GitHub. Przeskocz do sekcji Pobieranie kompletnego rozwiązania samouczka, aby uzyskać krótkie instrukcje.Jump to the Get the complete tutorial solution section for quick instructions.

Teraz do dzieła!Now let's get started!

Wymagania wstępnePrerequisites

Krok 1. Tworzenie konta usługi Azure Cosmos DBStep 1: Create an Azure Cosmos DB account

Utwórzmy konto usługi Azure Cosmos DB.Let's create an Azure Cosmos DB account. Jeśli masz już konto, którego chcesz użyć, możesz przejść od razu do kroku Konfigurowanie rozwiązania Visual Studio.If you already have an account you want to use, you can skip ahead to Setup your Visual Studio Solution. Jeśli używasz emulatora usługi Azure Cosmos DB, wykonaj czynności opisane w temacie Emulator usługi Azure Cosmos DB, aby skonfigurować emulator, a następnie przejdź do sekcji Konfigurowanie projektu programu 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. W nowym oknie przeglądarki zaloguj się do witryny Azure Portal.In a new browser window, sign in to the Azure portal.

  2. Kliknij kolejno pozycje Utwórz zasób > Bazy danych > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Okienko Bazy danych w witrynie Azure Portal

  3. Na stronie Tworzenie konta usługi Azure Cosmos DB wprowadź ustawienia nowego konta usługi Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    UstawienieSetting WartośćValue OpisDescription
    SubskrypcjaSubscription Twoja subskrypcjaYour subscription Wybierz subskrypcję platformy Azure, której chcesz użyć dla tego konta usługi Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupa zasobówResource Group Tworzenie nowego elementuCreate new

    Wprowadź unikatową nazwęEnter a unique name
    Wybierz pozycję Utwórz nową, a następnie wprowadź nazwę nowej grupy zasobów dla konta.Select Create New, then enter a new resource-group name for your account. Dla uproszczenia można użyć takiej samej nazwy nazwa konta.For simplicity, you can use the same name as your Account Name.
    Nazwa kontaAccount Name Wprowadź unikatową nazwęEnter a unique name Wprowadź unikatową nazwę do identyfikacji konta usługi Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Ponieważ adres documents.azure.com jest dołączany do podanego identyfikatora w celu utworzenia identyfikatora URI, użyj unikatowego identyfikatora.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    Identyfikator może zawierać tylko małe litery, cyfry i znaki łącznika (-) oraz musi mieć długość od 3 do 31 znaków.The ID can only contain lowercase letters, numbers, and the hyphen (-) character, and it must be between 3 and 31 characters in length..
    Interfejs APIAPI Core (SQL)Core (SQL) Interfejs API określa typ konta do utworzenia.The API determines the type of account to create. Usługa Azure Cosmos DB oferuje pięć interfejsów API: SQL (baza danych dokumentów), Gremlin (baza danych wykresów), MongoDB (baza danych dokumentów), interfejs API tabel i interfejs API Cassandra.Azure Cosmos DB provides five APIs: SQL (document database), Gremlin (graph database), MongoDB (document database), Table API, and Cassandra API. Każdy interfejs API obecnie wymaga utworzenia oddzielnego konta.Each API currently requires you to create a separate account.

    Wybierz pozycję Core (SQL) , ponieważ w tym artykule utworzysz bazę danych dokumentów i wykonasz zapytanie przy użyciu składni języka SQL.Select Core (SQL) because in this article you will create a document database and query using SQL syntax.

    Dowiedz się więcej o interfejsie API SQLLearn more about the SQL API
    LokalizacjaLocation Wybierz region najbliżej Twoich użytkownikówSelect the region closest to your users Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Użyj lokalizacji znajdującej się najbliżej Twoich użytkowników, aby zapewnić im najszybszy dostęp do danych.Use the location that's closest to your users to give them the fastest access to the data.
    Włącz nadmiarowość geograficznąEnable geo-redundancy Pozostaw pusteLeave blank Spowoduje to utworzenie replikowanej wersji bazy danych w drugim (sparowanym) regionie.This creates a replicated version of your database in a second (paired) region. Pozostaw to pole puste.Leave this blank.
    Zapisy w wielu regionachMulti-region writes Pozostaw pusteLeave blank Dzięki temu każdy z regionów baz danych może być zarówno regionem odczytu, jak i regionem zapisu.This enables each of your database regions to be both a read and write region. Pozostaw to pole puste.Leave this blank.

    Następnie kliknij pozycję Przeglądanie + tworzenie.Then click Review + create. Możesz pominąć sekcje Sieć i Tagi.You can skip the Network and Tags section.

    Strona nowego konta usługi Azure Cosmos DB

    Przejrzyj informacje podsumowujące i kliknij pozycję Utwórz.Review the summary information and click Create.

    Strona podsumowania weryfikacji konta

  4. Tworzenie konta potrwa kilka minut.The account creation takes a few minutes. Poczekaj, aż w portalu zostanie wyświetlony komunikat Wdrożenie zostało ukończone, a następnie kliknij pozycję Przejdź do zasobu.Wait for the portal to display the Your deployment is complete message and click Go to resource.

    Strona pomyślnego utworzenia konta

  5. W portalu zostanie teraz wyświetlona stronaGratulacje! Konto usługi Azure Cosmos DB zostało utworzone.The portal will now display the Congratulations! Your Azure Cosmos DB account was created page.

    Okienko Powiadomienia w witrynie Azure Portal

Krok 2. Konfigurowanie projektu programu Visual StudioStep 2: Setup your Visual Studio project

  1. Otwórz program Visual Studio 2017 na komputerze.Open Visual Studio 2017 on your computer.

  2. W menu Plik wybierz polecenie Nowy, a następnie wybierz pozycję Projekt.On the File menu, select New, and then choose Project.

  3. W oknie dialogowym Nowy projekt wybierz pozycję Visual C# / Aplikacja konsolowa (.NET Framework) , podaj nazwę projektu, a następnie kliknij przycisk OK.In the New Project dialog, select Visual C# / Console App (.NET Framework), name your project, and then click OK. Zrzut ekranu przedstawiający okno nowy projektScreenshot of the New Project window

    Uwaga

    W przypadku programu .NET Core Target w oknie dialogowym Nowy projekt wybierz pozycję C# / Aplikacja konsolowa (.NET Core) , nazwij projekt, a następnie kliknij przycisk OK .For .NET core target, in the New Project dialog, select Visual C# / Console App (.NET Core), name your project, and then click OK

  4. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nową aplikację konsolową, która znajduje się w ramach rozwiązania Visual Studio, a następnie kliknij pozycję Zarządzaj pakietami 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...

    Zrzut ekranu przedstawiający menu projektu kliknięte prawym przyciskiem myszy

  5. Na karcie NuGet kliknij pozycję Przeglądaj i wpisz ciąg Microsoft.Azure.Cosmos w polu wyszukiwania.In the NuGet tab, click Browse, and type Microsoft.Azure.Cosmos in the search box.

  6. W wynikach znajdź pozycję Microsoft.Azure.Cosmos, a następnie kliknij przycisk Zainstaluj.Within the results, find Microsoft.Azure.Cosmos and click Install. Identyfikator pakietu biblioteki klienta interfejsu API SQL w usłudze Azure Cosmos DB to 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. Zrzut ekranu przedstawiający menu NuGet służące do znajdowania zestawu SDK klienta Azure Cosmos DBScreenshot of the NuGet Menu for finding Azure Cosmos DB Client SDK

    Jeśli zostanie wyświetlony komunikat dotyczący przejrzenia zmian wprowadzonych w rozwiązaniu, kliknij przycisk OK.If you get a message about reviewing changes to the solution, click OK. Jeśli wyświetlany jest komunikat o akceptacji licencji, kliknij pozycję Akceptuję.If you get a message about license acceptance, click I accept.

Wspaniale!Great! Teraz, po zakończeniu konfigurowania, zacznijmy pisanie kodu.Now that we finished the setup, let's start writing some code. Ukończony projekt kodu z tego samouczka można znaleźć w witrynie GitHub.You can find a completed code project of this tutorial at GitHub.

Krok 3. Łączenie się z kontem usługi Azure Cosmos DBStep 3: Connect to an Azure Cosmos DB account

  1. Najpierw zastąp odwołania na początku aplikacji C# w pliku Program.cs następującymi odwołaniami:First, 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. Następnie dodaj te stałe i zmienne do klasy publicznej 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 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";
    }
    

    Osoby znające poprzednią wersję zestawu .NET SDK mogą być przyzwyczajone do terminów „kolekcja” i „dokument”.Note, if you are familiar with the previous version of the .NET SDK, you may be used to seeing the terms 'collection' and 'document.' Ponieważ usługa Azure Cosmos DB obsługuje wiele modeli interfejsu API, w wersji 3.0+ zestawu .NET SDK używane są ogólne terminy „kontener” i „element”.Because Azure Cosmos DB supports multiple API models, version 3.0+ of the .NET SDK uses the generic terms 'container' and 'item.' Kontener może być kolekcją, wykresem lub tabelą.A container can be a collection, graph, or table. Element może być dokumentem, krawędzią/wierzchołkiem lub wierszem i stanowi zawartość znajdująca się w kontenerze.An item can be a document, edge/vertex, or row, and is the content inside a container. Dowiedz się więcej na temat baz danych, kontenerów i elementów.Learn more about databases, containers, and items.

  3. Pobierz adres URL punktu końcowego i klucz podstawowy z witryny Azure Portal.Retrieve your endpoint URL and primary key from the Azure portal.

    W witrynie Azure Portal przejdź do swojego konta usługi Azure Cosmos DB i kliknij pozycję Klucze.In the Azure portal, navigate to your Azure Cosmos DB account, and then click Keys.

    Skopiuj identyfikator URI z portalu i wklej go w miejsce <your endpoint URL> w pliku Program.cs.Copy the URI from the portal and paste it into <your endpoint URL> in the Program.cs file. Skopiuj KLUCZ PODSTAWOWY z portalu i wklej go w miejsce <your primary key>.Copy the PRIMARY KEY from the portal and paste it into <your primary key>.

    Zrzut ekranu przedstawiający klucze Azure Cosmos DB z Azure Portal

  4. Następnie utworzymy nowe wystąpienie klasy CosmosClient i skonfigurujemy niektóre elementy szkieletu naszego programu.Next, we'll create a new instance of CosmosClient and set up some scaffolding for our program.

    Poniżej metody Main dodaj nowe zadanie asynchroniczne o nazwie GetStartedDemoAsync, które utworzy nowe wystąpienie klasy CosmosClient.Below the Main method, add a new asynchronous task called GetStartedDemoAsync, which will instantiate our new CosmosClient. Zadanie GetStartedDemoAsync służy jako punkt wejścia wywołujący metody, które działają na zasobach usługi 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. Dodaj następujący kod w celu uruchomienia zadania asynchronicznego GetStartedDemoAsync w metodzie Main.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. Metoda Main będzie przechwytywać wyjątki i zapisywać je w konsoli.The Main method will catch exceptions and write 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();
        }
    }
    
  6. Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application. W danych wyjściowych okna konsoli wyświetlany jest komunikat End of demo, press any key to exit. potwierdzający nawiązanie połączenia z usługą Azure Cosmos DB.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. Następnie można zamknąć okno konsoli.You can then close the console window.

Gratulacje!Congratulations! Pomyślnie nawiązano połączenie z kontem usługi Azure Cosmos DB.You have successfully connected to an Azure Cosmos DB account.

Krok 4. Tworzenie bazy danychStep 4: Create a database

Bazę danych można utworzyć przy użyciu funkcji CreateDatabaseIfNotExistsAsync lub CreateDatabaseAsync klasy CosmosClient.A database can be created by using either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync function of the CosmosClient class. Baza danych jest logicznym kontenerem elementów podzielonym na partycje w kontenerach.A database is the logical container of items partitioned across containers.

  1. Skopiuj i wklej metodę CreateDatabaseAsync poniżej metody GetStartedDemoAsync .Copy and paste the CreateDatabaseAsync method below your GetStartedDemoAsync method. CreateDatabaseAsync utworzy nową bazę danych o identyfikatorze FamilyDatabase , jeśli jeszcze nie istnieje, z databaseId identyfikatorem określonym w polu.CreateDatabaseAsync will create a new database with ID FamilyDatabase if it does not already exist, with the ID specified from the databaseId field.

    /// <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);
    }
    
  2. Skopiuj i wklej kod poniżej miejsca, w którym utworzono wystąpienie CosmosClient, aby wywołać metodę CreateDatabaseAsync , która właśnie została dodana.Copy and paste the code below where you instantiated 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();
    }
    

    Na tym etapie kod powinien wyglądać mniej więcej tak i zawierać dane dotyczące punktu końcowego i klucza podstawowego.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 System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
    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 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);
            }
        }
    }
    

Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Baza danych Azure Cosmos została pomyślnie utworzona.You have successfully created an Azure Cosmos database.

Krok 5. Tworzenie konteneraStep 5: Create a container

Ostrzeżenie

Wywołanie metody CreateContainerIfNotExistsAsync spowoduje utworzenie nowego kontenera, co ma wpływ na koszty.Calling the method CreateContainerIfNotExistsAsync will create a new container, which has pricing implications. Aby uzyskać więcej informacji, odwiedź naszą stronę cennika.For more details, please visit our pricing page.

Kontener można utworzyć za pomocą funkcji CreateContainerIfNotExistsAsync lub CreateContainerAsync w klasie CosmosDatabase .A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync function in the CosmosDatabase class. Kontener składa się z elementów (dokumentów JSON, jeśli interfejs API SQL) i skojarzonej logiki aplikacji po stronie serwera w języku JavaScript, na przykład procedury składowane, funkcje zdefiniowane przez użytkownika i wyzwalacze.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. Skopiuj i wklej metodę CreateContainerAsync poniżej metody CreateDatabaseAsync .Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. CreateContainerAsync utworzy nowy kontener o identyfikatorze FamilyContainer , jeśli jeszcze nie istnieje, z containerId identyfikatorem określonym w polu partycjonowanym przez LastName właściwość.CreateContainerAsync will create a new container with ID FamilyContainer if it does not already exist, with 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. Poniższy kod umożliwia wywołanie właśnie dodanej metody CreateContainer. Skopiuj go i wklej pod wierszem, w którym jest tworzone wystąpienie klasy CosmosClient.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();
    }
    

    Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie utworzono kontener usługi Azure Cosmos.You have successfully created an Azure Cosmos container.

Krok 6. Dodawanie elementów do konteneraStep 6: Add items to the container

Element można utworzyć za pomocą funkcji CreateItemAsync klasy CosmosContainer .An item can be created by using the CreateItemAsync function of the CosmosContainer class. Podczas korzystania z interfejsu API SQL elementy są przekazywane jako dokumenty, które stanowią zdefiniowaną przez użytkownika (dowolną) zawartość JSON.When using the SQL API, items are projected as documents, which are user-defined (arbitrary) JSON content. Teraz można wstawić element do kontenera usługi Azure Cosmos.You can now insert an item into your Azure Cosmos container.

Najpierw Utwórzmy klasę rodziny , która będzie reprezentować obiekty przechowywane w Azure Cosmos DB w tym przykładzie.First, let's create a Family class that will represent objects stored within Azure Cosmos DB in this sample. Zostaną również utworzone podklasy Parent, Child, Pet i Address, które są używane w ramach klasy Family.We will also create Parent, Child, Pet, Address subclasses that are used within Family. Element Note musi mieć serializowaną Właściwość ID jako Identyfikator w formacie JSON.Note item must have an Id property serialized as id in JSON.

  1. Naciśnij klawisze Ctrl+Shift+A, aby otworzyć okno dialogowe Dodaj nowy element.Select Ctrl+Shift+A to open the Add New Item dialog. Dodaj do projektu nową klasę Family.cs.Add a new class Family.cs to your project.

    Zrzut ekranu przedstawiający Dodawanie nowej klasy Family.cs do projektu

  2. Skopiuj i wklej klasy Family, Parent, Child, Pet i Address do klasy 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. Wróć do program.cs i Dodaj metodę AddItemsToContainerAsync w ramach metody CreateContainerAsync .Navigate back to Program.cs and add the AddItemsToContainerAsync method under your CreateContainerAsync method. Kod sprawdza, czy element o takim samym IDENTYFIKATORze jeszcze nie istnieje przed jego utworzeniem.The code checks to make sure an item with the same ID does not already exist before creating it. Wstawimy dwa elementy, jeden dla rodziny Andersen i jeden dla rodziny Wakefield.We will insert two items, one each for the Andersen Family and the Wakefield Family.

    /// <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);
        }
    }
    
  4. Dodaj wywołanie metody AddItemsToContainerAsync w metodzie 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();
    }
    

Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie utworzono dwa elementy usługi Azure Cosmos.You have successfully created two Azure Cosmos items.

Krok 7: Wykonywanie zapytania względem zasobów usługi Azure Cosmos DBStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB obsługuje zaawansowane zapytania względem dokumentów JSON przechowywanych w każdym kontenerze.Azure Cosmos DB supports rich queries against JSON documents stored in each container. W następującym przykładowym kodzie pokazano, jak uruchomić zapytanie względem elementów wstawionych w poprzednim kroku.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Skopiuj i wklej metodę QueryItemsAsync poniżej metody AddItemsToContainerAsync .Copy and paste the QueryItemsAsync method below 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. Dodaj wywołanie metody QueryItemsAsync w metodzie 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();
    }
    

Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie wykonano zapytanie względem kontenera usługi Azure Cosmos.You have successfully queried against an Azure Cosmos container.

Krok 8. Zastępowanie elementu JSONStep 8: Replace a JSON item

Teraz zaktualizujemy element w usłudze Azure Cosmos DB.Now, we will update an item in Azure Cosmos DB.

  1. Skopiuj i wklej metodę ReplaceFamilyItemAsync poniżej metody QueryItemsAsync .Copy and paste the ReplaceFamilyItemAsync method below your QueryItemsAsync method. Zwróć uwagę, że zmieniamy właściwość IsRegistered rodziny i właściwość Grade jednego dziecka.Note we are changing the IsRegistered property of the Family and the Grade of one of the children.

    /// <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. Dodaj wywołanie metody ReplaceFamilyItemAsync w metodzie 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();
    }
    

    Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie zamieniono element usługi Azure Cosmos.You have successfully replaced an Azure Cosmos item.

Krok 9. Usuwanie elementuStep 9: Delete item

Teraz usuniemy element w usłudze Azure Cosmos DB.Now, we will delete an item in Azure Cosmos DB.

  1. Skopiuj i wklej metodę DeleteFamilyItemAsync poniżej metody ReplaceFamilyItemAsync .Copy and paste the DeleteFamilyItemAsync method below 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. Dodaj wywołanie metody DeleteFamilyItemAsync w metodzie 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();
    }
    

Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie usunięto element usługi Azure Cosmos.You have successfully deleted an Azure Cosmos item.

Krok 10. Usuwanie bazy danychStep 10: Delete the database

Teraz usuniemy naszą bazę danych.Now we will delete our database. Usunięcie utworzonej bazy danych spowoduje usunięcie bazy danych i wszystkich zasobów podrzędnych (kontenerów, elementów, procedur składowanych, funkcji zdefiniowanych przez użytkownika i wyzwalaczy).Deleting the created database will remove the database and all children resources (containers, items, and any stored procedures, user-defined functions, and triggers). Usuniemy także wystąpienie klasy CosmosClient.We will also dispose of the CosmosClient instance.

  1. Skopiuj i wklej metodę DeleteDatabaseAndCleanupAsync poniżej metody DeleteFamilyItemAsync .Copy and paste the DeleteDatabaseAndCleanupAsync method below 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. Dodaj wywołanie metody DeleteDatabaseAndCleanupAsync w metodzie 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();
    }
    

Naciśnij klawisz F5, aby uruchomić aplikację.Select F5 to run your application.

Gratulacje!Congratulations! Pomyślnie usunięto bazę danych usługi Azure Cosmos.You have successfully deleted an Azure Cosmos database.

Krok 11. Uruchamianie całej aplikacji konsolowej C#Step 11: Run your C# console application all together!

Naciśnij klawisz F5 w programie Visual Studio, aby skompilować i uruchomić aplikację w trybie debugowania.Select F5 in Visual Studio to build and run the application in debug mode.

Wszystkie dane wyjściowe aplikacji powinny zostać wyświetlone w oknie konsoli.You should see the output of your entire app in a console window. Dane wyjściowe będą pokazywały wyniki dodanych zapytań i powinny odpowiadać poniższemu przykładowemu tekstowi.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.

Gratulacje!Congratulations! Pomyślnie ukończono ten samouczek i utworzono działającą aplikację konsolową C#.You've completed the tutorial and have a working C# console application!

Pobieranie kompletnego rozwiązania samouczkaGet the complete tutorial solution

Jeśli nie masz czasu na ukończenie tego samouczka lub po prostu chcesz pobrać przykłady kodu, możesz uzyskać je w serwisie 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.

Aby skompilować rozwiązanie GetStarted, niezbędne są następujące elementy:To build the GetStarted solution, you will need the following:

Aby przywrócić odwołania do zestawu SDK dla platformy .NET usługi Azure Cosmos DB w programie Visual Studio, kliknij prawym przyciskiem myszy rozwiązanie GetStarted w Eksploratorze rozwiązań, a następnie kliknij polecenie Przywróć pakiety 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. Następnie w pliku App.config zaktualizuj wartości EndPointUri i PrimaryKey zgodnie z opisem w kroku Łączenie się z kontem usługi 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.

To wszystko — skompiluj projekt i gotowe!That's it, build it, and you're on your way!

Następne krokiNext steps