Samouczek: tworzenie aplikacji konsolowej platformy .NET do zarządzania danymi na koncie interfejsu API SQL usługi Azure Cosmos DB

  • Artykuł
  • Czas czytania: 19 min

DOTYCZY: INTERFEJS API SQL

Witamy w samouczku rozpoczynania pracy z interfejsem API SQL usługi Azure Cosmos DB. W ramach tego samouczka zostanie utworzona aplikacja konsolowa, która tworzy zasoby usługi Azure Cosmos DB i wykonuje dla nich zapytania.

W tym samouczku jest używana wersja 3.0 lub nowsza zestawu .NET SDK usługi Azure Cosmos DB i platformy .NET 6.

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

  • Tworzenie konta usługi Azure Cosmos i łączenie się z nim
  • Konfigurowanie projektu w programie Visual Studio
  • Tworzenie bazy danych i kontenera
  • Dodawanie elementów do kontenera
  • Wykonywanie zapytań względem kontenera
  • Wykonywanie operacji tworzenia, odczytu, aktualizacji i usuwania (CRUD) na elemencie
  • Usuwanie bazy danych

Nie masz czasu? Nie martw się! Kompletne rozwiązanie jest dostępne w witrynie GitHub. Przeskocz do sekcji Pobieranie kompletnego rozwiązania samouczka, aby uzyskać krótkie instrukcje.

Teraz do dzieła!

Wymagania wstępne

Aktywne konto platformy Azure. Jeśli go nie masz, możesz zarejestrować się w celu utworzenia bezpłatnego konta.

Możesz bezpłatnie wypróbować usługę Azure Cosmos DB bez subskrypcji platformy Azure i bez zobowiązania. Alternatywnie możesz utworzyć konto warstwy Bezpłatna usługi Azure Cosmos DB z pierwszymi 1000 RU/s i 25 GB miejsca do magazynowania bezpłatnie. Możesz również użyć emulatora usługi Azure Cosmos DB z identyfikatorem URI .https://localhost:8081 Aby uzyskać klucz do użycia z emulatorem, zobacz Authenticating requests (Uwierzytelnianie żądań).

Najnowsza wersja programu Visual Studio z pakietem roboczym Programowanie na platformie Azure. Możesz rozpocząć pracę z bezpłatnymśrodowiskiem IDE Visual Studio Community. Włącz obciążenie Programowanie na platformie Azure podczas konfigurowania programu Visual Studio.

Krok 1. Tworzenie konta usługi Azure Cosmos DB

