ASP.NET Core 및 MongoDB를 사용하여 웹 API 만들기

작성자: Pratik Khandelwal 및 Scott Addie

이 자습서에서는 MongoDB NoSQL 데이터베이스에 대해 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업을 실행하는 웹 API를 만듭니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

• MongoDB 구성
• MongoDB 데이터베이스 만들기
• MongoDB 컬렉션 및 스키마 정의
• 웹 API에서 MongoDB CRUD 작업 수행
• JSON serialization 사용자 지정

필수 조건

• MongoDB 6.0.5 이상
• MongoDB Shell

Visual Studio

• ASP.NET 및 웹 개발 워크로드가 있는 Visual Studio 2022

  

Visual Studio Code

• Visual Studio Code
• Visual Studio Code용 C#(최신 버전)
• .NET 8.0 SDK

Visual Studio Code 지침은 .NET CLI를 사용하여 프로젝트 작성과 같은 ASP.NET Core 개발 기능을 사용합니다. macOS, Linux 또는 Windows와 모든 코드 편집기에서 이러한 지침을 따를 수 있습니다. Visual Studio Code 이외의 항목을 사용하는 경우 사소한 변경이 필요할 수 있습니다.

Mac용 Visual Studio

• Mac용 Visual Studio 2022(최신 버전)

  Important

  Microsoft는 Mac용 Visual Studio의 사용 중지를 발표했습니다. Mac용 Visual Studio는 2024년 8월 31일부터 더 이상 지원되지 않습니다. 대안은 다음과 같습니다.

  • C# 개발 키트 및 관련 확장(예: .NET MAUIUnity)이 있는 Visual Studio Code.
  • Mac의 VM에서 Windows에서 실행되는 Visual Studio IDE입니다.
  • 클라우드의 VM에서 Windows에서 실행되는 Visual Studio IDE입니다.

  자세한 내용은 Mac용 Visual Studio 사용 중지 공지를 참조하세요.

MongoDB 구성

개발 머신의 어디에서나 MongoDB 및 Mongo DB Shell 액세스를 사용하도록 설정합니다.

1. Windows에서 MongoDB는 기본적으로 C:\Program Files\MongoDB에 설치됩니다. C:\Program Files\MongoDB\Server\<version_number>\bin을 PATH 환경 변수에 추가합니다.

2. MongoDB 셸을 다운로드하고 추출할 디렉터리를 선택합니다. 환경 변수에 대한 mongosh.exePATH 결과 경로를 추가합니다.

3. 데이터를 저장하기 위해 개발 머신에서 디렉터리를 선택합니다. 예를 들어 Windows의 경우 C:\BooksData 등을 선택합니다. 디렉터리가 없을 경우 새로 만듭니다. mongo 셸은 새 디렉터리를 만들지 않습니다.

4. OS 명령 셸(MongoDB 셸 아님)에서 다음 명령을 사용하여 기본 포트 27017에서 MongoDB에 연결합니다. 이전 단계에서 선택한 디렉터리로 바꿉 <data_directory_path> 다.

   mongod --dbpath <data_directory_path>
   

다음 단계에서 이전에 설치된 MongoDB Shell을 사용하여 데이터베이스 및 컬렉션을 만들고 문서를 저장합니다. MongoDB Shell 명령에 대한 자세한 내용은 mongosh를 참조하세요.

1. 를 시작하여 MongoDB 명령 셸 인스턴스를 엽니다 mongosh.exe.

2. 명령 셸에서 다음 명령을 실행하여 기본 테스트 데이터베이스에 연결합니다.

   mongosh
   

3. 명령 셸에서 다음 명령을 실행합니다.

   use BookStore
   

   아직 존재하지 않는 경우 BookStore라는 데이터베이스가 생성됩니다. 데이터베이스가 있는 경우 트랜잭션을 위해 해당 연결이 열립니다.

4. 다음 명령을 사용하여 Books 컬렉션을 만듭니다.

   db.createCollection('Books')
   

   다음 결과가 표시됩니다.

   { "ok" : 1 }
   

