Getting Started: Controller-based Web API¶
NeoDEEX 5.x 는 이전 버전과 마찬가지로 ASP.NET Core 의 Web API MVC 컨트롤러 프레임워크를 통해 Fox Biz/Data Service Web API 를 제공할 수 있습니다. 이 문서는 MVC 컨트롤러를 사용하여 Fox Biz/Data Service Web API 를 사용하는 방법을 구체적으로 설명합니다.
Overview¶
ASP.NET Core 는 ControllerBase
클래스와 ApiControllerAttribute
특성을 통해 Web API 컨트롤러 기능을 제공합니다. NeoDEEX 5.x 는 ControllerBase
클래스와 ApiControllerAttribute
특성이 적용된 FoxBizServiceController
클래스와 FoxDataServiceController
클래스를 NeoDEEX.ServiceModel.WebApi
패키지를 통해 제공합니다. 간단한 MVC 컨트롤러 설정을 통해 최소의 코드를 사용하여 Web API 를 구성할 수 있으며, 추가적인 Web API 컨트롤러를 정의하여 다양한 수준의 커스터마이징이 가능합니다.
이 문서를 통해 Visual Studio 를 사용하여 MVC 컨트롤러 기반 Web API 프로젝트를 생성하고 Fox Biz/Data Service Web API 를 추가하는 방법에 대해 단계적으로 예제를 통해 설명합니다.
Creating a web api project¶
먼저, Visual Studio 를 사용하여 ASP.NET Core Web API 프로젝트를 생성합니다.
Note
이 문서에서 Visual Studio Code 를 사용하는 방법에 대해서는 설명하지 않습니다. 하지만, Visual Studio Code를 사용하여 동등한 기능을 동일하게 작성할 수 있습니다. 구체적인 방법은 MSDN의 Create a controller-based web API 예제를 참고하십시요.
-
Visual Studio 에서 새 프로젝트를 생성을 수행합니다.
-
프로젝트 템플릿에서
ASP.NET Core Web API
템플릿을 선택합니다. -
프로젝트 이름을 입력합니다. 이 예제에서는
ControllerWebApi
라는 이름을 사용하였습니다. -
프로젝트 추가 정보에서, 프레임워크로
.NET 8.0
을 선택하고Do not use top-level statements
와Use controllers
옵션을 선택합니다.Info
Create a controller-based web API 예제
Enable OpenAPI support
옵션을 선택하였지만 Fox Biz/Data Service 는 OpenAPI 와는 다른 접근 방식이므로 이 예제에서는 선택하지 않았습니다. OpenAPI 지원에 대한 사항은 이 문서를 참고 하십시요. -
생성된 프로젝트에서 사용하지 않을
WeatherForecast.cs
파일과WeatherForecastController.cs
파일을 제거하고, 혼동을 막기위해WeatherForecast.http
파일을test.http
로 이름을 변경합니다. -
Fox Biz/Data Service 에 대한 Web API 컨트롤러를 구성하기 위해
NeoDEEX.ServiceModel.WebApi
패키지를 프로젝트에 추가합니다. 프로젝트에 대한 NuGet 패키지 관리자를 구동하고NeoDEEX.ServiceModel.WebApi
패키지를 검색하여 설치 합니다. -
Program.cs
파일의Main
메서드에서 Fox Biz/Data Service 에 대한 컨트롤러를 추가하도록AddFoxWebApiControllers
메서드 호출을 추가합니다. -
프로젝트를 빌드하고 수행합니다. 브라우저가 구동되면 주소 창에 서비스의 About 페이지 주소를 입력하여 Fox Biz Service Web API 가 정상적으로 구성되었는지 확인합니다.
Warning
주어진 url 에서 포트 번호는 프로젝트마다 다른 값이 사용되므로 해당 프로젝트에 맞추어 변경해야 합니다.
정상적으로 설정이 되었다면 다음과 같은 About 페이지를 볼 수 있습니다.
Fox Data Service Web API 역시 다음 About 페이지 주소를 사용하여 테스트가 가능합니다.
Configuring Fox Biz Service¶
Fox Biz Service 를 통해 비즈니스 로직 코드를 호출하기 위해서는 비즈니스 로직 코드가 포함된 비즈 모듈을 작성하고 등록해야 합니다. 개발 편의성을 높이기 위해 비즈니스 로직 코드를 Web API 프로젝트에 직접 작성할 수도 있지만, 기업용 어플리케이션과 같이 규모가 큰 경우 수십, 수백개의 비즈니스 로직 코드가 존재할 수도 있습니다. 따라서 별도의 라이브러리 프로젝트를 사용하여 비즈니스 로직 코드를 작성하는 것이 일반적입니다.
-
솔루션에 Class Library 프로젝트를 추가 합니다. 이 예제에서 프로젝트의 이름은
BizLogicModule
으로 지정하였습니다. -
추가된 라이브러리 프로젝트에 비즈니스 로직 작성을 위해
NeoDEEX.ServiceModel.Services
패키지를 추가 합니다. -
프로젝트 생성과 함께 생성된
Class1.cs
파일의 이름을BizLogic.cs
로 변경합니다. -
BizLogic.cs
파일을 열고 내용을 다음과 같이 수정합니다.Note
FoxBizClassAttribute
와FoxBizMethodAttribute
는 Fox Biz Service 가 클라이언트에게 노출할 클래스와 메서드를 결정하는데 중요합니다. 이 두 특성이 명시되지 않으면 클라이언트는 비즈 서비스를 호출할 수 없습니다. -
BizLogicModule
라이브러리를 Web API 프로젝트가 사용할 수 있도록ControllerWebApi
프로젝트에서 참조를 추가 합니다. -
비즈니스 로직 모듈을 등록하기 위해 구성 설정 파일이 필요합니다.
ControllerWebApi
프로젝트에서 아이템 추가 메뉴를 선택하여 JSON 파일을 추가 합니다. 파일 이름은neodeex.config.json
이어야 합니다.Warning
NeoDEEX 는 기본적으로 구성 설정 파일로 neodeex.config.json 을 사용합니다. 이를 변경하기 위해서는
FoxConfigurationManager
클래스의ConfigurationFileName
정적 속성을 설정해야 합니다. -
neodeex.config.json
구성 설정 파일이 Output 폴더에 복사되도록 이 파일의Copy to Output Directory
속성의 값이Copy if newer
로 설정되었는지 확인합니다. -
neodeex.config.json
구성 설정 파일의 내용을 다음과 같이 추가 합니다.Warning
modules
배열에 포함될 내용은 라이브러리 프로젝트의 이름입니다. 이 예제에서 사용한 라이브러리 이름(BizLogicModule
)이 아닌 다른 이름을 사용했다면 해당 이름을 명시해야 합니다. -
Program.cs 파일의 Main 메서드에서 설정한 비즈니스 로직 모듈을 로드하도록
ConfigureBizService
메서드 호출을 추가 합니다. -
솔루션을 빌드하고
Ctrl+F5
혹은F5
키를 눌러ControllerWebApi
프로젝트를 수행하고 정상적으로 Web API 가 구동되는지 확인합니다.Note
neodeex.config.json
구성 파일에 오타가 존재하거나 명시된 비즈니스 모듈을 찾을 수 없는 상황과 같은 오류가 존재하는 경우, Web API 프로젝트는 정상적으로 구동되지 않고 예외가 발생합니다. 예외 메시지를 검토하면 대부분 오류의 원인을 찾을 수 있습니다. -
추가한 비즈니스 로직을 확인하기 위해
test.http
파일을 다음과 같이 수정합니다.Note
POST 요청에 사용된 JSON 에서
classId
속성과methodId
속성의 값은 비즈니스 로직 클래스의 이름과 메서드 이름으로 일치해야 합니다. 예제에서 사용한 네임스페이스, 클래스, 메서드 이름과 다른 이름을 사용했다면 해당 이름이 사용되어야 합니다. 비슷하게,Echo
메서드의 매개변수 이름과parameters
객체에 사용된message
속성이 이름도 동일해야 합니다.Warning
이 예제에서
ControllerWebApi_HostAddress
변수에 사용된 url 의 포트 번호는5097
이지만 포트 번호는 프로젝트마다 달라지므로 수정 할 때 주의가 필요합니다. -
test.http
파일에서 추가된 POST 요청에 대해Send request
버튼을 클릭하여 Web API 를 호출하고,BizLogic
클래스의Echo
메서드의 반환값이 응답으로 반환되는지 확인합니다.Tip
정상적인 응답이 오지 않는 경우 오류에 따라 원인을 찾을 수 있습니다.
- HTTP 404 NotFound 상태값이 반환되었다면 POST 요청의 url 을 확인하십시요.
-
HTTP 500 Internal Server Error 상태값이 반환되었다면 반환된 JSON 에 상세한 오류 메시지를 알 수 있습니다. 예를 들어,
methodId
에 잘못된 메서드 이름이 사용되었다면, 응답 JSON 은 다음과 같은 오류 메시지를 반환할 것입니다.{ "message": "There is no method with the method id('Echo2'). Type: BizLogicModule.BizLgic", "messageDetail": "NeoDEEX.ServiceModel.Services.Biz.FoxBizServiceException: There is n method w ith the method id('Echo2'). Type: BizLogicModule.BizLogic", ... 생략 ... }
이 경우, POST 요청 JSON 의
methodId
속성을 확인하거나 비즈니스 로직 클래스의 메서드 이름을 확인하십시요. 혹은, 클래스와 메서드에FoxBizClass
특성과FoxBizMethod
특성이 추가되었는지도 확인하십시요.
Configuring Fox Data Service¶
앞서 설명한 대로 NeoDEEX.ServiceModel.WebApi
패키지를 추가하고 AddFoxWebApiControllers
메서드를 호출하면 Fox Data Service Web API 를 구성할 수 있지만 실제로 데이터베이스에 대해 쿼리를 수행하고 결과를 받기 위해서는 데이터베이스 연결을 위한 추가 설정 작업과 FoxQuery 파일을 추가해야 합니다.
-
ControllerWebApi
프로젝트에 대해 NuGet 패키지 관리자를 구동하고 사용자의 데이터베이스에 따라서 다음 패키지들 중 하나를 선택하여 설치하도록 합니다. 이 예제에서는 SQL Server 의 Northwind 데이터베이스를 액세스하기 때문에NeoDEEX.Data.SqlClient
패키지를 설치할 것입니다.- SQL Server :
NeoDEEX.Data.SqlClient
- Oracle :
NeoDEEX.Data.OracleClient
- PostgreSQL :
NeoDEEX.Data.NpgsqlClient
- MySQL :
NeoDEEX.Data.MySqlClient
- ODBC :
NeoDEEX.Data.Odbc
- SQL Server :
-
neodeex.config.json
구성 설정 파일을 열고, 데이터베이스 연결 문자열 설정을 다음과 같이 추가합니다. -
FoxQuery 파일을 추가하기 위해
ControllerWebApi
프로젝트에Foxml
폴더를 추가 합니다.Note
구성 설정에
queryMappers
설정을 추가하지 않는 경우,FoxDbAccess
는 자동으로./foxml
폴더에서 FoxQuery 파일들을 읽도록 쿼리 매퍼를 구성합니다. -
추가된
foxml
폴더에 FoxQuery 파일을 추가합니다. 프로젝트 아이템 추가 메뉴를 선택하고 XML 파일 템플릿을 선택하며 파일 이름으로Northwind.foxml
을 지정합니다.Warning
FoxQuery 파일의 확장자는 반드시
.foxml
이어야만 합니다. -
구성 파일과 마찬가지로 추가된
Northwind.foxml
파일의Copy to Output Directory
속성의 값을Copy if newer
으로 지정하십시요. 이 설정이 없다면.foxml
파일이 복사되지 않기 때문에 Fox Data Service 호출에서 오류가 발생하게 됩니다. -
Northwind.foxml
파일의 내용에 다음과 같이 SQL 문장을 입력하십시요. -
Fox Biz Service 테스트와 동일하게
test.http
파일을 편집하여 Fox Data Service 를 호출하도록 POST 를 다음과 같이 추가합니다.호출하고자 하는 FoxQuery의 아이디를
queryId
속성에 명시하였음에 주목하십시요. FoxQuery 아이디는 FoxQuery 파일 이름(Northwind
)과 파일 내에 존재하는 쿼리의 아이디(GetProducts
)를 콜론 문자로 조합한 것입니다.Warning
POST 요청의 JSON 에서
parameters
객체에 의해 전달되는 매개변수는IDictionary<string, object>
타입으로 역직렬화되어 FoxQuery 에 전달됩니다. Dictionary 타입에서 키(key)는 대소문자를 구별하므로 FoxQuery에서 사용된 매개변수 이름과 정확히 일치하도록 제공되어야 합니다. -
Send request
버튼을 클릭하여 FoxQuery 가 수행되고 그 결과가 정상적으로 반환되는지 확인하십시요.
Customizing Web API¶
MVC 컨트롤러를 사용하는 Fox Biz/Data Service Web API 는 FoxBizServiceControllerBase 및 FoxDataServiceControllerBase 클래스와 여러 특성(attribute) 클래스를 사용하여 커스터마이징이 가능합니다. 이 예제에서는 Web API 에 대한 Url, 수행 결과를 반환하는 JSON 에 테이터 타입 포함 여부 등을 설정하는 방법을 살펴볼 것입니다.
Url customizing¶
ASP.NET Core Web API 컨트롤러는 .NET Framework 4.x 버전과 달리 컨트롤러에 대한 url 라우팅을 컨트롤러 클래스의 RouteAttribute
특성으로만 지정이 가능합니다. 따라서 AddFoxWebApiControllers
메서드 호출에 의해 자동으로 구성되는 FoxBizServiceController
클래스는 /api/bizservice/{action}
을, FoxDataServiceController
클래스는 /api/dataservice/{action}
을 라우팅 템플릿으로 사용합니다.
Web API 에 대한 url 을 변경하고자 하는 경우, FoxBizServiceControllerBase
혹은 FoxDataServiceControllerBase
클래스에서 파생된 컨트롤러 클래스를 정의하고 RouteAttribute
특성을 추가해야 합니다. 별도의 복잡한 코드를 작성할 필요없이 새로운 Controller 를 추가하고 특성을 명시함하면 간단히 서비스에 대한 url 을 변경할 수 있습니다.
-
ControllerWebApi
프로젝트의Controllers
폴더에MyBizServiceController
클래스를 추가 합니다. -
MyBizServiceController.cs
파일의 내용을 다음과 같이 입력합니다.Web API 의 url 을 커스터마이징 하기 위해
RouteAttribute
클래스가 사용되었고 라우팅 템플릿으로biz/service
가 사용되었음에 주목하십시요.Warning
Microsoft.AspNetCore.Mvc
네임스페이스가 사용되었음에 주의하십시요.RouteAttribute
클래스는 다른 네임스페이스(Microsoft.AspNetCore.Components
)에도 동일한 이름의 클래스가 존재하기 때문입니다. -
솔루션을 빌드하고 수행 시킵니다. 브라우저가 구동되면 주소 창에 About 페이지의 주소를 입력하여 Web API 가 변경된 url 으로도 잘 구성되었는지 확인하십시요.
-
test.http
파일을 열고, Fox Biz Service Web API 를 테스트하는 POST 요청의 url 을 다음과 같이 수정합니다. 새로이 추가된MyBizServicController
클래스에 설정된RouteAttribute
를 참조 하십시요.Send request
버튼을 클릭하여 이전과 동일한 결과가 반환되는지 확인하십시요.
UseTypeInfo setting¶
기본적으로 Fox Biz/Data Service 는 서비스 호출 결과를 반환할 때 데이터 타입도 반환합니다. 앞서 Fox Biz Service 호출을 테스트한 결과를 상세히 살펴보면 다음과 같습니다.
Fox Biz Service의 호출 결과는 result
속성을 통해 반환되는데, 이 결과가 string
타입임을 나타내는 $type
속성 역시 포함하고 있습니다. $type
을 통해 제공되는 데이터 타입 정보는 C# 과 같이 타입에 강력하게 연결된 환경에서는 유용하지만 Javascript 와 같이 데이터 타입에 구애 받지 않는 환경에서는 불편한 요소가 됩니다.
일반적으로 이러한 설정은 구성 설정 파일에서 webApiServer
섹션에서 설정이 가능합니다. 이 설정은 Controller 기반 Web API 및 Minimal Web API 를 포함하여 전체 Biz/Data 서비스에 모두 영향을 줍니다. 하지만 특정 서비스에서만 결과 JSON 의 데이터 타입 반환 여부를 설정하고자 하는 경우, Web API 컨트롤러에 FoxServiceResultAttribute
특성을 명시할 수 있습니다.
-
앞서 예제에서 추가한
MyBizServiceController.cs
파일을 열어FoxServiceResultAttribute
특성을 추가합니다. 이 특성의 매개변수로UseTypeInfo
속성을false
로 지정합니다. -
test.http
파일에서 이전에 비즈 서비스 테스트에 사용했던 POST 요청을 그대로 다시 호출에 사용하고 결과에 타입 정보($type
속성)가 존재하지 않음을 확인하십시요.
Other customizing¶
NeoDEEX.ServiceModel.WebApi 패키지에는 FoxServiceResultAttribute
특성 뿐만 아니라 예외 발생 시 상세한 오류 정보를 JSON 으로 클라이언트에게 반환해 주는 FoxServiceExceptionHandlerAttribute
특성, HTTP Body 에서 FoxBizReuqest
혹은 FoxDataRequest
를 역직렬화(모델 바인딩)하는 FoxFromBodyAttribute
특성 등을 제공합니다. 이들을 통해 다양하게 Web API 를 커스터마이징할 수 있습니다.
예를 들어, Fox Biz Service 를 호출하기 위해 인증된 클라이언트 만을 허용한다고 가정해 봅시다. 이 때 로그인을 위한 Login
메서드는 인증되지 않은 사용자도 호출이 가능해야 합니다. 이와 같은 상황을 처리하기 위해 Web API 컨트롤러에 Login
메서드를 추가하고 FoxAuthorizeAttribute
를 추가하여 인증되지 않은 사용자도 호출이 가능하도록 설정이 가능합니다.
Summary¶
MVC 컨트롤러 기반의 ASP.NET Core Web API 는 매우 간단한 코드로 Fox Biz/Data Service 에 대한 Web API 를 구성할 수 있도록 해주며 다양한 특성들을 통해 높은 수준의 Web API 커스터마이징이 가능하게 해 줍니다. 상세한 내용은 Fox Biz/Data Service Web API 에 관련된 다양한 문서들을 참고 하십시요.