Utwórzmy konto usługi Azure Cosmos DB. Jeśli masz już konto, którego chcesz użyć, pomiń tę sekcję. Aby użyć emulatora usługi Azure Cosmos DB, wykonaj kroki opisane w temacie Emulator usługi Azure Cosmos DB , aby skonfigurować emulator. Następnie przejdź do kroku 2. Konfigurowanie projektu programu Visual Studio.

  1. W menu witryny Azure Portal lub na stronie głównej wybierz pozycję Utwórz zasób.

  2. Na stronie Nowa wyszukaj i wybierz usługę Azure Cosmos DB.

  3. Na stronie opcji Wybierz interfejs API wybierz opcję Utwórz w sekcji Core (SQL) — Zalecane . Usługa Azure Cosmos DB oferuje pięć interfejsów API: Core (SQL) i MongoDB dla danych dokumentów, Gremlin dla danych grafów, Azure Table i Cassandra. Obecnie dla każdego interfejsu API należy utworzyć oddzielne konto. Dowiedz się więcej o interfejsie API SQL.

  4. Na stronie Tworzenie konta usługi Azure Cosmos DB wprowadź podstawowe ustawienia nowego konta usługi Azure Cosmos.

    Ustawienie Wartość Opis
    Subskrypcja Nazwa subskrypcji Wybierz subskrypcję platformy Azure, której chcesz użyć dla tego konta usługi Azure Cosmos.
    Grupa zasobów Nazwa grupy zasobów Wybierz grupę zasobów lub wybierz pozycję Utwórz nową, a następnie wprowadź unikatową nazwę nowej grupy zasobów.
    Nazwa konta Unikatowa nazwa Wprowadź nazwę, która będzie identyfikować konto usługi Azure Cosmos. Ponieważ adres documents.azure.com jest dołączany do podanej nazwy w celu utworzenia identyfikatora URI, użyj unikatowej nazwy.

    Nazwa może zawierać tylko małe litery, cyfry i znaki łącznika (-). Musi mieć długość od 3 do 44 znaków.
    Lokalizacja Region najbliżej Twoich użytkowników Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB. Użyj lokalizacji znajdującej się najbliżej Twoich użytkowników, aby zapewnić im najszybszy dostęp do danych.
    Tryb wydajności Aprowizowana przepływność lub bezserwerowa Wybierz pozycję Aprowizowana przepływność , aby utworzyć konto w trybie aprowizowanej przepływności . Wybierz pozycję Bezserwerowa , aby utworzyć konto w trybie bezserwerowym .
    Stosowanie rabatu za bezpłatną warstwę usługi Azure Cosmos DB Zastosuj lub nie zastosuj W przypadku warstwy Bezpłatna usługi Azure Cosmos DB uzyskasz pierwsze 1000 RU/s i 25 GB miejsca do magazynowania bezpłatnie na koncie. Dowiedz się więcej o warstwie Bezpłatna.

    Uwaga

    W ramach jednej subskrypcji platformy Azure można korzystać z maksymalnie jednego konta usługi Azure Cosmos DB w warstwie Bezpłatna. Tę opcję należy wybrać podczas tworzenia konta. Jeśli opcja zastosowania rabatu na podstawie warstwy Bezpłatna nie jest widoczna, inne konto w subskrypcji już korzysta z warstwy Bezpłatna.

    Strona nowego konta usługi Azure Cosmos DB

  5. Na karcie Dystrybucja globalna skonfiguruj następujące szczegóły. Możesz pozostawić wartości domyślne dla tego przewodnika Szybki start:

    Ustawienie Wartość Opis
    Nadmiarowość geograficzna Wyłącz Włącz lub wyłącz dystrybucję globalną na koncie, łącząc region z regionem pary. Później możesz dodać więcej regionów do swojego konta.
    Moduły zapisujące obsługujące wiele regionów Wyłącz Funkcja zapisu w wielu regionach umożliwia wykorzystanie aprowizowanej przepływności dla baz danych i kontenerów na całym świecie.

    Uwaga

    Następujące opcje nie są dostępne w przypadku wybrania opcji Bezserwerowa jako tryb pojemności:

    • Zastosuj rabat na podstawie warstwy Bezpłatna
    • Nadmiarowość geograficzna
    • Moduły zapisujące obsługujące wiele regionów

  6. Opcjonalnie możesz skonfigurować więcej szczegółów na następujących kartach:

  7. Wybierz pozycję Przejrzyj i utwórz.

  8. Przejrzyj ustawienia konta, a następnie wybierz pozycję Utwórz. Utworzenie konta trwa kilka minut. Poczekaj na wyświetlenie komunikatu Wdrożenie zostało ukończone na stronie portalu.

    Okienko Powiadomienia w witrynie Azure Portal

  9. Wybierz pozycję Przejdź do zasobu, aby przejść do strony konta usługi Azure Cosmos DB.

    Strona konta usługi Azure Cosmos DB

