자습서: .NET 콘솔 앱을 빌드하여 Azure Cosmos DB SQL API 계정에서 데이터 관리Tutorial: Build a .NET console app to manage data in Azure Cosmos DB SQL API account

적용 대상: SQL API

Azure Cosmos DB SQL API 시작 자습서를 시작합니다.Welcome to the Azure Cosmos DB SQL API get started tutorial. 이 자습서를 따라 하면 Azure Cosmos DB 리소스를 만들고 쿼리하는 콘솔 애플리케이션이 생깁니다.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

이 자습서에는 Azure Cosmos DB .NET SDK 버전 3.0 이상을 사용합니다.This tutorial uses version 3.0 or later of the Azure Cosmos DB .NET SDK. .NET Framework 또는 .NET Core로 작업할 수 있습니다.You can work with .NET Framework or .NET Core.

이 자습서에서는 다음 내용을 다룹니다.This tutorial covers:

  • Azure Cosmos 계정 만들기 및 연결Creating and connecting to an Azure Cosmos account
  • Visual Studio에서 프로젝트 구성Configuring your project in Visual Studio
  • 데이터베이스 및 컨테이너 만들기Creating a database and a container
  • 컨테이너에 항목 추가Adding items to the container
  • 컨테이너 쿼리Querying the container
  • 항목에 대한 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업 수행Performing create, read, update, and delete (CRUD) operations on the item
  • 데이터베이스 삭제Deleting the database

시간이 없으십니까?Don't have time? 염려하지 마십시오.Don't worry! GitHub에서 전체 솔루션을 사용할 수 있습니다.The complete solution is available on GitHub. 빠른 지침을 보려면 전체 자습서 솔루션 가져오기 섹션으로 이동하세요.Jump to the Get the complete tutorial solution section for quick instructions.

이제 시작하겠습니다.Now let's get started!

필수 구성 요소Prerequisites

1단계: Azure Cosmos DB 계정 만들기Step 1: Create an Azure Cosmos DB account