5. 다음 명령을 사용하여 Books 컬렉션에 대한 스키마를 정의하고 두 개의 문서를 삽입합니다.

   db.Books.insertMany([{ "Name": "Design Patterns", "Price": 54.93, "Category": "Computers", "Author": "Ralph Johnson" }, { "Name": "Clean Code", "Price": 43.15, "Category": "Computers","Author": "Robert C. Martin" }])
   

   다음과 비슷한 결과가 표시됩니다.

   {
       "acknowledged" : true,
       "insertedIds" : [
           ObjectId("61a6058e6c43f32854e51f51"),
           ObjectId("61a6058e6c43f32854e51f52")
        ]
    }
   

   참고 항목

   ObjectId이전 결과에 표시된 내용이 명령 셸에 표시된 것과 일치하지 않습니다.

6. 다음 명령을 사용하여 데이터베이스의 문서를 봅니다.

   db.Books.find().pretty()
   

   다음과 비슷한 결과가 표시됩니다.

   {
        "_id" : ObjectId("61a6058e6c43f32854e51f51"),
        "Name" : "Design Patterns",
        "Price" : 54.93,
        "Category" : "Computers",
        "Author" : "Ralph Johnson"
    }
    {
        "_id" : ObjectId("61a6058e6c43f32854e51f52"),
        "Name" : "Clean Code",
        "Price" : 43.15,
        "Category" : "Computers",
        "Author" : "Robert C. Martin"
    }
   

   스키마가 각 문서에 대해 자동 생성된 ObjectId 형식의 _id 속성을 추가합니다.

ASP.NET Core 웹 API 프로젝트 만들기

Visual Studio

1. 파일>새로 만들기>프로젝트로 이동합니다.

2. ASP.NET Core Web API 프로젝트 형식을 선택하고 다음을 선택합니다.

3. 프로젝트 이름을 BookStoreApi로 지정하고 다음을 선택합니다.

4. .NET 8.0(장기 지원) 프레임워크를 선택하고 만들기를 선택합니다.

5. 패키지 관리자 콘솔 창에서 프로젝트 루트로 이동합니다. 다음 명령을 실행하여 MongoDB용 .NET 드라이버를 설치합니다.

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. 명령 셸에서 다음 명령을 실행합니다.

   dotnet new webapi -o BookStoreApi
   code BookStoreApi
   

   위의 명령은 새 ASP.NET Core Web API 프로젝트를 생성하여 Visual Studio Code 프로젝트에서 엽니다.

2. OmniSharp 서버가 시작되면 빌드 및 디버그에 필요한 자산이 ‘BookStoreApi’에서 누락되었습니다. 추가하시겠습니까? 대화 상자가 표시됩니다. 예를 선택합니다.

3. 통합 터미널을 열고 다음 명령을 실행하여 MongoDB용 .NET 드라이버를 설치합니다.

   dotnet add package MongoDB.Driver
   

Mac용 Visual Studio

1. Visual Studio>기본 설정을 선택합니다.
2. 사이드바에서 미리 보기 기능을 선택하고 .NET SDK의 미리 보기 사용을 사용하도록 설정하고 확인을 선택합니다.
3. Visual Studio를 다시 시작합니다.
4. 파일>새 프로젝트...를 선택합니다.
5. 사이드바에서 웹 및 콘솔>앱을 선택합니다.
6. ASP.NET Core>API C# 프로젝트 템플릿을 선택하고 다음을 선택합니다.
7. 대상 프레임워크 드롭다운 목록에서 .NET 8.0 을 선택하고 다음을 선택합니다.
8. 프로젝트 이름으로 BookStoreApi를 입력하고 만들기를 선택합니다.
9. 솔루션 패드에서 프로젝트의 종속성 노드를 마우스 오른쪽 단추로 클릭하고 패키지 추가를 선택합니다.
10. 검색 상자에 MongoDB.Driver를 입력하여 MongoDB.Driver 패키지를 선택하고 패키지 추가를 선택합니다.
11. 라이선스 승인 대화 상자에서 동의 단추를 선택합니다.

엔터티 모델 추가

1. 프로젝트 루트에 Models 디렉터리를 추가합니다.