Krok 2. Konfigurowanie projektu programu Visual Studio

  1. Otwórz program Visual Studio i wybierz pozycję Utwórz nowy projekt.

  2. W obszarze Utwórz nowy projekt wybierz pozycję Aplikacja konsolowa dla języka C#, a następnie wybierz pozycję Dalej.

  3. Nadaj projektowi nazwę CosmosGettingStartedTutorial, a następnie wybierz pozycję Utwórz.

  4. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy nową aplikację konsolową, która znajduje się w rozwiązaniu programu Visual Studio, a następnie wybierz pozycję Zarządzaj pakietami NuGet.

  5. W Menedżerze pakietów NuGet wybierz pozycję Przeglądaj i wyszukaj ciąg Microsoft.Azure.Cosmos. Wybierz pozycję Microsoft.Azure.Cosmos i wybierz pozycję Zainstaluj.

    Instalowanie pakietu NuGet dla zestawu SDK klienta usługi Azure Cosmos DB

    Identyfikator pakietu biblioteki klienta interfejsu API SQL w usłudze Azure Cosmos DB to Microsoft Azure Cosmos DB Client Library.

Świetnie! Teraz, po zakończeniu konfigurowania, zacznijmy pisanie kodu. Aby zapoznać się z ukończonym projektem tego samouczka, zobacz Tworzenie aplikacji konsolowej platformy .NET przy użyciu usługi Azure Cosmos DB.

Krok 3. Łączenie się z kontem usługi Azure Cosmos DB

  1. Zastąp odwołania na początku aplikacji C# w pliku Program.cs następującymi odwołaniami:

    using System;
using System.Threading.Tasks;
using System.Configuration;
using System.Collections.Generic;
using System.Net;
using Microsoft.Azure.Cosmos;

  2. Dodaj te stałe i zmienne do Program klasy.

    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";
}

    Uwaga

    Jeśli znasz poprzednią wersję zestawu .NET SDK, możesz zapoznać się z kolekcją terminów i dokumentem. Ponieważ usługa Azure Cosmos DB obsługuje wiele modeli interfejsu API, wersja 3.0 zestawu .NET SDK używa ogólnych terminów kontenera i elementu. Kontenerem może być kolekcja, graf lub tabela. Element może być dokumentem, krawędzią/wierzchołkiem lub wierszem i jest zawartością wewnątrz kontenera. Aby uzyskać więcej informacji, zobacz Praca z bazami danych, kontenerami i elementami w usłudze Azure Cosmos DB.

  3. Otwórz witrynę Azure Portal. Znajdź konto usługi Azure Cosmos DB, a następnie wybierz pozycję Klucze.

    Pobieranie kluczy usługi Azure Cosmos DB z Azure Portal

  4. W obszarze Program.cs zastąp <your endpoint URL> wartość identyfikatora URI. Zastąp <your primary key> ciąg wartością KLUCZ PODSTAWOWY.

  5. Poniżej metody Main dodaj nowe zadanie asynchroniczne o nazwie GetStartedDemoAsync, które tworzy wystąpienie nowego CosmosClientelementu .

    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);
}

    Używamy metody GetStartedDemoAsync jako punktu wejścia, który wywołuje metody działające na zasobach usługi Azure Cosmos DB.

  6. Dodaj następujący kod w celu uruchomienia zadania asynchronicznego GetStartedDemoAsync w metodzie Main. Metoda Main przechwytuje wyjątki i wyświetla je w konsoli.

    public static async Task Main(string[] args)
{
    try
    {
        Console.WriteLine("Beginning operations...\n");
        Program p = new Program();
        await p.GetStartedDemoAsync();

    }
    catch (CosmosException cosmosException)
    {
        Console.WriteLine("Cosmos Exception with Status {0} : {1}\n", cosmosException.StatusCode, cosmosException);
    }
    catch (Exception e)
    {
        Console.WriteLine("Error: {0}", e);
    }
    finally
    {
        Console.WriteLine("End of demo, press any key to exit.");
        Console.ReadKey();
    }
}

  7. Wybierz klawisz F5, aby uruchomić aplikację.

    Konsola wyświetla komunikat: Koniec pokazu, naciśnij dowolny klawisz, aby zakończyć. Ten komunikat potwierdza, że aplikacja nawiązała połączenie z usługą Azure Cosmos DB. Następnie można zamknąć okno konsoli.

Gratulacje! Pomyślnie nawiązaliśmy połączenie z kontem usługi Azure Cosmos DB.

