Skip to content

Fox Biz Service Overview

Fox Biz Service 는 다수의 비즈니스 로직 호출을 위한 단일 디스패처 역할을 수행합니다. 특히 Fox Web API 를 통해 웹 앱이나 원격 닷넷 클라이언트가 비즈니스 로직을 호출하고자 할 때 Fox Biz Service 를 사용하면 ASP.NET Web API 나 gRPC 와 같은 서비스 계층을 작성하지 않고도 비즈니스 로직을 호출할 수 있습니다.

Fox Biz Service

서비스 개념

클라이언트에게 노출할 비즈니스 로직 코드는 Fox Biz Service 가 등록하고 호출할 수 있도록 비즈 클래스로 표시되어야 합니다. 비즈 클래스는 FoxBizClassAttribute 특성을 사용하여 표시하며 비즈 클래스 내에서 클라이언트가 호출할 수 있는 메서드는 FoxBizMethodAttribute 특성을 사용하여 비즈 메서드로 표시되어야 합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
namespace BizSample;

[FoxBizClass]
public class MyBizLogic
{
    [FoxBizMethod]
    public string Echo(string message)
    {
        return "ECHO: " +message;
    }
}

Note

Fox Biz Service 와 Fox Web API 를 구성하는 구체적이고 단계적인 방법은 Fox Biz/Data Service 시작하기 문서를 참고하십시요.

클라이언트는 호출할 비즈니스 로직의 비즈 클래스 ID 와 비즈 메서드 ID 를 FoxBizRequest 객체에 담아 FoxBizService 의 Execute 메서드를 호출할 수 있습니다. 비즈 클래스 ID 는 기본적으로 비즈 클래스의 네임스페이스를 포함하는 전체 이름이며 비즈 메서드 ID 는 비즈 클래스 내에서 표시된 비즈 메서드의 이름입니다.

다음 코드는 Fox Web API 클라이언트를 사용하여 원격 서버의 Fox Biz Service 를 호출하는 예를 보여줍니다.

1
2
3
4
5
6
FoxBizRequest request = new("BizSample.MyBizLogic", "Echo");
request.Parameters["message"] = "Hello, Fox Biz Service World!";
FoxBizServiceClient client = new("api/bizservice");
FoxBizResponse response = client.Execute(request);
Console.WriteLine($"Biz Service Response: {response.Result}");
// Biz Service Response: ECHO: Hello, Fox Biz Service World!

FoxBizRequest 객체의 생성자를 통해 호출하고자 하는 비즈니스 로직의 비즈 클래스 ID(BizSample.MyBizLogic) 와 비즈 메서드 ID(Echo)를 지정하고, Parameters 속성에 비즈 메서드의 매개변수(message)를 설정한 후 Execute 메서드를 호출하면 Fox Biz Service 는 해당 비즈니스 로직을 호출하고 그 결과를 FoxBizResponse 객체에 담아 반환합니다.

Note

Fox Biz Service 는 Fox Web API 를 통해 웹 앱이나 데스크톱 앱과 같은 원격 클라이언트에서 백 엔드의 비즈니스 로직을 호출할 때 사용하는 것이 일반적입니다. ASP.NET Razor 페이지와 같은 서버 측 코드에서는 굳이 Fox Biz Service 를 사용하지 않고 곧바로 비즈니스 로직을 호출할 수 있기 때문입니다.

위 예제에서도 Fox Web API 클라이언트를 사용하여 원격 서버의 Fox Biz Service 를 호출하는 예를 보여주고 있지만, 동일 웹 서버의 Razor 페이지에서 비즈니스 로직을 호출하는 경우라면 Fox Biz Service 를 거치지 않고 곧바로 MyBizLogic 인스턴스를 생성하고 Echo 메서드를 호출하는 것이 더 효율적일 것입니다.

매개변수/결과값 바인딩

Fox Biz Service 는 FoxBizRequest 객체의 Parameters 컬렉션을 통해 전달된 비즈 메서드의 매개변수 자동으로 바인딩해 주며 비즈 메서드의 반환값을 FoxBizResposne 객체의 Result 속성에 자동으로 바인딩해 줍니다.

예를 들어 다음과 같이 name 매개변수를 사용하고 DataSet 을 반환하는 비즈 메서드가 존재할때,