Azure Cosmos DB 계정을 만들어 보겠습니다.Let's create an Azure Cosmos DB account. 사용할 계정이 이미 있으면 이 섹션을 건너뜁니다.If you already have an account you want to use, skip this section. Azure Cosmos DB 에뮬레이터를 사용하려면 Azure Cosmos DB 에뮬레이터의 단계에 따라 에뮬레이터를 설정합니다.To use the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator. 그런 다음, 2단계: Visual Studio 프로젝트 설정으로 건너뜁니다.Then skip ahead to Step 2: Set up your Visual Studio project.

  1. Azure Portal 메뉴 또는 페이지에서 리소스 만들기 를 선택합니다.From the Azure portal menu or the Home page, select Create a resource.

  2. 새로 만들기 페이지에서 Azure Cosmos DB 를 검색하여 선택합니다.On the New page, search for and select Azure Cosmos DB.

  3. Azure Cosmos DB 페이지에서 만들기 를 선택합니다.On the Azure Cosmos DB page, select Create.

  4. Azure Cosmos DB 계정 만들기 페이지에서 새 Azure Cosmos 계정에 대한 기본 설정을 입력합니다.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    설정Setting Value DescriptionDescription
    SubscriptionSubscription 구독 이름Subscription name 이 Azure Cosmos 계정에 사용하려는 Azure 구독을 선택합니다.Select the Azure subscription that you want to use for this Azure Cosmos account.
    리소스 그룹Resource Group 리소스 그룹 이름Resource group name 리소스 그룹을 선택하거나 새로 만들기 를 선택한 후, 새 리소스 그룹에 고유한 이름을 입력합니다.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    계정 이름Account Name 고유한 이름A unique name Azure Cosmos 계정을 식별하는 이름을 입력합니다.Enter a name to identify your Azure Cosmos account. URI를 만들기 위해 제공하는 이름에 documents.azure.com 이 추가되므로 고유한 이름을 사용합니다.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    이름은 소문자, 숫자 및 하이픈(-) 문자만 포함할 수 있으며,The name can only contain lowercase letters, numbers, and the hyphen (-) character. 길이는 3~44자여야 합니다.It must be between 3-44 characters in length.
    APIAPI 만들 계정 형식The type of account to create Core(SQL) 를 선택하여 문서 데이터베이스를 만들고 SQL 구문을 사용하여 쿼리합니다.Select Core (SQL) to create a document database and query by using SQL syntax.

    API는 만들 계정의 형식을 결정합니다.The API determines the type of account to create. Azure Cosmos DB는 문서 데이터용 Core(SQL) 및 MongoDB, 그래프 데이터용 Gremlin, Azure Table 및 Cassandra, 이렇게 5가지 API를 제공합니다.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 현재 각 API에 대한 별도의 계정을 만들어야 합니다.Currently, you must create a separate account for each API.
    용량 모드Capacity mode 프로비저닝된 처리량 또는 서버리스Provisioned throughput or Serverless 프로비저닝된 처리량 을 선택하여 프로비저닝된 처리량 모드에서 계정을 만듭니다.Select Provisioned throughput to create an account in provisioned throughput mode. 서버리스 를 선택하여 서버리스 모드에서 계정을 만듭니다.Select Serverless to create an account in serverless mode.
    체험 계층 할인 적용Apply Free Tier Discount 적용 또는 적용 안 함Apply or Do not apply Azure Cosmos DB 체험 계층을 사용하는 경우 처음에는 400RU/초 및 5GB의 스토리지가 계정에 무료로 제공됩니다.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. 체험 계층에 대해 자세히 알아보세요.Learn more about free tier.
    위치Location 사용자와 가장 가까운 지역The region closest to your users Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다.Select a geographic location to host your Azure Cosmos DB account. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.Use the location that is closest to your users to give them the fastest access to the data.
    계정 유형Account Type 프로덕션 또는 비프로덕션Production or Non-Production 계정이 프로덕션 워크로드에 사용되는 경우 프로덕션 을 선택합니다.Select Production if the account will be used for a production workload. 계정이 비프로덕션(예: 개발, 테스트, QA 또는 준비)에 사용되는 경우 비프로덕션 을 선택합니다.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. 이는 포털 환경을 조정하지만 기본 Azure Cosmos DB 계정에는 영향을 주지 않는 Azure 리소스 태그 설정입니다.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. 이 값은 언제든지 변경할 수 있습니다.You can change this value anytime.

    참고

    Azure 구독당 최대 1개의 체험 계층 Azure Cosmos DB 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. 체험 계층 할인을 적용하는 옵션이 표시되지 않으면 구독의 다른 계정에서 이미 체험 계층을 사용하도록 설정되었음을 의미합니다.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.

    참고

    용량 모드서버리스 를 선택한 경우 다음 옵션을 사용할 수 없습니다.The following options are not available if you select Serverless as the Capacity mode:

    • 체험 계층 할인 적용Apply Free Tier Discount
    • 지리적 중복Geo-redundancy
    • 다중 지역 쓰기Multi-region Writes

    Azure Cosmos DB에 대한 새 계정 페이지

  5. 검토 + 만들기 를 선택합니다.Select Review + create. 네트워크태그 섹션은 건너뛰어도 됩니다.You can skip the Network and Tags sections.

  6. 계정 설정을 검토한 다음, 만들기 를 선택합니다.Review the account settings, and then select Create. 계정을 만드는 데 몇 분이 걸립니다.It takes a few minutes to create the account. 포털 페이지에 배포가 완료됨 이 표시되기를 기다립니다.Wait for the portal page to display Your deployment is complete.

    Azure Portal 알림 창

  7. 리소스로 이동 을 선택하여 Azure Cosmos DB 계정 페이지로 이동합니다.Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB 계정 페이지

