Öğretici: Azure Cosmos DB SQL API hesabındaki verileri yönetmek için bir .NET konsol uygulaması oluşturmaTutorial: Build a .NET console app to manage data in Azure Cosmos DB SQL API account

Uygulama hedefı: SQL API

SQL API Başlarken öğreticisine Azure Cosmos DB hoş geldiniz.Welcome to the Azure Cosmos DB SQL API get started tutorial. Bu öğreticiyi uyguladıktan sonra, Azure Cosmos DB kaynaklarını oluşturan ve sorgulayan bir konsol uygulamasına sahip olacaksınız.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

Bu öğretici, Azure Cosmos DB .NET SDK 'sının3,0 veya sonraki bir sürümünü kullanır.This tutorial uses version 3.0 or later of the Azure Cosmos DB .NET SDK. .NET Framework veya .NET Coreile çalışabilirsiniz.You can work with .NET Framework or .NET Core.

Bu öğreticinin içindekiler:This tutorial covers:

  • Azure Cosmos hesabı oluşturma ve bu hesaba bağlanmaCreating and connecting to an Azure Cosmos account
  • Visual Studio 'da projenizi yapılandırmaConfiguring your project in Visual Studio
  • Veritabanı ve kapsayıcı oluşturmaCreating a database and a container
  • Kapsayıcıya öğeleri eklemeAdding items to the container
  • Kapsayıcıyı sorgulamaQuerying the container
  • Öğe üzerinde oluşturma, okuma, güncelleştirme ve silme (CRUD) işlemleri gerçekleştiriliyorPerforming create, read, update, and delete (CRUD) operations on the item
  • Veritabanını silmeDeleting the database

Zamanınız yok mu?Don't have time? Endişelenmeyin!Don't worry! Eksiksiz çözümü GitHub'da bulabilirsiniz.The complete solution is available on GitHub. Hızlı yönergeler için Tüm öğretici çözümünü al bölümüne atlayın.Jump to the Get the complete tutorial solution section for quick instructions.

Şimdi başlayalım!Now let's get started!

ÖnkoşullarPrerequisites

1. Adım: Azure Cosmos DB hesabı oluşturmaStep 1: Create an Azure Cosmos DB account