2. 다음 코드를 사용하여 Models 디렉터리에 Book 클래스를 추가합니다.

   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   
   namespace BookStoreApi.Models;
   
   public class Book
   {
       [BsonId]
       [BsonRepresentation(BsonType.ObjectId)]
       public string? Id { get; set; }
   
       [BsonElement("Name")]
       public string BookName { get; set; } = null!;
   
       public decimal Price { get; set; }
   
       public string Category { get; set; } = null!;
   
       public string Author { get; set; } = null!;
   }
   

   앞의 클래스에서 Id 속성은

   • CLR(공용 언어 런타임) 개체를 MongoDB 컬렉션에 매핑하는 데 필요합니다.
   • 이 속성을 문서의 기본 키로 설정하기 위해 [BsonId]로 주석이 추가됩니다.
   • ObjectId 구조체 대신 string 형식으로 매개 변수를 전달할 수 있도록 [BsonRepresentation(BsonType.ObjectId)]로 주석이 추가됩니다. Mongo는 string에서 ObjectId로 변환을 처리합니다.

   BookName 속성은 [BsonElement] 특성으로 주석이 추가됩니다. Name의 특성 값은 MongoDB 컬렉션의 속성 이름을 나타냅니다.

구성 모델 추가

1. 다음 데이터베이스 구성 값을 appsettings.json에 추가합니다.

   {
       "BookStoreDatabase": {
           "ConnectionString": "mongodb://localhost:27017",
           "DatabaseName": "BookStore",
           "BooksCollectionName": "Books"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning"
           }
       },
       "AllowedHosts": "*"
   }
   

2. 다음 코드를 사용하여 Models 디렉터리에 BookStoreDatabaseSettings 클래스를 추가합니다.

   namespace BookStoreApi.Models;
   
   public class BookStoreDatabaseSettings
   {
       public string ConnectionString { get; set; } = null!;
   
       public string DatabaseName { get; set; } = null!;
   
       public string BooksCollectionName { get; set; } = null!;
   }
   

   위의 BookStoreDatabaseSettings 클래스는 appsettings.json 파일의 BookStoreDatabase 속성 값을 저장하는 데 사용됩니다. JSON 및 C# 속성 이름은 매핑 프로세스를 용이하게 하기 위해 동일한 이름이 지정됩니다.

3. 다음 강조 표시된 코드를 Program.cs에 추가합니다.

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   

   위의 코드에서 appsettings.json 파일의 BookStoreDatabase 섹션이 바인딩되는 구성 인스턴스가 DI(종속성 주입) 컨테이너에 등록됩니다. 예를 들어 BookStoreDatabaseSettings 개체의 ConnectionString 속성은 appsettings.json의 BookStoreDatabase:ConnectionString 속성으로 채워집니다.

4. Program.cs의 맨 위에 다음 코드를 추가하여 BookStoreDatabaseSettings 참조를 확인합니다.

   using BookStoreApi.Models;
   

CRUD 작업 서비스 추가

1. 프로젝트 루트에 Services 디렉터리를 추가합니다.