2단계: Visual Studio 프로젝트 설정Step 2: Set up your Visual Studio project

  1. Visual Studio를 열고 새 프로젝트 만들기 를 선택합니다.Open Visual Studio and select Create a new project.

  2. 새 프로젝트 만들기 에서 C#에 대해 콘솔 앱(.NET Framework) 을 선택한 후 다음 을 선택합니다.In Create a new project , choose Console App (.NET Framework) for C#, then select Next.

  3. 프로젝트 이름을 CosmosGettingStartedTutorial 로 지정한 다음, 만들기 를 선택 합니다.Name your project CosmosGettingStartedTutorial , and then select Create.

    프로젝트 구성

  4. 솔루션 탐색기 에서 Visual Studio 솔루션 아래에 있는 새 콘솔 애플리케이션을 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리 를 선택합니다.In the Solution Explorer , right-click your new console application, which is under your Visual Studio solution, and select Manage NuGet Packages.

  5. NuGet 패키지 관리자 에서 찾아보기 를 선택하고 Microsoft.Azure.Cosmos 를 검색합니다.In the NuGet Package Manager , select Browse and search for Microsoft.Azure.Cosmos. Microsoft.Azure.Cosmos 를 선택하고 설치 를 선택합니다.Choose Microsoft.Azure.Cosmos and select Install.

    Azure Cosmos DB 클라이언트 SDK용 NuGet 설치

    Azure Cosmos DB SQL API 클라이언트 라이브러리의 패키지 ID는 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.

잘하셨습니다.Great! 설치를 완료했으므로 코드를 작성해 보겠습니다.Now that we finished the setup, let's start writing some code. 이 자습서의 완료된 프로젝트는 Azure Cosmos DB를 사용하여 .NET 콘솔 앱 개발을 참조하세요.For the completed project of this tutorial, see Developing a .NET console app using Azure Cosmos DB.

3단계: Azure Cosmos DB 계정에 연결Step 3: Connect to an Azure Cosmos DB account

  1. Program.cs 파일에서 C# 애플리케이션의 시작 부분에 있는 참조를 다음 참조로 바꿉니다.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. 다음 상수와 변수를 Program 클래스에 추가합니다.Add these constants and variables into your Program class.

    public class Program
    {
        // ADD THIS PART TO YOUR CODE
    
        // The Azure Cosmos DB endpoint for running this sample.
        private static readonly string EndpointUri = "<your endpoint here>";
        // The primary key for the Azure Cosmos account.
        private static readonly string PrimaryKey = "<your primary key>";
    
        // The Cosmos client instance
        private CosmosClient cosmosClient;
    
        // The database we will create
        private Database database;
    
        // The container we will create.
        private Container container;
    
        // The name of the database and container we will create
        private string databaseId = "FamilyDatabase";
        private string containerId = "FamilyContainer";
    }
    

    참고

    이전 버전의 .NET SDK에 익숙한 경우 컬렉션문서 라는 용어가 친숙할 수 있습니다.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는 여러 API 모델을 지원하기 때문에 .NET SDK 버전 3.0에서는 컨테이너항목 이라는 일반적인 용어가 사용됩니다.Because Azure Cosmos DB supports multiple API models, version 3.0 of the .NET SDK uses the generic terms container and item. 컨테이너 는 컬렉션, 그래프 또는 테이블이 될 수 있습니다.A container can be a collection, graph, or table. 항목 은 문서, 가장자리/꼭짓점 또는 행이 될 수 있고, 컨테이너 내부의 콘텐츠입니다.An item can be a document, edge/vertex, or row, and is the content inside a container. 자세한 내용은 Azure Cosmos DB에서 데이터베이스, 컨테이너 및 항목 작업을 참조하세요.For more information, see Work with databases, containers, and items in Azure Cosmos DB.

  3. Azure Portal을 엽니다.Open the Azure portal. Azure Cosmos DB 계정을 찾은 다음, 를 선택합니다.Find your Azure Cosmos DB account, and then select Keys.

    Azure Portal에서 Azure Cosmos DB 키 가져오기

  4. Program.cs 에서 <your endpoint URL>URI 값으로 바꿉니다.In Program.cs , replace <your endpoint URL> with the value of URI. <your primary key>기본 키 값으로 대체합니다.Replace <your primary key> with the value of PRIMARY KEY.

  5. Main 메서드 아래에 새 CosmosClient를 인스턴스화하는 GetStartedDemoAsync 라는 새 비동기 작업을 추가합니다.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);
    }
    

    GetStartedDemoAsync 를 Azure Cosmos DB 리소스에서 작동하는 메서드를 호출하는 진입점으로 사용합니다.We use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

  6. 다음 코드를 추가하여 Main 메서드에서 GetStartedDemoAsync 비동기 작업을 실행합니다.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. Main 메서드가 예외를 catch하고 콘솔에 씁니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

    콘솔에 End of demo, press any key to exit. 메시지가 표시됩니다.The console displays the message: End of demo, press any key to exit. 이 메시지는 애플리케이션이 Azure Cosmos DB에 연결된 것을 확인합니다.This message confirms that your application made a connection to Azure Cosmos DB. 그런 다음 콘솔 창을 닫을 수 있습니다.You can then close the console window.