Bir Azure Cosmos DB hesabı oluşturalım.Let's create an Azure Cosmos DB account. Kullanmak istediğiniz bir hesabınız zaten varsa, bu bölümü atlayın.If you already have an account you want to use, skip this section. Azure Cosmos DB öykünücüsünü kullanmak için, öykünücüyü ayarlamak üzere Azure Cosmos DB öykünücüsü ' nde bulunan adımları izleyin.To use the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator. 2. Adım: Visual Studio projenizi ayarlamabölümüne atlayın.Then skip ahead to Step 2: Set up your Visual Studio project.

  1. Azure portal menüsünde veya giriş sayfasında, kaynak oluştur' u seçin.From the Azure portal menu or the Home page, select Create a resource.

  2. Yeni sayfasında, Azure Cosmos DB bulun ve seçin.On the New page, search for and select Azure Cosmos DB.

  3. Azure Cosmos DB sayfasında Oluştur' u seçin.On the Azure Cosmos DB page, select Create.

  4. Azure Cosmos DB Hesabı Oluştur sayfasında, yeni Azure Cosmos hesabına yönelik temel ayarları girin.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    AyarSetting DeğerValue AçıklamaDescription
    AbonelikSubscription Abonelik adıSubscription name Bu Azure Cosmos hesabı için kullanmak istediğiniz Azure aboneliğini seçin.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Kaynak GrubuResource Group Kaynak grubu adıResource group name Bir kaynak grubu seçin veya Yeni oluştur seçeneğini belirleyin ve yeni kaynak grubu için benzersiz bir ad girin.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Hesap AdıAccount Name Benzersiz bir adA unique name Azure Cosmos hesabınızı tanımlayan bir ad girin.Enter a name to identify your Azure Cosmos account. URI’nizi oluşturmak için sağladığınız ada documents.azure.com ekleneceği için benzersiz bir ad kullanın.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Ad yalnızca küçük harf, sayı ve kısa çizgi (-) karakterini içerebilir.The name can only contain lowercase letters, numbers, and the hyphen (-) character. 3-44 karakter uzunluğunda olmalıdır.It must be between 3-44 characters in length.
    APIAPI Oluşturulacak hesap türüThe type of account to create SQL söz dizimini kullanarak belge veritabanı ve sorgusu oluşturmak için Cekirdek (SQL) seçeneğini belirleyin.Select Core (SQL) to create a document database and query by using SQL syntax.

    API, oluşturulacak hesap türünü belirler.The API determines the type of account to create. Azure Cosmos DB beş API sağlar: belge verileri için çekirdek (SQL) ve MongoDB, Graf verileri için Gremlin, Azure tablosu ve Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Şu anda, her API için farklı bir hesap oluşturmanız gerekir.Currently, you must create a separate account for each API.
    Kapasite moduCapacity mode Sağlanan aktarım hızı veya sunucusuzProvisioned throughput or Serverless Sağlanan aktarım hızı modunda bir hesap oluşturmak için sağlanan aktarım hızı ' nı seçin.Select Provisioned throughput to create an account in provisioned throughput mode. Sunucusuz modda bir hesap oluşturmak Için sunucusuz ' ı seçin.Select Serverless to create an account in serverless mode.
    Ücretsiz Katman İndirimi UygulaApply Free Tier Discount Uygula veya UygulaApply or Do not apply Azure Cosmos DB ücretsiz katman sayesinde ilk 400 RU/sn ve 5 GB depolama alanını hesapta ücretsiz olarak alırsınız.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Ücretsiz katmanhakkında daha fazla bilgi edinin.Learn more about free tier.
    KonumLocation Kullanıcılarınıza en yakın bölgeThe region closest to your users Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin.Select a geographic location to host your Azure Cosmos DB account. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.Use the location that is closest to your users to give them the fastest access to the data.
    Hesap TürüAccount Type Üretim veya üretim dışıProduction or Non-Production Hesap bir üretim iş yükü için kullanılacaksa, Üretim ' ı seçin.Select Production if the account will be used for a production workload. Hesap üretim dışı, örneğin geliştirme, test, QA veya hazırlama için kullanılacaksa, Üretim dışı seçeneğini belirleyin.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Bu, Portal deneyimini denetleyen ancak temel alınan Azure Cosmos DB hesabını etkilemeyen bir Azure Kaynak etiketi ayarıdır.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. Bu değeri dilediğiniz zaman değiştirebilirsiniz.You can change this value anytime.

    Not

    Azure aboneliği başına en fazla bir ücretsiz katman Azure Cosmos DB hesabınız olabilir ve hesabı oluştururken kabul etmeniz gerekir.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Ücretsiz katman indirimi uygulama seçeneğini görmüyorsanız bu, abonelikteki başka bir hesabın ücretsiz katmanla zaten etkinleştirildiği anlamına gelir.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Not

    Kapasite modu olarak sunucusuz ' i seçerseniz aşağıdaki seçenekler kullanılamaz:The following options are not available if you select Serverless as the Capacity mode:

    • Ücretsiz Katman İndirimi UygulaApply Free Tier Discount
    • Coğrafi yedeklilikGeo-redundancy
    • Birden Çok Bölgeli YazmalarMulti-region Writes

    Azure Cosmos DB için yeni hesap sayfası

  5. Gözden geçir ve oluştur’u seçin.Select Review + create. ve Etiketler bölümlerini atlayabilirsiniz.You can skip the Network and Tags sections.

  6. Hesap ayarlarını gözden geçirip Oluştur seçeneğini belirleyin.Review the account settings, and then select Create. Hesabın oluşturulması birkaç dakika sürer.It takes a few minutes to create the account. Portal sayfasında Dağıtımınız tamamlandı iletisinin görüntülenmesini bekleyin.Wait for the portal page to display Your deployment is complete.

    Azure portaldaki Bildirimler bölmesi

  7. Azure Cosmos DB hesabı sayfasına gitmek için Kaynağa git seçeneğini belirleyin.Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB hesabı sayfası

