빠른 시작: MongoDB 드라이버를 사용하는 .NET용 Azure Cosmos DB for MongoDB

적용 대상: Mongodb

MongoDB를 시작하여 Azure Cosmos DB 리소스 내에서 데이터베이스, 컬렉션 및 문서를 만듭니다. 다음 단계에 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 보세요.

참고

예제 코드 조각은 GitHub에서 .NET 프로젝트로 사용할 수 있습니다.

MongoDB용 API 참조 설명서 | MongoDB 패키지(NuGet)

필수 구성 요소

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 dotnet --list-sdks를 실행하여 .NET 6.x가 사용 가능한 버전 중 하나인지 확인합니다.
  • az --version(Azure CLI) 또는 Get-Module -ListAvailable AzureRM(Azure PowerShell)을 실행하여 적절한 Azure 명령줄 도구가 설치되어 있는지 확인합니다.

설치

이 섹션에서는 Azure Cosmos DB 계정을 만들고 MongoDB NuGet 패키지를 사용하는 프로젝트를 설정하는 방법에 대해 설명합니다.

Azure Cosmos DB 계정 만들기

이 빠른 시작에서는 MongoDB용 API를 사용하여 단일 Azure Cosmos DB 계정을 만듭니다.

  1. accountName, resourceGroupNamelocation에 대한 셸 변수를 만듭니다.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. 아직 로그인하지 않은 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다.

  3. az group create 명령을 사용하여 새 리소스 그룹을 구독에 만듭니다.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. az cosmosdb create 명령을 사용하여 기본 설정으로 새 Azure Cosmos DB for MongoDB 계정을 만듭니다.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

MongoDB 연결 문자열 가져오기

  1. 명령을 사용하여 계정의 연결 문자열 목록에서 MongoDB용 API 연결 문자열az cosmosdb keys list 찾습니다.

    az cosmosdb keys list --type connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. 기본 키 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

새 .NET 앱 만들기

원하는 터미널을 사용하여 새 .NET 애플리케이션을 빈 폴더에 만듭니다. dotnet new console을 사용하여 새 콘솔 앱을 만듭니다.

dotnet new console -o <app-name>

NuGet 패키지 설치

MongoDB.Driver NuGet 패키지를 새 .NET 프로젝트에 추가합니다. NuGet 패키지의 이름을 지정한 dotnet add package 명령을 사용합니다.

dotnet add package MongoDb.Driver

환경 변수 구성

코드 내에서 CONNECTION STRING 값을 사용하려면 애플리케이션을 실행하는 로컬 환경에서 이 값을 설정합니다. 환경 변수를 설정하려면 원하는 터미널을 사용하여 다음 명령을 실행합니다.

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

개체 모델

애플리케이션 빌드를 시작하기 전에 Azure Cosmos DB의 리소스 계층 구조를 살펴보겠습니다. Azure Cosmos DB에는 리소스를 만들고 액세스하는 데 사용되는 특정 개체 모델이 있습니다. Azure Cosmos DB는 리소스를 계정, 데이터베이스, 컬렉션 및 문서로 구성된 계층 구조에 만듭니다.

계정, 데이터베이스, 컬렉션 및 문서를 포함하는 Azure Cosmos DB 계층 구조의 다이어그램.

맨 위에 있는 Azure Cosmos DB 계정을 보여 주는 계층 다이어그램. 계정에는 두 개의 자식 데이터베이스 노드가 있습니다. 데이터베이스 노드 중 하나에는 두 개의 자식 컬렉션 노드가 포함되어 있습니다. 다른 데이터베이스 노드에는 단일 자식 컬렉션 노드가 포함됩니다. 단일 컬렉션 노드에는 세 개의 자식 문서 노드가 있습니다.