축하합니다!Congratulations! Azure Cosmos DB 계정에 성공적으로 연결되었습니다.You've successfully connected to an Azure Cosmos DB account.

4단계: 데이터베이스 만들기Step 4: Create a database

데이터베이스는 여러 컨테이너에 분할된 항목의 논리적 컨테이너입니다.A database is the logical container of items partitioned across containers. CosmosClient 클래스의 CreateDatabaseIfNotExistsAsync 또는 CreateDatabaseAsync 메서드는 데이터베이스를 만들 수 있습니다.Either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync method of the CosmosClient class can create a database.

  1. CreateDatabaseAsync 메서드를 복사하여 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);
    }
    

    CreateDatabaseAsyncdatabaseId 필드에서 지정된 ID가 있는 데이터베이스가 없으면, ID가 FamilyDatabase인 새 데이터베이스를 만듭니다.CreateDatabaseAsync creates a new database with ID FamilyDatabase if it doesn't already exist, that has the ID specified from the databaseId field.

  2. 코드를 복사하여 CosmosClient를 인스턴스화한 위치 아래에 붙여넣고 방금 추가한 CreateDatabaseAsync 메서드를 호출합니다.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.cs 가 이제 다음과 같이 보이고, 엔드포인트와 기본 키가 채워져 있습니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

    참고

    "503 서비스를 사용할 수 없는 예외" 오류가 발생하면 직접 연결 모드에 필요한 포트가 방화벽에 의해 차단되었을 수 있습니다.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. 이 문제를 해결하려면 다음 코드와 같이 필요한 포트를 열거나 게이트웨이 모드 연결을 사용합니다.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
             });
    

축하합니다!Congratulations! Azure Cosmos 데이터베이스가 성공적으로 만들어졌습니다.You've successfully created an Azure Cosmos database.

5단계: 컨테이너 만들기Step 5: Create a container

경고

CreateContainerIfNotExistsAsync 메서드는 가격 책정에 영향을 주는 새 컨테이너를 만듭니다.The method CreateContainerIfNotExistsAsync creates a new container, which has pricing implications. 자세한 내용은 가격 페이지를 참조하세요.For more details, please visit our pricing page.