2. Adım: Visual Studio projenizi ayarlamaStep 2: Set up your Visual Studio project

  1. Visual Studio 'Yu açın ve Yeni proje oluştur' u seçin.Open Visual Studio and select Create a new project.

  2. Yeni proje oluştur bölümünde C# için konsol uygulaması (.NET Framework) öğesini seçin ve ardından İleri' yi seçin.In Create a new project, choose Console App (.NET Framework) for C#, then select Next.

  3. Projenizin Cosmosgettingstartedöğreticisini adlandırın ve Oluştur' u seçin.Name your project CosmosGettingStartedTutorial, and then select Create.

    Projenizi yapılandırma

  4. Çözüm Gezgini, Visual Studio çözümünüzün altındaki yeni konsol uygulamanıza sağ tıklayın ve NuGet Paketlerini Yönet' i seçin.In the Solution Explorer, right-click your new console application, which is under your Visual Studio solution, and select Manage NuGet Packages.

  5. NuGet Paket Yöneticisi'Nde, Araştır ' ı seçin ve Microsoft. Azure. Cosmos için arama yapın.In the NuGet Package Manager, select Browse and search for Microsoft.Azure.Cosmos. Microsoft. Azure. Cosmos öğesini seçin ve yüklemeyi seçin.Choose Microsoft.Azure.Cosmos and select Install.

    Azure Cosmos DB Istemci SDK 'Sı için NuGet 'i yükler

    Azure Cosmos DB SQL API'si İstemci Kitaplığının paket kimliği Microsoft Azure Cosmos DB İstemci Kitaplığı’dır.The package ID for the Azure Cosmos DB SQL API Client Library is Microsoft Azure Cosmos DB Client Library.

Harika!Great! Kurulumu tamamladığımıza göre, biraz kod yazmaya başlayalım.Now that we finished the setup, let's start writing some code. Bu öğreticinin tamamlanan projesi için bkz. Azure Cosmos DB kullanarak .NET konsol uygulaması geliştirme.For the completed project of this tutorial, see Developing a .NET console app using Azure Cosmos DB.

3. Adım: Azure Cosmos DB hesabına bağlanmaStep 3: Connect to an Azure Cosmos DB account

  1. Program. cs dosyasındaki C# uygulamanızın başındaki başvuruları şu başvurularla değiştirin: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. Bu sabitleri ve değişkenleri Program sınıfınıza ekleyin.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";
    }
    

    Not

    Önceki .NET SDK sürümü hakkında bilginiz varsa , hüküm ve belge hakkında bilgi sahibi olabilirsiniz.If you're familiar with the previous version of the .NET SDK, you may be familiar with the terms collection and document. Azure Cosmos DB birden çok API modelini desteklediğinden, .NET SDK 'nın 3,0 sürümü genel terimler kapsayıcısını ve öğesini kullanır.Because Azure Cosmos DB supports multiple API models, version 3.0 of the .NET SDK uses the generic terms container and item. Kapsayıcı bir koleksiyon, grafik veya tablo olabilir.A container can be a collection, graph, or table. Bir öğe bir belge, Kenar/köşe veya satır olabilir ve bir kapsayıcı içindeki içeriktir.An item can be a document, edge/vertex, or row, and is the content inside a container. Daha fazla bilgi için bkz. Azure Cosmos DB veritabanları, kapsayıcılar ve öğelerle çalışma.For more information, see Work with databases, containers, and items in Azure Cosmos DB.

  3. Azure portalını açın.Open the Azure portal. Azure Cosmos DB hesabınızı bulun ve ardından anahtarlar' ı seçin.Find your Azure Cosmos DB account, and then select Keys.

    Azure portal Azure Cosmos DB anahtarları al

  4. Program. cs' de, <your endpoint URL> URI değeri ile değiştirin.In Program.cs, replace <your endpoint URL> with the value of URI. <your primary key> Birincil anahtar değeriyle değiştirin.Replace <your primary key> with the value of PRIMARY KEY.

  5. Main yönteminin altında, yeni bir zaman uyumsuz görev ekleyin, bu, yeni bir örneği oluşturur 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);
    }
    

    Azure Cosmos DB kaynaklarında çalışan yöntemleri çağıran giriş noktası olarak Getstarteddemoasync kullanıyoruz.We use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

  6. Ana yönteminizin Getstarteddemoasync görevi çalıştırmak için aşağıdaki kodu ekleyin.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. Main yöntemi özel durumları yakalar ve bunları konsola yazar.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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

    Konsol şu iletiyi görüntüler: demo sonu, çıkmak için herhangi bir tuşa basın.The console displays the message: End of demo, press any key to exit. Bu ileti, uygulamanızın Azure Cosmos DB bağlantı yaptığını onaylar.This message confirms that your application made a connection to Azure Cosmos DB. Ardından konsol penceresini kapatabilirsiniz.You can then close the console window.