1
2
3
4
5
6
7
8
[FoxBizMethod]
public DataSet SearchProduct(string name)
{
    FoxDbAccess dbAccess = FoxDbAccess.CreateDbAccess();
    var parameters = new { keyword = name + '%' };
    DataSet ds = dbAccess.ExecuteQueryDataSet("northwind.search_by_name", parameters);
    return ds;
}

클라이언트는 비즈 메서드의 name 매개변수를 전달하기 위해 FoxBizRequest 객체의 Parameters 컬렉션에 매개변수로 name 을 추가하면 됩니다.

1
2
3
4
5
FoxBizRequest request = new("BizLib2.BizLogic2", "SearchProduct");
request.Parameters["name"] = "CA";
FoxBizServiceClient client = new("api/bizservice");
FoxBizResponse response = client.Execute(request);
DataSet ds = (DataSet)response.Result;

또한, FoxBizResponse 객체의 Result 속성(object 타입)은 비즈 메서드가 반환한 DataSet 객체를 반환하므로 이를 형변환하여 사용할 수 있습니다.

매개변수 및 결과값 바인딩에 대한 구체적인 규칙은 기본 사용법 문서의 바인딩 항목을 참고 하십시요.

Note

Fox Web API 를 통해 Fox Biz Service 를 호출할 때 DataSet 과 같은 복잡한 타입은 타입 정보를 사용해야만(UseTypeInfo = true) 자동으로 역직렬화 됩니다. 타입 정보를 사용하지 않는 경우, 비즈 메서드가 DataSet 이나 일반적인 닷넷 타입을 반환하면 FoxBizResponse.Result 속성은 JsonElement 객체를 반환합니다.

다중 비즈 로직 호출

Fox Biz Service 는 단일 비즈니스 로직 호출 뿐만 아니라 다수의 비즈니스 로직을 한 번에 호출할 수 있는 기능도 제공합니다. 클라이언트는 여러 개의 FoxBizRequest 객체를 생성하여 FoxBizRequestCollection 객체에 담아 ExecuteMultiple 메서드를 호출하면 Fox Biz Service 는 각 비즈니스 로직을 순차적으로 호출하고 각각의 호출 결과를 FoxBizReposne 객체에 담고 이들을 다시 FoxBizResponseCollection 객체에 담아 반환합니다.

ExecuteMultiple 개념

진단 및 로깅

Fox Biz Service 는 비즈니스 로직 호출 시 발생할 수 있는 다양한 문제점을 파악하고 해결하기 위한 다양한 기능을 제공합니다. Fox Biz Service 는 비즈니스 로직 모듈들에서 비즈 클래스들을 스캔하는 과정을 비롯하여 Execute 메서드 혹은 ExecuteMultiple 메서드 호출 시 호출 과정을 추적할 수 있는 상세한 로그를 제공합니다. 그리고 이들 로그를 손쉽게 구분하고 파악하기 위해 로그 ID 를 제공하며 클라이언트에게 반환할 수 있습니다.

다음은 Fox Biz Service 가 생성하는 로그의 예를 보여줍니다. 로그 ID 는 #00010:41149443# 과 같이 로그의 시작과 끝에 표시되며, 클라이언트는 이 로그 ID 를 통해 특정 비즈니스 로직 호출과 관련된 로그를 쉽게 구분할 수 있습니다.

1
2
3
4
5
6
7
8
9
#00001:00000000#Start configuring ......
#00001:00000000#    Starting to load predefined biz modules:
#00001:00000000#        Loading assembly successfully: bizservice_app, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
#00001:00000000#        Biz class loaded : BizSample.MyBizLogic, 1 biz methods, id=BizSample.MyBizLogic
#00001:00000000#End configuring ......
#00010:41149443#>> Biz Service Start: Execute  Requests=1  UserId=  ClientMachine=  ClientIP=  ClientMAC=
#00010:41149443#      Before Execute BizMethod: ClassId=BizSample.MyBizLogic  MethodId=Echo  Type=BizSample.MyBizLogic  Method=Echo  in-params=1
#00010:41149443#      After Invoke: elpased = 112.0 msec, out-params:0
#00010:41149443#>> Biz Service End: Execute  elapsed = 117.3 msec

