ASP.NET - .Net Core REST API Server 제작하기

728x90

.Net Core REST API Server 제작하기

Visual Studio 2022를 사용하여 Asp.net Core 프로젝트 템플릿을 사용하고 SQL Server를 데이터베이스로 사용하는 REST API를 제작하는 예제를 한 번 정리해보려고 한다. 본 프로젝트는 실무에서 사용되는 예시보단 특수한 상황을 위해 작성하는 것으로 실무에서 사용하는 내용과는 다소 차이가 있을 수 있다. 제한된 환경(라이브러리 사용 제한 등) 속에서 특정 기능 문제를 풀기 위해 만드는 내용으로 실무에서 사용하는 방법과는 차이가 많이 있다.

사용하고 있는 SW Tool은 아래와 같다.

Visual Studio 2022 Professional (Installed - .Net Desktop development, Data storage and Processing)
SQL Server 2022 Express
SQL Server 2019 Management Studio

본 포스팅은 아래 목차 순으로 내용이 작성될 예정이다.

ASP.NET Core Web API 프로젝트 생성
프로젝트 구조와 설명
Nuget Package - Entity Framework Core 설치
Entity Framework Scaffolding을 통한 DB 불러오기
샘플 Api Controller 만들고 실행 테스트하기

ASP.NET Core Web API 프로젝트 생성

Visual Studio을 실행하고 [Create a New Proejct]를 클릭하여 나타나는 화면에서 아래와 같은 프로젝트 템플릿을 선택한다.

ASP.NET Core Web App 템플릿은 별도의 Web Page 모두 생성되는 Template으로 별도의 웹 구현 없이 REST API만을 구현하는 용도라면 Web API 템플릿을 선택해서 진행하면 된다.

그리고 다음 화면에서 프로젝트를 저장할 위치와 이름을 입력하고 다음으로 넘어간다.

다음 화면에서는 이제 프로젝트 템플릿으로 생성할 옵션들을 선택하는 화면이다.

Framework는 당연 Long Term Support 오랫동안 지원이 가능하다고 하는 .Net 8.0 Framework 환경을 선택해 주면 된다.

Authentication Type은 애플리케이션 안에서 어떤 인증 방식을 사용할 것인지를 선택하는 옵션인데, 현재 나의 경우 별도의 인증 방식이 필요하지 않기 때문에 None 옵션을 선택하고 진행했다. (Local/인트라넷 내부에서 동작하는 REST API를 만드려고 하기 때문에 필요가 없다.)

또한, HTTPS 설정이 필요한 지를 묻는 [Configure for HTTPS] 옵션과 [Enable Container Support] 옵션도 당연 필요가 없다. 내가 하려고 하는 프로젝트는 보안적 조치가 필요한 상황이 아니기 때문에 불필요한 옵션들은 모두 체크를 해제하고 진행한다.

마지막으로 [Use Controllers]와 [Enable OpenAPI Support]만 체크를 선택하고 나머지는 모두 해제한다. Enable OpenAPI Support는 API를 Swagger로 쉽게 테스트할 수 있게 해주는 옵션이라 선택해 주는 것이 좋다. 옵션 중에 [Do not use top-level statements] 옵션이 있는데, 기존에는 프로젝트 생성 시 생성되는 기본적으로 생성되는 program.cs 파일에 main 함수가 존재하여 프로그램의 시작점 위치를 바로 알 수 있었고, 각 클래스 파일이 필요로 하는 라이브러리가 있는 경우 using 키워드를 사용해서 명시해서 사용해 주면 됐다. 그러나 .Net 버전이 올라감에 따라 global using 키워드를 사용하여 새로운 방식으로 프로그래밍을 작성할 수 있게끔 한 것이 top-level statements다. 이 부분은 취향에 따라 옵션을 사용해도 안 해도 된다.

최상위 문 - Main 메서드가 없는 프로그램 - C#

최상위 문에 대해 알아봅니다. 프로그램 클래스 및 Main 메서드의 형식 없이 프로그램을 만들 수 있습니다.

learn.microsoft.com

프로젝트 생성이 정상적으로 완료되면 아래와 같이 나타난다.

프로젝트 구조와 설명

프로젝트를 생성하면 솔루션 탐색기에서 아래와 같은 파일들을 확인할 수 있다.

생성된 각 파일들에 대해 하나씩 정리를 해보려고 한다.

Program.cs 파일

Program.cs 파일을 열어보면 main 함수가 없지만 일부 코드가 작성되어 있는 것을 볼 수 있다. main 함수가 없이 작성된 이것은 위에서 언급했던 Top-level Statements 방식으로 작성된 코드다.