Tebrikler!Congratulations! Bir Azure Cosmos DB hesabına başarıyla bağlandınız.You've successfully connected to an Azure Cosmos DB account.

4. Adım: Veritabanı oluşturmaStep 4: Create a database

Veritabanı, kapsayıcılar genelinde bölümlenmiş öğelerin mantıksal bir kapsayıcısıdır.A database is the logical container of items partitioned across containers. CreateDatabaseIfNotExistsAsync CreateDatabaseAsync CosmosClient sınıfının ya da yöntemi bir veritabanı oluşturabilir.Either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync method of the CosmosClient class can create a database.

  1. Yöntemi kopyalayın ve CreateDatabaseAsync yönteminin altına yapıştırın 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``FamilyDatabasezaten mevcut değilse, bu kimliği alandan BELIRTILEN kimliğe sahip yeni bir veritabanı oluşturur 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. Yeni eklediğiniz Createdatabaseasync yöntemini çağırmak için CosmosClient örneklediğinizde aşağıdaki kodu kopyalayın ve yapıştırın.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();
    }
    

    Programınız. cs , uç nokta ve birincil anahtarınızla doldurulmuş olarak şöyle görünmelidir.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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

    Not

    Bir "503 hizmeti kullanılamayan özel durum" hatası alırsanız, doğrudan bağlantı modu için gerekli bağlantı noktaları güvenlik duvarı tarafından engelleniyor olabilir.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. Bu sorunu onarmak için gerekli bağlantı noktalarını açın ya da aşağıdaki kodda gösterildiği gibi ağ geçidi modu bağlantısını kullanın: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
             });
    

Tebrikler!Congratulations! Azure Cosmos veritabanını başarıyla oluşturdunuz.You've successfully created an Azure Cosmos database.

5. Adım: kapsayıcı oluşturmaStep 5: Create a container

Uyarı

Yöntemi, CreateContainerIfNotExistsAsync fiyatlandırma etkilerine sahip yeni bir kapsayıcı oluşturur.The method CreateContainerIfNotExistsAsync creates a new container, which has pricing implications. Daha fazla ayrıntı için lütfen fiyatlandırmasayfamızı ziyaret edin.For more details, please visit our pricing page.

Bir kapsayıcı, sınıfında Createcontainerifnotexistsasync veya Createcontainsilinebilir Sync yöntemi kullanılarak oluşturulabilir CosmosDatabase .A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync method in the CosmosDatabase class. Bir kapsayıcı, JavaScript 'te, örneğin saklı yordamlar, Kullanıcı tanımlı işlevler ve tetikleyiciler gibi öğeler (SQL API 'SI ise JSON belgeleri) ve ilişkili sunucu tarafı uygulama mantığını içerir.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. Yöntemi kopyalayın ve CreateContainerAsync yönteminin altına yapıştırın CreateDatabaseAsync .Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. CreateContainerAsync``FamilyContainer containerId özellik tarafından bölümlenmiş alandan belirtilen kimliği kullanarak, zaten mevcut DEĞILSE, kimlik ile yeni bir kapsayıcı oluşturur 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. Daha önce eklediğiniz CreateContainer yöntemini çağırmak için CosmosClient örneklendirmeniz gereken kodu kopyalayın ve yapıştırın.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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! Azure Cosmos kapsayıcısını başarıyla oluşturdunuz.You've successfully created an Azure Cosmos container.