컨테이너는 CosmosDatabase 클래스의 CreateContainerIfNotExistsAsync 또는 CreateContainerAsync 메서드를 사용하여 만들 수 있습니다.A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync method in the CosmosDatabase class. 컨테이너는 항목(SQL API의 경우 JSON 문서) 및 JavaScript의 관련 서버 쪽 애플리케이션 논리(예: 저장 프로시저, 사용자 정의 함수 및 트리거)로 구성됩니다.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. CreateContainerAsync 메서드를 복사하여 CreateDatabaseAsync 메서드 아래에 붙여넣습니다.Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. CreateContainerAsync는 ID가 FamilyContainer인 컨테이너가 없으면 LastName 속성으로 분할된 containerId 필드에서 지정된 ID를 사용하여 해당 컨테이너를 새로 만듭니다.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. CosmosClient를 인스턴스화한 아래 코드를 복사하여 붙여넣어 방금 추가한 CreateContainer 메서드를 호출합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! Azure Cosmos 컨테이너를 성공적으로 만들었습니다.You've successfully created an Azure Cosmos container.

6단계: 컨테이너에 항목 추가Step 6: Add items to the container

CosmosContainer 클래스의 CreateItemAsync 메서드는 항목을 만들 수 있습니다.The CreateItemAsync method of the CosmosContainer class can create an item. SQL API를 사용하는 경우 항목은 사용자 정의 임의 JSON 콘텐츠인 문서로 프로젝션됩니다.When using the SQL API, items are projected as documents, which are user-defined arbitrary JSON content. 이제 Azure Cosmos 컨테이너에 항목을 삽입할 수 있습니다.You can now insert an item into your Azure Cosmos container.

먼저 이 샘플에서는 Azure Cosmos DB 내에 저장된 개체를 나타내는 Family 클래스를 만들어 보겠습니다.First, let's create a Family class that represents objects stored within Azure Cosmos DB in this sample. Family 내에서 사용되는 Parent, Child, Pet, Address 하위 클래스도 만듭니다.We'll also create Parent, Child, Pet, Address subclasses that are used within Family. 항목에는 id로 직렬화된 JSON 형식의 Id 속성이 있어야 합니다.The item must have an Id property serialized as id in JSON.

  1. Ctrl+Shift+A를 선택하여 새 항목 추가 를 엽니다.Select Ctrl+Shift+A to open Add New Item. 프로젝트에 새 클래스인 Family.cs를 추가합니다.Add a new class Family.cs to your project.

    프로젝트에 새 Family.cs 클래스를 추가하는 스크린샷

  2. Family, Parent, Child, PetAddress 클래스를 복사하여 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 로 돌아가서 CreateContainerAsync 메서드 뒤에 AddItemsToContainerAsync 메서드를 추가합니다.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);
        }
    }
    

    이 코드는 ID가 같은 항목이 존재하는지 확인합니다.The code checks to make sure an item with the same ID doesn't already exist. Andersen FamilyWakefield Family 에 대해 하나씩 두 개의 항목을 삽입하겠습니다.We'll insert two items, one each for the Andersen Family and the Wakefield Family.

  4. 호출을 GetStartedDemoAsync 메서드의 AddItemsToContainerAsync에 추가합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! 두 개의 Azure Cosmos 항목을 성공적으로 만들었습니다.You've successfully created two Azure Cosmos items.

7단계: Azure Cosmos DB 리소스 쿼리Step 7: Query Azure Cosmos DB resources

Azure Cosmos DB는 각 컨테이너에 저장된 JSON 문서에 대해 다양한 쿼리를 지원합니다.Azure Cosmos DB supports rich queries against JSON documents stored in each container. 자세한 내용은 SQL 쿼리 시작을 참조하세요.For more information, see Getting started with SQL queries. 다음 샘플 코드에서는 이전 단계에서 삽입한 항목에 대해 쿼리를 실행하는 방법을 보여줍니다.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. QueryItemsAsync 메서드를 복사하여 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. 호출을 GetStartedDemoAsync 메서드의 QueryItemsAsync에 추가합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! Azure Cosmos 컨테이너를 성공적으로 쿼리했습니다.You've successfully queried an Azure Cosmos container.

8단계: JSON 항목 바꾸기Step 8: Replace a JSON item