Krok 4. Tworzenie bazy danych

Baza danych jest logicznym kontenerem elementów podzielonym na partycje w kontenerach. CreateDatabaseIfNotExistsAsync Metoda lub CreateDatabaseAsync klasy CosmosClient może utworzyć bazę danych.

  1. Skopiuj i wklej metodę CreateDatabaseAsync poniżej GetStartedDemoAsync metody .

    /// <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 Tworzy nową bazę danych o identyfikatorze FamilyDatabase , jeśli jeszcze nie istnieje, która ma identyfikator określony z databaseId pola. Na potrzeby tego pokazu tworzymy bazę danych w ramach ćwiczenia, ale w przypadku aplikacji w środowisku produkcyjnym nie zaleca się wykonywania jej w ramach normalnego przepływu.

  2. Skopiuj i wklej poniższy kod, w którym utworzysz wystąpienie obiektu CosmosClient, aby wywołać właśnie dodaną metodę CreateDatabaseAsync .

    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();
}

    Twój program.cs powinien teraz wyglądać następująco, z wypełnionym punktem końcowym i kluczem podstawowym.

    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 cosmosException)
            {
                Console.WriteLine("Cosmos Exception with Status {0} : {1}\n", cosmosException.StatusCode, cosmosException);
            }
            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. Wybierz klawisz F5, aby uruchomić aplikację.

    Uwaga

    Jeśli wystąpi błąd "Wyjątek niedostępności usługi 503", możliwe, że wymagane porty dla trybu łączności bezpośredniej są blokowane przez zaporę. Aby rozwiązać ten problem, otwórz wymagane porty lub użyj łączności w trybie bramy, jak pokazano w poniższym kodzie:

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

Gratulacje! Pomyślnie utworzono bazę danych usługi Azure Cosmos.

Krok 5. Tworzenie kontenera

Ostrzeżenie

Metoda CreateContainerIfNotExistsAsync tworzy nowy kontener, który ma wpływ na ceny. Aby uzyskać więcej informacji, odwiedź naszą stronę cennika.

Kontener można utworzyć przy użyciu metody CreateContainerIfNotExistsAsync lub CreateContainerAsync w CosmosDatabase klasie . 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 procedur składowanych, funkcji zdefiniowanych przez użytkownika i wyzwalaczy.

  1. Skopiuj i wklej metodę CreateContainerAsync poniżej CreateDatabaseAsync metody . CreateContainerAsync Tworzy nowy kontener z identyfikatorem FamilyContainer , jeśli jeszcze nie istnieje, przy użyciu identyfikatora określonego containerId z pola partycjonowanego przez LastName właściwość. Na potrzeby tego pokazu tworzymy kontener w ramach ćwiczenia, ale w przypadku aplikacji w środowisku produkcyjnym nie zaleca się wykonywania go w ramach normalnego przepływu.

    /// <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.

    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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie utworzono kontener usługi Azure Cosmos.

Krok 6. Dodawanie elementów do kontenera

Metoda CosmosContainerCreateItemAsync klasy może utworzyć element. W przypadku korzystania z interfejsu API SQL elementy są projektowane jako dokumenty, które są dowolną zawartością JSON zdefiniowaną przez użytkownika. Teraz możesz wstawić element do kontenera usługi Azure Cosmos.

Najpierw utwórzmy klasę reprezentującą Family obiekty przechowywane w usłudze Azure Cosmos DB w tym przykładzie. Utworzymy Parentrównież podklasy , Child, Pet, Address używane w ramach klasy Family. Element musi mieć Id właściwość serializowaną tak jak id w formacie JSON.

  1. Naciśnij klawisze Ctrl+Shift+A, aby otworzyć polecenie Dodaj nowy element. Dodaj nową klasę Family.cs do projektu.

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

  2. Skopiuj i wklej klasę Family, Parent, Child, Peti Address do Family.csklasy .

    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. Po powrocie do pliku Program.cs dodaj metodę AddItemsToContainerAsync po metodzie CreateContainerAsync .

    /// <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);
    }
}

    Kod sprawdza, czy element o tym samym identyfikatorze jeszcze nie istnieje. Wstawimy dwa elementy, po jednym dla rodziny Andersena i rodziny Wakefield.

  4. Dodaj wywołanie metody AddItemsToContainerAsync w metodzie GetStartedDemoAsync.

    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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie utworzono dwa elementy usługi Azure Cosmos.