6. Adım: kapsayıcıya öğe eklemeStep 6: Add items to the container

Sınıfın Createitemasync yöntemi CosmosContainer bir öğe oluşturabilir.The CreateItemAsync method of the CosmosContainer class can create an item. SQL API 'sini kullanırken öğeler, Kullanıcı tanımlı rastgele JSON içeriği olan belgeler olarak yansıtılacaktır.When using the SQL API, items are projected as documents, which are user-defined arbitrary JSON content. Artık Azure Cosmos kapsayıcınıza bir öğe ekleyebilirsiniz.You can now insert an item into your Azure Cosmos container.

İlk olarak, Family Bu örnekteki Azure Cosmos db içinde depolanan nesneleri temsil eden bir sınıf oluşturalım.First, let's create a Family class that represents objects stored within Azure Cosmos DB in this sample. Ayrıca Parent , Child Pet Address içinde kullanılan alt sınıflar Family da oluşturacağız.We'll also create Parent, Child, Pet, Address subclasses that are used within Family. Öğe Id JSON içinde olarak seri hale getirilmiş bir özelliğe sahip olmalıdır id .The item must have an Id property serialized as id in JSON.

  1. Yeni öğe Ekle' yi açmak için CTRL + SHIFT + A ' yı seçin.Select Ctrl+Shift+A to open Add New Item. Projenize yeni bir sınıf ekleyin Family.cs .Add a new class Family.cs to your project.

    Projeye yeni bir Family. cs sınıfı ekleme ekranının ekran görüntüsü

  2. ,,, Family Parent Child Pet Ve Address sınıfını kopyalayıp içine yapıştırın 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. Program. cs' ye geri döndüğünüzde, yönteminizi AddItemsToContainerAsync uyguladıktan sonra yöntemi ekleyin 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);
        }
    }
    

    Kod, aynı KIMLIĞE sahip bir öğenin zaten mevcut olmadığından emin olmak için kontrol eder.The code checks to make sure an item with the same ID doesn't already exist. Her biri bir ve Wakefield ailesi için olmak üzere iki öğe ekleyeceğiz.We'll insert two items, one each for the Andersen Family and the Wakefield Family.

  4. Yöntemine bir çağrı ekleyin AddItemsToContainerAsync 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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! İki Azure Cosmos öğesini başarıyla oluşturdunuz.You've successfully created two Azure Cosmos items.

7. Adım: Azure Cosmos DB kaynaklarını sorgulamaStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB, her bir kapsayıcıda depolanan JSON belgeleri için zengin sorguların gerçekleştirilmesini destekler.Azure Cosmos DB supports rich queries against JSON documents stored in each container. Daha fazla bilgi için bkz. SQL sorgularıyla çalışmayabaşlama.For more information, see Getting started with SQL queries. Aşağıdaki örnek kod, önceki adımda eklediğimiz öğelerde bir sorgunun nasıl çalıştırılacağını gösterir.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Yönteminden QueryItemsAsync sonra yöntemi kopyalayıp yapıştırın 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. Yöntemine bir çağrı ekleyin QueryItemsAsync 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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! Azure Cosmos kapsayıcısını başarıyla sorguladınız.You've successfully queried an Azure Cosmos container.

8. Adım: JSON öğesini değiştirmeStep 8: Replace a JSON item