2. 다음 코드를 사용하여 Services 디렉터리에 BooksService 클래스를 추가합니다.

   using BookStoreApi.Models;
   using Microsoft.Extensions.Options;
   using MongoDB.Driver;
   
   namespace BookStoreApi.Services;
   
   public class BooksService
   {
       private readonly IMongoCollection<Book> _booksCollection;
   
       public BooksService(
           IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
       {
           var mongoClient = new MongoClient(
               bookStoreDatabaseSettings.Value.ConnectionString);
   
           var mongoDatabase = mongoClient.GetDatabase(
               bookStoreDatabaseSettings.Value.DatabaseName);
   
           _booksCollection = mongoDatabase.GetCollection<Book>(
               bookStoreDatabaseSettings.Value.BooksCollectionName);
       }
   
       public async Task<List<Book>> GetAsync() =>
           await _booksCollection.Find(_ => true).ToListAsync();
   
       public async Task<Book?> GetAsync(string id) =>
           await _booksCollection.Find(x => x.Id == id).FirstOrDefaultAsync();
   
       public async Task CreateAsync(Book newBook) =>
           await _booksCollection.InsertOneAsync(newBook);
   
       public async Task UpdateAsync(string id, Book updatedBook) =>
           await _booksCollection.ReplaceOneAsync(x => x.Id == id, updatedBook);
   
       public async Task RemoveAsync(string id) =>
           await _booksCollection.DeleteOneAsync(x => x.Id == id);
   }
   

   위의 코드에서 생성자 주입을 통해 DI에서 BookStoreDatabaseSettings 인스턴스가 검색됩니다. 이 방법은 구성 모델 추가 섹션에 추가된 appsettings.json 구성 값에 대한 액세스를 제공합니다.

3. 다음 강조 표시된 코드를 Program.cs에 추가합니다.

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   

   위의 코드에서 BooksService 클래스는 사용 클래스에서 생성자 주입을 지원하는 DI로 등록됩니다. BooksService가 MongoClient에 직접 종속되기 때문에 싱글톤 서비스 수명이 가장 적합합니다. 공식 Mongo 클라이언트 재사용 지침에 따라 MongoClient를 싱글톤 수명으로 DI에 등록해야 합니다.

4. Program.cs의 맨 위에 다음 코드를 추가하여 BooksService 참조를 확인합니다.

   using BookStoreApi.Services;
   

BooksService 클래스는 다음 MongoDB.Driver 멤버를 사용하여 데이터베이스에 대해 CRUD 작업을 실행합니다.

• MongoClient: 데이터베이스 작업을 실행하기 위한 서버 인스턴스를 읽습니다. 이 클래스의 생성자는 MongoDB 연결 문자열 제공됩니다.

  public BooksService(
      IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
  {
      var mongoClient = new MongoClient(
          bookStoreDatabaseSettings.Value.ConnectionString);
  
      var mongoDatabase = mongoClient.GetDatabase(
          bookStoreDatabaseSettings.Value.DatabaseName);
  
      _booksCollection = mongoDatabase.GetCollection<Book>(
          bookStoreDatabaseSettings.Value.BooksCollectionName);
  }
  

• IMongoDatabase: 작업을 실행하기 위한 Mongo 데이터베이스를 나타냅니다. 이 자습서에서는 인터페이스의 제네릭 GetCollection<TDocument>(collection) 메서드를 사용하여 특정 컬렉션의 데이터에 액세스합니다. 이 메서드를 호출한 후 컬렉션에 대해 CRUD 작업을 실행합니다. GetCollection<TDocument>(collection) 메서드 호출에서 다음을 수행합니다.

  • collection은 컬렉션 이름을 나타냅니다.
  • TDocument는 컬렉션에 저장된 CLR 개체 형식을 나타냅니다.

GetCollection<TDocument>(collection)는 컬렉션을 나타내는 MongoCollection 개체를 반환합니다. 이 자습서에서는 컬렉션에 대해 다음 메서드를 호출합니다.

• DeleteOneAsync: 제공된 검색 조건과 일치하는 단일 문서를 삭제합니다.
• Find<TDocument>: 제공된 검색 조건과 일치하는 컬렉션의 모든 문서를 반환합니다.
• InsertOneAsync: 제공된 개체를 컬렉션에 새 문서로 삽입합니다.
• ReplaceOneAsync: 제공된 검색 조건과 일치하는 단일 문서를 제공된 개체로 바꿉니다.

컨트롤러 추가

다음 코드를 사용하여 Controllers 디렉터리에 BooksController 클래스를 추가합니다.

using BookStoreApi.Models;
using BookStoreApi.Services;
using Microsoft.AspNetCore.Mvc;

namespace BookStoreApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly BooksService _booksService;

    public BooksController(BooksService booksService) =>
        _booksService = booksService;

    [HttpGet]
    public async Task<List<Book>> Get() =>
        await _booksService.GetAsync();

    [HttpGet("{id:length(24)}")]
    public async Task<ActionResult<Book>> Get(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        return book;
    }

    [HttpPost]
    public async Task<IActionResult> Post(Book newBook)
    {
        await _booksService.CreateAsync(newBook);

        return CreatedAtAction(nameof(Get), new { id = newBook.Id }, newBook);
    }

    [HttpPut("{id:length(24)}")]
    public async Task<IActionResult> Update(string id, Book updatedBook)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        updatedBook.Id = book.Id;

        await _booksService.UpdateAsync(id, updatedBook);

        return NoContent();
    }

    [HttpDelete("{id:length(24)}")]
    public async Task<IActionResult> Delete(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        await _booksService.RemoveAsync(id);

        return NoContent();
    }
}

앞의 웹 API 컨트롤러는 다음과 같습니다.

• BooksService 클래스를 사용하여 CRUD 작업을 실행합니다.
• GET, POST, PUT 및 DELETE HTTP 요청을 지원하는 작업 메서드를 포함합니다.
• Create 작업 메서드에서 CreatedAtAction를 호출하여 HTTP 201 응답을 반환합니다. 상태 코드 201은 서버에서 새 리소스를 만드는 HTTP POST 메서드의 표준 응답입니다. 또한 CreatedAtAction는 Location 헤더를 응답에 추가합니다. Location 헤더는 새로 만든 책의 URI를 지정합니다.