다음 MongoDB 클래스를 사용하여 해당 리소스와 상호 작용합니다.

  • MongoClient - 이 클래스는 Azure Cosmos DB의 API for MongoDB 계층에 대한 클라이언트 쪽 논리 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.
  • MongoDatabase - 이 클래스는 아직 서비스에 있거나 없을 수도 있는 데이터베이스에 대한 참조입니다. 데이터베이스에 액세스하거나 이에 대한 작업을 수행하려고 하면 서버 쪽에서 데이터베이스의 유효성이 검사됩니다.
  • Collection - 이 클래스는 아직 서비스에 없을 수도 있는 컬렉션에 대한 참조입니다. 관련 작업을 시도하면 서버 쪽에서 컬렉션의 유효성이 검사됩니다.

코드 예제

이 문서에서 설명하는 샘플 코드에서는 products라는 컬렉션을 사용하여 adventureworks라는 데이터베이스를 만듭니다. products 컬렉션은 이름, 범주, 수량 및 판매 지표와 같은 제품 세부 정보를 포함하도록 설계되었습니다. 각 제품에는 고유 식별자도 포함됩니다.

클라이언트 인증

프로젝트 디렉터리에서 Program.cs 파일을 엽니다. 편집기에서 MongoDB.Driver에 대한 using 지시문을 추가합니다.

using MongoDB.Driver;

생성자를 사용하여 MongoClient 클래스의 새 인스턴스를 정의하고 이전에 설정한 연결 문자열을 읽기 위해 Environment.GetEnvironmentVariable을 정의합니다.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

데이터베이스 만들기

아직 없는 경우 MongoClient.GetDatabase 메서드를 사용하여 새 데이터베이스를 만듭니다. 이 메서드는 기존 또는 새로 만든 데이터베이스에 대한 참조를 반환합니다.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

컬렉션 만들기

MongoDatabase.GetCollection은 컬렉션이 아직 없는 경우 새 컬렉션을 만들고 컬렉션에 대한 참조를 반환합니다.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

항목 만들기

새 항목을 컬렉션에 만드는 가장 쉬운 방법은 JSON으로 직렬화하려는 모든 멤버가 포함된 C# 클래스 또는 레코드 형식을 만드는 것입니다. 다음 예제의 C# 레코드에는 고유 식별자, 파티션 키에 대한 category 필드, 추가 name, quantitysale 필드가 있습니다.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

IMongoCollection<TDocument>.InsertOne을 호출해 Product 레코드를 사용하여 컬렉션에 항목을 만듭니다.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

항목 가져오기

Azure Cosmos DB에서 Linq를 사용해 쿼리를 작성하여 항목을 검색할 수 있습니다. SDK에서 IMongoCollection.FindAsync<>를 호출하고 C# 식을 전달하여 결과를 필터링합니다.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

쿼리 항목

항목을 삽입한 후 컬렉션을 IQueryable로 처리하여 특정 필터와 일치하는 모든 항목을 가져오는 쿼리를 실행할 수 있습니다. 이 예제에서는 식을 사용하여 제품을 범주별로 필터링합니다. AsQueryable에 대한 호출이 완료되면 MongoQueryable.Where를 호출하여 필터링된 항목 세트를 검색합니다.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

코드 실행

이 앱은 Azure Cosmos DB MongoDb API 데이터베이스 및 컬렉션을 만듭니다. 그런 다음, 다음 예제에서 항목을 만든 다음, 정확히 동일한 항목을 다시 읽습니다. 마지막으로, 이 예제에서는 두 번째 항목을 만든 다음, 여러 항목을 반환해야 하는 쿼리를 수행합니다. 각 단계에서 예제는 수행한 단계에 대한 메타데이터를 콘솔에 출력합니다.

앱을 실행하려면 터미널을 사용하여 애플리케이션 디렉터리로 이동하고 애플리케이션을 실행합니다.

dotnet run

앱의 출력은 다음 예제와 비슷합니다.

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

리소스 정리

NoSQL용 Azure Cosmos DB 계정이 더 이상 필요하지 않은 경우 해당 리소스 그룹을 삭제할 수 있습니다.

az group delete 명령을 사용하여 리소스 그룹을 삭제합니다.

az group delete --name $resourceGroupName