Artık Azure Cosmos DB bir öğeyi güncelleştireceğiz.Now, we'll update an item in Azure Cosmos DB. IsRegistered Family Alt öğelerinden birinin ve öğelerinin özelliğini değiştireceksiniz Grade .We'll change the IsRegistered property of the Family and the Grade of one of the children.

  1. Yönteminden ReplaceFamilyItemAsync sonra yöntemi kopyalayıp yapıştırın 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. Yöntemine bir çağrı ekleyin ReplaceFamilyItemAsync 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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! Azure Cosmos öğesini başarıyla değiştirdiniz.You've successfully replaced an Azure Cosmos item.

9. Adım: öğeyi silmeStep 9: Delete item

Artık Azure Cosmos DB bir öğeyi sileceğiz.Now, we'll delete an item in Azure Cosmos DB.

  1. Yönteminden DeleteFamilyItemAsync sonra yöntemi kopyalayıp yapıştırın 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. Yöntemine bir çağrı ekleyin DeleteFamilyItemAsync 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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! Azure Cosmos öğesini başarıyla sildiniz.You've successfully deleted an Azure Cosmos item.

10. Adım: Veritabanını silmeStep 10: Delete the database

Şimdi veritabanımızı sileceğiz.Now we'll delete our database. Oluşturulan veritabanı silindiğinde, veritabanı ve tüm alt kaynaklar kaldırılır.Deleting the created database removes the database and all children resources. Kaynaklar kapsayıcılar, öğeler ve saklı yordamlar, Kullanıcı tanımlı işlevler ve Tetikleyiciler içerir.The resources include containers, items, and any stored procedures, user-defined functions, and triggers. Örneği de atıyoruz CosmosClient .We also dispose of the CosmosClient instance.

  1. Yönteminden DeleteDatabaseAndCleanupAsync sonra yöntemi kopyalayıp yapıştırın 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. Yöntemine bir çağrı ekleyin DeleteDatabaseAndCleanupAsync 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. Uygulamanızı çalıştırmak için F5 ' i seçin.Select F5 to run your application.

Tebrikler!Congratulations! Azure Cosmos veritabanını başarıyla sildiniz.You've successfully deleted an Azure Cosmos database.

11. Adım: C# konsol uygulamanızın tümünü çalıştırın!Step 11: Run your C# console application all together!

Visual Studio 'da F5 ' i seçerek uygulamayı derleyip hata ayıklama modunda çalıştırın.Select F5 in Visual Studio to build and run the application in debug mode.

Tüm uygulamanızın çıkışını bir konsol penceresinde görmeniz gerekir.You should see the output of your entire app in a console window. Çıktı, eklediğimiz sorguların sonuçlarını gösterir.The output shows the results of the queries we added. Aşağıdaki örnek metinle eşleşmelidir.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.

Tebrikler!Congratulations! Bu öğreticiyi tamamladınız ve çalışan bir C# konsol uygulamasına sahipsiniz!You've completed the tutorial and have a working C# console application!

Tam öğretici çözümünü edininGet the complete tutorial solution

Bu öğreticideki adımları tamamlamaya yönelik bir zaman yoksa veya yalnızca kod örneklerini indirmek istiyorsanız, indirebilirsiniz.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.

Çözümü oluşturmak için GetStarted aşağıdaki önkoşullara sahip olmanız gerekir:To build the GetStarted solution, you need the following prerequisites:

Başvuruları Visual Studio 'daki Azure Cosmos DB .NET SDK 'sına geri yüklemek için, Çözüm Gezgini çözüme sağ tıklayın ve ardından NuGet paketlerini geri yükle' yi seçin.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. Sonra, App.config dosyasında, EndPointUri ve PrimaryKey değerlerini Adım 3: bir Azure Cosmos DB hesabına bağlanmabölümünde açıklandığı gibi güncelleştirin.Next, in the App.config file, update the EndPointUri and PrimaryKey values as described in Step 3: Connect to an Azure Cosmos DB account.

Bu, derdir ve sizin de sizin.That's it, build it, and you're on your way!

Sonraki adımlarNext steps