이외에도 비즈니스 로직을 수행하는 과정에서 발생하는 예외에 대한 상세한 정보, 성능 측정 정보 등을 로그에 기록하거나 클라이언트에게 반환할 수 있습니다. 이러한 진단 및 로깅 기능은 선택적으로 켜거나 끌 수 있으며, 상세한 내용은 Fox Biz Service 고급 사용법에서 로깅 관련 항목 을 참조 하십시요.

구성 설정

Fox Biz Service 는 비즈니스 로직을 포함하는 비즈 클래스가 어느 모듈에 존재하는지 알아햐 합니다. 이를 위해 구성 설정에는 "bizService:modules" 항목이 이 존재하며 Fox Biz Service 가 검색해야할 비즈니스 로직 모듈(어셈블리)들의 이름을 설정해야 합니다. modules 속성에는 어셈블리 이름 혹은 .dll 파일의 경로가 포함될 수 있습니다. 또한 와일드카드(*)를 사용하여 특정 폴더 내의 모든 .dll 파일을 검색하도록 설정할 수도 있습니다.

다음 구성 설정 조각은 비즈니스 로직 모듈로 BizLib1 어셈블리, BizLib2.dll 파일, 그리고 legacy 폴더 내의 모든 .dll 파일을 검색하도록 설정하는 예를 보여줍니다.

1
2
3
4
5
6
7
{
  ......
  "bizService": {
    "modules": [ "BizLib1", "BizLib2.dll", "./legacy/*.dll" ]
  }
  ......
}

FoxBizServiceConfig 정적 클래스의 Configure 메서드가 호출되면 구성 설정에 기록된 비즈니스 로직 모듈들을 검색하여 FoxBizClassAttribute 가 표시된 비즈 클래스들의 목록을 구성하며 클라이언트는 이렇게 구성된 비즈 클래스들만을 호출할 수 있습니다.

트랜잭션 고려 사항

Fox Biz Service 는 Fox Data Service 와 달리 자체적으로 트랜잭션에 관련된 기능을 제공하지 않습니다. 일반적으로 트랜잭션 처리는 비즈니스 로직의 일부분이며 복잡한 로직을 처리해야 하는 경우가 많으므로 비즈니스 로직이 트랜잭션을 관리하는 구조를 갖추어야 합니다. 이런 이유에서 Fox Biz Service 는 단순히 비즈니스 로직을 호출하는 기능만을 제공하며 트랜잭션의 시작/커밋/롤백 등의 처리는 비즈니스 로직 내에서 수행되어야 합니다.

비즈니스 로직이 간편한 트랜잭션 처리가 필요하다면 Fox Transactions 기능을 사용하여 FoxBizBase 클래스에서 파생된 클래스에 FoxBizClassAttribute 를 사용하면 비즈 메서드 호출 시 자동으로 트랜잭션이 시작되고 메서드 종료 시에 트랜잭션 커밋 혹은 롤백이 수행되도록 할 수 있습니다. Fox Transactions 기능을 사용하면 비즈니스 로직 내에서 트랜잭션을 직접 관리할 필요가 없으며, 비즈니스 로직의 복잡성을 줄이고 트랜잭션 처리를 간편하게 할 수 있습니다.

다음은 Fox Transactions 기능을 사용하는 비즈 클래스와 비즈 메서드의 예를 보여 줍니다. InsertTxData 메서드가 호출되면 트랜잭션은 자동으로 시작되며 오류가 발생하지 않는다면 트랜잭션은 자동으로 커밋되고, 오류가 발생하면 트랜잭션은 자동으로 롤백됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[FoxBizClass]
public class TxBizLogic : FoxBizBase
{
    [FoxBizMethod]
    public void InsertTxData(string data)
    {
        using TxDataAccess dac = new();
        ITxDataAccess itf = dac.CreateExecution<ITxDataAccess>();
        itf.InsertTestData(data);
    }
}

Summary

Fox Biz Service 는 백엔드에 존재하는 비즈니스 로직을 호출해주는 디스패처(dispatcher) 역할을 수행합니다. Fox Web API 혹은 ASP.NET Web API, gRPC 와 같은 원격 호출 기법을 사용하여 백엔드의 비즈니스 로직을 호출하고자 할 때 Fox Biz Service 는 간단한 비즈 클래스 ID, 비즈 메서드 ID 및 매개변수 바인딩 기능을 제공하여 손쉽게 비즈니스 로직에 접근할 수 있도록 해 줍니다.