Krok 7. Wykonanie zapytania względem zasobów usługi Azure Cosmos DB

Usługa Azure Cosmos DB obsługuje zaawansowane zapytania względem dokumentów JSON przechowywanych w poszczególnych kontenerach. Aby uzyskać więcej informacji, zobacz Wprowadzenie do zapytań SQL. W następującym przykładowym kodzie pokazano, jak uruchomić zapytanie względem elementów wstawionych w poprzednim kroku.

  1. Skopiuj i wklej metodę QueryItemsAsync po metodzie AddItemsToContainerAsync .

    /// <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);
    using 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.

    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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie wykonano zapytanie dotyczące kontenera usługi Azure Cosmos.

Krok 8. Zastępowanie elementu JSON

Teraz zaktualizujemy element w usłudze Azure Cosmos DB. Zmienimy IsRegistered właściwość Family i Grade jednego z dzieci.

  1. Skopiuj i wklej metodę ReplaceFamilyItemAsync po metodzie QueryItemsAsync .

    /// <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.

    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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie zastąpiono element usługi Azure Cosmos.

Krok 9. Usuwanie elementu

Teraz usuniemy element w usłudze Azure Cosmos DB.

  1. Skopiuj i wklej metodę DeleteFamilyItemAsync po metodzie ReplaceFamilyItemAsync .

    /// <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.

    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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie usunięto element usługi Azure Cosmos.

Krok 10. Usuwanie bazy danych

Teraz usuniemy naszą bazę danych. Usunięcie utworzonej bazy danych powoduje usunięcie bazy danych i wszystkich zasobów podrzędnych. Zasoby obejmują kontenery, elementy i wszystkie procedury składowane, funkcje zdefiniowane przez użytkownika i wyzwalacze. Usuwamy CosmosClient również wystąpienie.

  1. Skopiuj i wklej metodę DeleteDatabaseAndCleanupAsync po metodzie DeleteFamilyItemAsync .

    /// <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.

    /// <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. Wybierz klawisz F5, aby uruchomić aplikację.

Gratulacje! Pomyślnie usunięto bazę danych usługi Azure Cosmos.

Krok 11. Uruchamianie całej aplikacji konsolowej C#

Naciśnij klawisz F5 w programie Visual Studio, aby skompilować i uruchomić aplikację w trybie debugowania.

Wszystkie dane wyjściowe aplikacji powinny zostać wyświetlone w oknie konsoli. Dane wyjściowe pokazują wyniki dodanych zapytań. Powinien on być zgodny z poniższym przykładowym tekstem.

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! Pomyślnie ukończono ten samouczek i utworzono działającą aplikację konsolową C#.

Pobieranie kompletnego rozwiązania samouczka

Jeśli nie masz czasu na wykonanie kroków opisanych w tym samouczku lub po prostu chcesz pobrać przykłady kodu, możesz go pobrać.

Do utworzenia GetStarted rozwiązania potrzebne są następujące wymagania wstępne:

Aby przywrócić odwołania do zestawu .NET SDK usługi Azure Cosmos DB w programie Visual Studio, kliknij prawym przyciskiem myszy rozwiązanie w Eksplorator rozwiązań, a następnie wybierz polecenie Przywróć pakiety NuGet. Następnie w pliku App.config zaktualizuj EndPointUri wartości i PrimaryKey zgodnie z opisem w sekcji Krok 3. Łączenie z kontem usługi Azure Cosmos DB.

To wszystko — skompiluj projekt i gotowe!

Następne kroki