웹 API 테스트

1. 앱을 빌드하고 실행합니다.

2. https://localhost:<port>/api/books로 이동합니다. 여기서 <port>는 앱에 자동으로 할당된 포트 번호이며, 컨트롤러의 매개 변수가 없는 Get 작업 메서드를 테스트합니다. 다음과 비슷한 JSON 응답이 표시됩니다.

   [
     {
       "id": "61a6058e6c43f32854e51f51",
       "bookName": "Design Patterns",
       "price": 54.93,
       "category": "Computers",
       "author": "Ralph Johnson"
     },
     {
       "id": "61a6058e6c43f32854e51f52",
       "bookName": "Clean Code",
       "price": 43.15,
       "category": "Computers",
       "author": "Robert C. Martin"
     }
   ]
   

3. https://localhost:<port>/api/books/{id here}로 이동하여 컨트롤러의 오버로드된 Get 작업 메서드를 테스트합니다. 다음과 비슷한 JSON 응답이 표시됩니다.

   {
     "id": "61a6058e6c43f32854e51f52",
     "bookName": "Clean Code",
     "price": 43.15,
     "category": "Computers",
     "author": "Robert C. Martin"
   }
   

JSON serialization 옵션 구성

웹 API 테스트 섹션에서 반환된 JSON 응답에 대해 변경하는 두 개의 세부 정보가 있습니다.

• 속성 이름의 기본 카멜식 대/소문자는 CLR 개체의 속성 이름의 파스칼식 대/소문자와 일치하도록 변경되어야 합니다.
• bookName 속성은 Name으로 반환되어야 합니다.

앞의 요구 사항을 충족하기 위해 다음과 같이 변경합니다.

1. Program.cs에서 다음 강조 표시된 코드를 AddControllers 메서드 호출에 연결합니다.

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   
   builder.Services.AddControllers()
       .AddJsonOptions(
           options => options.JsonSerializerOptions.PropertyNamingPolicy = null);
   

   이전 변경으로 웹 API의 직렬화된 JSON 응답에서 속성 이름은 CLR 개체 형식의 해당 속성 이름과 일치합니다. 예를 들어 Book 클래스의 Author 속성은 author 대신 Author로 직렬화됩니다.

2. Models/Book.cs에서 BookName 속성은 [JsonPropertyName] 특성으로 주석이 추가됩니다.

   [BsonElement("Name")]
   [JsonPropertyName("Name")]
   public string BookName { get; set; } = null!;
   

   Name의 [JsonPropertyName] 특성 값은 웹 API의 직렬화된 JSON 응답의 속성 이름을 나타냅니다.

3. Models/Book.cs의 맨 위에 다음 코드를 추가하여 [JsonProperty] 특성 참조를 확인합니다.

   using System.Text.Json.Serialization;
   

4. 웹 API 테스트 섹션에 정의된 단계를 반복합니다. JSON 속성 이름의 차이를 확인합니다.

웹 API에 인증 지원 추가

ASP.NET Core Identity는 ASP.NET Core 웹앱에 UI(사용자 인터페이스) 로그인 기능을 추가합니다. 웹 API 및 SPA를 보호하려면 다음 중 하나를 사용합니다.

• Microsoft Entra ID
• Azure Active Directory B2C(Azure AD B2C)
• Duende Identity Server

Duende Identity Server는 ASP.NET Core용 OpenID Connect 및 OAuth 2.0 프레임워크입니다. Duende Identity Server에서는 다음과 같은 보안 기능을 사용할 수 있습니다.

• AaaS(Authentication as a Service)
• 여러 응용 프로그램 유형에 대한 SSO(Single Sign-On/Off)
• API에 대한 액세스 제어
• 페더레이션 게이트웨이

Important

Duende Software에서 Duende Identity 서버의 프로덕션 사용에 대한 라이선스 요금 지불을 요구할 수 있습니다. 자세한 내용은 ASP.NET Core 5.0에서 6.0으로 마이그레이션을 참조하세요.

자세한 내용은 Duende Identity Server 설명서(Duende Software 웹 사이트)를 참조하세요.

추가 리소스

• 샘플 코드 보기 및 다운로드(다운로드 방법)
• ASP.NET Core로 웹 API 만들기
• ASP.NET Core 웹 API의 컨트롤러 작업 반환 형식
• ASP.NET Core를 사용하여 웹 API 만들기