Program.cs에서 주로 사용되는 객체인 WebApplicationBuilder 객체는 WebApplication 클래스의 CreateBuilder 메서드를 통해 생성되는데 이 객체는 웹 애플리케이션 및 서비스를 위한 객체다. 이 객체를 활용해 서비스에 필요한 기초 설정을 완료하고 마지막 Run() 메서드를 호출함으로써 서비스를 실행하는 것으로 보면 된다.

WebApplicationBuilder 클래스 (Microsoft.AspNetCore.Builder)

웹 애플리케이션 및 서비스를 위한 작성기입니다.

learn.microsoft.com

또 하나 .Net Framework로 제작할 수 있는 Asp.net Web Api와 조금 다른 점을 설명하자면 .Net Core로 작업할 때는 Swagger를 기본적으로 사용할 수 있게 지원하여, 별도의 페이지를 구현할 필요 없이 Swagger를 통해 내가 개발한 API를 웹을 통해 테스트하고 확인할 수 있다.

WeatherForecast.cs 파일과 WeathreForecastController.cs 파일

이 두 파일은 Visual Studio가 임시로 혹은 참고 용도로 만들어 둔 샘플 소스코드다. 참고용으로만 활용하고 필요 없는 경우 삭제해도 무방하다.

Properties - launchSettings.json

이 파일은 application 시작에 필요한 세팅값이 저장되어 있다. debug profile, environment variable 등이 들어 있다. 아래 그림을 보면 디버그 모드 상태에서의 포트 번호나 배포 시에 가질 url 정보 등을 여기서 입력해서 세팅할 수 있다.

Dependencies

프로젝트를 개발함에 있어 필요한 다른 Nuget Package를 설치(예를 들어 SQL Server를 사용한 작업 시 유용한 EntityFramework 등)하여 사용해야 하는데, .Net Framework 시절에는 관련 dll 라이브러리를 직접 프로젝트 내부 참조로 추가하는 방식이었지만, .Net Core로 오면서 dependency를 정보를 남겨 참조하는 라이브러리 버전을 관리할 수 있게 했다고 보면 된다.

Nuget Package - Entity Framework Core 설치

.Net Framework 개발 환경에서는 Entity Framework를 별도로 추가하거나 부가적인 작업 없이 DAO를 추가하여 자동으로 Entity Framework 라이브러리가 참조되게 할 수 있었는데, .Net Core로 넘어오면서부터는 Entity Framework를 사용하기 위해선 필요한 라이브러리를 Nuget Package에서 설치하여 Dependency를 추가하고 부가적인 작업을 수행해야만 Sql Server와 연결하여 사용할 수가 있다.

로컬에서 동작하는 REST API Server를 구현하기 위해 Entity Framework를 추가하여 사용하는 방법을 정리하려고 한다.

Nuget Package 설치

솔루션 탐색기에서 솔루션을 마우스 우클릭하여 나타나는 팝업 메뉴에서 [Manage NuGet Packages...] 메뉴를 클릭한다. 그러면 아래와 같은 화면이 나타나는데, 나타난 화면에서 3개의 탭 중에 [Browse] 탭을 눌러 EntityFrameworkCore를 검색한다.

검색하여 나타난 결과 중에서 위에 표시된 3개의 패키지들을 Install 하여 준다. Install 할 때는 각 패키지들의 버전을 동일하게 맞춰서 하는 걸 추천한다.

정상적으로 설치가 되면 다음과 같이 확인할 수 있다.