이제 Azure Cosmos DB에서 항목을 업데이트하겠습니다.Now, we'll update an item in Azure Cosmos DB. FamilyIsRegistered 속성과 자식 요소 중 하나의 Grade를 변경합니다.We'll change the IsRegistered property of the Family and the Grade of one of the children.

  1. ReplaceFamilyItemAsync 메서드를 복사하여 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. 호출을 GetStartedDemoAsync 메서드의 ReplaceFamilyItemAsync에 추가합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! Azure Cosmos 항목을 성공적으로 대체했습니다.You've successfully replaced an Azure Cosmos item.

9단계: 항목 삭제Step 9: Delete item

이제 Azure Cosmos DB에서 항목을 삭제하겠습니다.Now, we'll delete an item in Azure Cosmos DB.

  1. DeleteFamilyItemAsync 메서드를 복사하여 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. 호출을 GetStartedDemoAsync 메서드의 DeleteFamilyItemAsync에 추가합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! Azure Cosmos 항목을 성공적으로 삭제했습니다.You've successfully deleted an Azure Cosmos item.

10단계: 데이터베이스 삭제Step 10: Delete the database

이제 데이터베이스를 삭제하겠습니다.Now we'll delete our database. 만든 데이터베이스를 삭제하면 데이터베이스와 모든 하위 리소스가 제거됩니다.Deleting the created database removes the database and all children resources. 리소스에는 컨테이너, 항목, 저장 프로 시저, 사용자 정의 함수 및 트리거가 포함됩니다.The resources include containers, items, and any stored procedures, user-defined functions, and triggers. CosmosClient 인스턴스도 삭제합니다.We also dispose of the CosmosClient instance.

  1. DeleteDatabaseAndCleanupAsync 메서드를 복사하여 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. 호출을 GetStartedDemoAsync 메서드의 DeleteDatabaseAndCleanupAsync에 추가합니다.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. F5 키를 선택하여 애플리케이션을 실행합니다.Select F5 to run your application.

축하합니다!Congratulations! Azure Cosmos 데이터베이스를 성공적으로 삭제했습니다.You've successfully deleted an Azure Cosmos database.

11단계: C# 콘솔 애플리케이션 모두 함께 실행Step 11: Run your C# console application all together!

디버그 모드에서 애플리케이션을 빌드하고 실행하려면 Visual Studio에서 F5를 선택합니다.Select F5 in Visual Studio to build and run the application in debug mode.

전체 앱의 출력이 콘솔 창에 표시됩니다.You should see the output of your entire app in a console window. 출력에는 추가한 쿼리의 결과가 표시됩니다.The output shows the results of the queries we added. 아래 예제 텍스트와 일치해야 합니다.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.

축하합니다!Congratulations! 이 자습서를 완료했으며 실행되는 C# 콘솔 애플리케이션이 생겼습니다.You've completed the tutorial and have a working C# console application!

전체 자습서 솔루션 가져오기Get the complete tutorial solution

이 자습서의 단계를 완료할 시간이 없거나 코드 샘플만 다운로드하려는 경우에는 다운로드할 수 있습니다.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.

GetStarted 솔루션을 빌드하려면 다음 필수 구성 요소가 필요합니다.To build the GetStarted solution, you need the following prerequisites:

Visual Studio에서 Azure Cosmos DB .NET SDK에 대한 참조를 복원하려면 솔루션 탐색기 에서 솔루션을 마우스 오른쪽 단추로 클릭한 다음, NuGet 패키지 복원 을 선택합니다.To restore the references to the Azure Cosmos DB .NET SDK in Visual Studio, right-click the solution in Solution Explorer , and then select Restore NuGet Packages. 그런 다음, App.config 파일에서 EndPointUriPrimaryKey 값을 3단계: Azure Cosmos DB 계정에 연결에 따라 업데이트합니다.Next, in the App.config file, update the EndPointUri and PrimaryKey values as described in Step 3: Connect to an Azure Cosmos DB account.

정말 간단하죠? 빌드하고 원하는 대로 진행하세요!That's it, build it, and you're on your way!

다음 단계Next steps