나는 설치하는 과정에서 최신 버전 9.0을 설치하려고 했으나 계속 NU1301 Nuget Package 에러가 뜨면서 설치를 할 수가 없었다. ( The local source 블라블라 doesn't exist 에러가 발생.) 도대체 뭐야 하다가 찾은 해결 방법은 다른 포스팅에 정리했다. 혹시 똑같은 에러가 뜨시는 분들은 아래를 참고하고 오시길...

2025.01.04 - [C#/Problem Solving] - (해결) ASP.NET - Nuget Package 설치 오류 (NU1301)

(해결) ASP.NET - Nuget Package 설치 오류 (NU1301)

해결 Nuget Package 설치 오류 (NU1301)ASP.Net Core Web API 프로젝트를 만들어서 진행하던 도중 Entity Framework Nuget Package를 설치하는 과정에서 최신 버전인 9.0 버전을 설치하려고 하는데 진행이 되지 않고 NU

it-hun-bar-2.tistory.com

Entity Framework Scaffolding을 통한 DB 불러오기

Nuget Package에서 Sql Server와의 작업을 위한 EntityFramework Core 패키지들을 설치를 완료하고 난 이후에는 Net Core에서는 Scaffold라고 하는 CLI 명령어를 사용해서 수동으로 Entity Framework 라이브러리를 사용하여 SQL Server와 연결 작업을 수행해줘야 한다.

Scaffold를 사용하여 DB와 연결하기 위해서는 Connection String을 알고 있어야 하는데 많이 사용하는 사람의 입장에서는 어느 순간 외워져 있겠지만 가끔 작업을 하는 사람의 입장에선 기억이 안 날 수 있다.

그럴 땐 Visual Studio에 있는 기능을 활용해서 아래와 같이 Connection String을 가져오면 된다.

Visual Studio 기능을 활용하여 Connection String 알아오기

Visual Studio 상단에 있는 [Tools] - [Connect to Database...] 메뉴를 클릭한다. 해당 메뉴를 선택하게 되면 아래와 같이 데이터베이스에 연결할 수 있게 도움을 주는 툴(혹은 옛날 말로 마법사(?))가 나타난다.

나타난 화면에서 로컬 Sql Server에 연결하는 것과 같이 Server Name과 기타 정보들을 입력하여 준다.

정보를 모두 입력하고 [OK] 버튼을 클릭한다. 입력을 완료하면 Visual Studio 내 Server Explorer 화면에서 아래와 같이 연결된 DB 정보를 확인할 수 있고, 해당 연결 정보를 클릭하여 Connection String을 얻어낼 수 있다.

위 화면에서 구한 Connection String 내용은 다음과 같다.

Data Source=.\SQLExpress;Initial Catalog=SampleDB;User ID=sa;Password=***********;Encrypt=True;Trust Server Certificate=True

위 String에서 Password는 현재 암호화되어 *으로 표시가 되고 있는데 Scaffold를 진행할 때는 해당 Password란에 Sql Server 연결 시 사용하는 계정의 패스워드를 정확히 입력해서 진행을 해야 한다.

Scaffold 기능 사용하기

위의 방법을 통해 Connection String을 구한 다음에는 이제 Nuget Package CLI를 사용해서 Scaffold 명령어를 사용하여 Sql Server에 있는 DB 정보를 프로젝트로 불러오면 된다.

그전에 Scaffold 명령어를 먼저 살펴보자.

Scaffold-DbContext “[Connection String]" Microsoft.EntityFrameworkCore.SqlServer -outputdir [ 폴더 경로 ] -context [Conext 이름]

위의 모든 명령어를 입력해도 되지만 다음과 같이 조금 더 축약해서 사용할 수 있다. Context 이름은 자동으로 생성되는 Context 이름을 사용한다는 가정하에 아래와 같이 수정하는 것이다.

Scaffold-DbContext “[Connection String]" Microsoft.EntityFrameworkCore.SqlServer -o [ 폴더 경로 ]

[Connection String]이라고 표시된 부분에는 위에서 구한 Connection String을 활용해서 입력하면 된다.

[폴더 경로]는 Sql Server에 연결해서 가져오는 DB 스키마 정보들을 어디에 저장할 것인지 프로젝트 폴더 이름을 입력하면 된다. 프로젝트 내에 미리 폴더를 만들어도 되지만, 만들지 않고 그냥 폴더를 입력해도 해당 이름으로 폴더를 생성하고 그곳에 DB 스키마 정보를 모두 불러오게 된다.

그럼 이제 Scaffold 명령어를 입력해 보자. Visual Studio 메뉴 중 [Tools] - [Nuget Package Manager] - [Package Manager Console] 메뉴로 접근한다.

위 메뉴로 접근하게 되면 Visual Studio 하단에서 Package Manager Console 창이 나타나는 것을 확인할 수 있다.

이 Console창에다 준비한 Scaffold 명령어를 입력한다. 내가 입력한 Scaffold 명령어는 다음과 같다.

Scaffold-DbContext “Data Source=.\SQLExpress;Initial Catalog=SampleDB;User ID=sa;Password=패스워드;Encrypt=True;Trust Server Certificate=True" Microsoft.EntityFrameworkCore.SqlServer -o Model

Console에 위 명령어를 입력하고 정상적으로 수행이 되면 Build succeeded 메세지와 함께 아래와 같은 화면을 볼 수 있다.

Scaffold가 완료되면 Visual Studio의 Solution 탐색기에서 Model 폴더가 생성이 되고 SQL Server에 있던 연결하려고 한 데이터베이스의 테이블들이 클래스 파일이 되어 생성된 것을 확인할 수 있다.

이렇게 불러온 이후로는 .Net Framework에서 Entity Framework를 사용하여 작업하던 것과 동일한 방법으로 개발을 진행하면 된다. DbContext 객체를 생성하고 이를 통해 테이블 데이터 조작(추가/수정/삭제)등의 작업을 진행하면 된다.

샘플 Api Controller 만들고 실행 테스트하기

Scaffold를 통해 DB 데이터를 모두 불러왔으니 이제 REST API를 실제로 동작시킬 Controller를 만들고 실행하여 테스트하는 것까지 살펴보자. Controller 클래스를 만들기 위해 Controller 폴더를 마우스로 우클릭하고 아래와 같이 메뉴를 선택한다.

그리고 나타난 화면에서 기본은 [Common] - [MVC] - [Controller] 탭이 선택이 되어 있겠지만, 현재 나는 MVC 패턴 기반으로 API를 만드는 것이 아니기에 [Common] - [API] 탭으로 선택하고 [API Controller - Empty] 기본을 선택한다.

그러면 또 다음과 같은 화면이 나타난다. 기본으로 선택되어 있는 API Controller - Empty 아이템을 그대로 선택하고 Controller의 이름만 변경하여 주면 된다. 현재 나는 DB에 있는 [User] 테이블을 사용하는 Controller를 만드려고 하기 때문에 UserController로 명명하였다.

API Controller - Empty 아이템을 그대로 선택하고 UserController로 이름을 명명한 모습

UserController 클래스를 생성하게 되면 위와 같이 나타나게 된다. 기본적으로 Route 경로를 잡아주고 있고 내부에는 아무것도 없는 형태로 클래스 파일이 만들어지게 된다. Route에 표시되어 있는 [controller] 부분에는 UserController에서 Controller앞에 입력한 "User"의 이름이 Route 경로에 사용되게 된다. 즉 이 파일에 만들어지는 API들은 url이 "api/user/"로 시작하게 되는 것이다. 여기에서 User의 목록을 반환하는 Get API를 하나 만들어보자.

[Route("api/[controller]")]
[ApiController]
public class UserController : ControllerBase
{
    private readonly SampleDbContext context;

    public UserController(SampleDbContext context)
    {
        this.context = context;
    }

    [HttpGet]
    public async Task<ActionResult<dynamic>> GetUsers()
    {
        var users = await context.Users.ToListAsync();

        return Ok(users);
    }
}

이렇게 작성하고 실행 버튼을 클릭해 보자. 나타난 Swagger를 통해 쉽게 내가 만든 API를 테스트할 수 있다. 각 API에 있는 [Try it out] 버튼을 클릭해서 테스트할 수 있다.

각 API의 [Try it out] 버튼을 클릭해서 테스트 할 수 있다.

Try it out 버튼을 클릭하면 위와 같이 Execute 버튼이 나타난다.

실행 결과 당연히 실패다. 내가 만든 UserController의 생성자를 보게 되면 Context 객체를 전달받아 사용하는 것을 보고 있는데 프로젝트 내 그 어떤 클래스를 뒤져봐도 Context 객체를 넘겨주는 코드를 볼 수가 없다. 근데 왜 이렇게 사용했냐면, Program.cs에 있는 WebApplicationBuilder 객체의 옵션을 설정하여 이 Context를 자동으로 넘겨줄 수 있게 할 수 있다.

이렇게 하지 않으면 매번 Controller 클래스를 만들 때마다 Context 객체를 new 해서 생성하는 코드를 하나하나 작성해줘야 하는 번거로움이 있다.

using REST_API_TEST.Model;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddDbContext<SampleDbContext>();
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
...

Program.cs 파일에 builder.Services.AddDbContext<SampleDbContext>(); 코드 한 줄을 추가하면 된다.

이렇게 하면 Web Service Builder가 자동으로 Api Controller를 실행할 때 DbContext 객체를 생성하여 넘겨주게 된다. 그래서 위와 같이 코드를 작성했던 것이다. 이렇게 Program.cs 파일에 코드 한 줄 추가하고 다시 실행을 해보자.

이렇게 해서 Asp.Net Core Web API 프로젝트를 만들고 Entity Framework를 사용해서 Sql Server와 연결하고 간단한 GET API까지 만들어보는 것을 해보았다. 다음에 기회가 된다면, GET, DELETE, POST, PUT API 모두를 만들고 활용하는 것에 대해 정리해 보겠다.