Skip to content

Fox Biz Service Request

Fox Biz Service 는 비즈니스 로직 호출에 필요한 정보를 담는 FoxBizRequest 혹은 FoxBizRequestCollection 객체를 입력으로 받아 비즈 메서드를 수행하고 그 수행 결과를 담는 FoxBizResponse 객체 혹은 FoxBizResponseCollection 객체를 반환합니다. Fox Biz Service 가 비즈니스 로직 수행 뿐만 아니라 비즈 메서드 수행 성능 측정, 진단 정보 수집 등의 다양한 기능을 제공하기 때문에 FoxBizRequest 객체도 비즈 메서드 호출 및 결과 수집에 필요한 정보 뿐만아니라 성능 정보, 진단 정보를 위한 다양한 정보를 담을 수 있도록 구성되어 있습니다.

FoxBizRequest 객체

FoxBizRequest 객체는 Fox Biz Service 가 비즈니스 로직을 수행하기 위해 필요한 정보를 담는 객체입니다. Fox Biz Service 는 등록된 비즈 클래스 내에 존재하는 비즈 메서드를 호출하기 때문에 반드시 포함되어야 할 정보로서 비즈 클래스/메서드 ID와 매개변수(필요한 경우)를 포함해야 합니다.

기본 속성들

  • ClassId 속성

    Fox Biz Service 가 수행할 비즈니스 로직에 대한 비즈 클래스를 나타내는 문자열입니다. 비즈 클래스는 FoxBizClassAttribute 특성이 설정된 public 클래스 입니다. FoxBizClassAttribute 특성에 아무런 매개변수도 사용하지 않으면 비즈 클래스 ID 는 네임스페이스를 포함하는 클래스의 전체 이름이 사용됩니다.

    1
2
3
4
    namespace BizLib;

[FoxBizClass]
public class BizLogic { ...... }

    위 예제에서 BizLogic 클래스의 비즈 클래스 ID 는 BizLib.BizLogic 으로 설정됩니다. 한편, 다음과 같이 FoxBizClassAttribute 특성에 비즈 클래스 ID 를 명시적으로 설정할 수도 있습니다.

    1
2
3
4
    namespace BizLib;

[FoxBizClass("MyBizClass")]
public class BizLogic { ...... }

    위 예제에서 BizLogic 클래스의 비즈 클래스 ID 는 MyBizClass 로 설정됩니다.

    비즈 클래스 ID 는 Fox Biz Service 전체에서 유일해야 합니다. Fox Biz Service 초기화 루틴이 동일한 비즈 클래스 ID 가 발견되면 예외가 발생하며 초기화 과정이 중단되거나 비즈 클래스의 등록이 취소될 수 있습니다.

    JSON 형태에서 ClassId 속성은 classId 속성으로 표현됩니다.

    1
2
3
4
    {
    "classId": "BizLib.BizLogic",
    "methodId": "HelloWorld"
}

  • MethodId 속성

    비즈 클래스 내에서 호출할 비즈 메서드를 나타내는 문자열 입니다. 비즈 메서드는 FoxBizMehtodAttribute 특성이 설정된 public 인스턴스 메서드입니다. FoxBizMethodAttribute 특성에 아무런 매개변수도 사용하지 않으면 비즈 메서드 ID 는 메서드 이름이 그대로 사용됩니다.

    1
2
3
4
5
6
    [FoxBizClass]
public class BizLogic
{
    [FoxBizMethod]
    public string Echo(string input) { ...... }
}

    위 예제에서 Echo 메서드의 비즈 메서드 ID 는 Echo 로 설정됩니다. 다음과 같이 FoxBizMethodAttribute 특성에 비즈 메서드 ID 를 명시적으로 설정할 수도 있습니다.

    1
2
3
4
5
6
    [FoxBizClass]
public class BizLogic
{
    [FoxBizMethod("EchoString")]
    public string Echo(string input) { ...... }
}

    위 예제에서 Echo 메서드의 비즈 메서드 ID 는 EchoString 으로 설정됩니다.

    비즈 메서드 ID 는 비즈 클래스 내에서 유일해야 합니다. Fox Biz Service 초기화 루틴이 비즈 클래스에서 동일한 비즈 메서드 ID 가 발견되면 예외가 발생하며 초기화 과정이 중단되거나 비즈 클래스의 등록이 취소될 수 있습니다.

    JSON 형태에서 MethodId 속성은 methodId 속성으로 표현됩니다.

    1
2
3
4
5
6
7
    {
    "classId": "BizLib.BizLogic",
    "methodId": "EchoString",
    "parameters": {
        "input": "Hello World!"
    }
}

  • Parameters 속성

    비즈 메서드를 수행할 때 필요한 매개변수들을 담는 FoxServiceParameterCollection 타입의 컬렉션입니다. FoxServiceParameterCollection 컬렉션은 기본적으로 딕셔너리(IDictionary<string, object>)와 동일하게 사용할 수 있으며 이외에도 null 값을 DBNull.Value 로 변경하는 기능(UseDBNull 속성 및 SetNullToDBNull 메서드) 등도 포함하고 있습니다.

    JSON 형태에서 Parameters 속성은 parameters 객체로 표현됩니다.

    1
2
3
4
5
6
7
    {
    "classId": "BizLib.BizLogic",
    "methodId": "Echo",
    "parameters": {
        "input": "Hello World!"
    }
}

  • ThrowException 속성

    비즈 메서드 수행 중 오류 발생 시 예외를 전파할 것인지 여부를 나타냅니다. 이 속성이 true 이면 서비스는 FoxBizServiceException 예외를 발생합니다. 이 속성이 false 이면 서비스는 예외를 발생시키지 않고 오류 정보를 FoxBizResponse 객체에 담아 반환합니다. 기본값은 true 입니다. Fox Biz Service 의 예외 처리 방식에 대한 상세한 내용은 Fox Biz Service 예외 처리 항목을 참조하십시오.

    JSON 형태에서 ThrowException 속성은 throwException 속성으로 표현됩니다.

    1
2
3
4
5
    {
    "classId": "BizLib.BizLogic",
    "methodId": "HelloWorld",
    "throwException": false
}

기타 속성

  • Diagnostics 속성

    Fox Biz Service 진단을 위한 플래그 속성입니다. 이 속성은 FoxBizRequestDiagnostics 열거 타입을 사용하며 다음과 같은 값을 가질 수 있습니다.

    • None : 진단 기능을 사용하지 않습니다. 디폴트 값입니다.
    • LogId : Fox Biz Service 가 비즈 메서드를 수행할 때 생성하는 로그 항목들에 대해 생성하는 로그 ID 를 응답 객체의 LogId 속성에 반환하도록 요청합니다.
    • ServiceLog : Fox Biz Service 가 비즈 메서드를 수행할 때 생성하는 로그 항목들을 응답 객체의 ServiceLog 속성에 반환하도록 요청합니다.
    • PerformanceInfo : Fox Biz Service 가 비즈 메서드를 수행할 때 수집하는 성능 정보를 응답 객체의 PerformanceInfo 속성에 반환하도록 요청합니다.
    • SuppressPerfLogWrite : Fox Biz Service 가 비즈 메서드를 수행할 때 수집하는 성능 정보를 서버 측 로그에 기록하지 않도록 요청합니다.

    JSON 형태에서 Diagnostics 속성은 diagnostics 속성으로 표현됩니다.

    1
2
3
4
5
6
    {
    "classId": "BizLib.BizLogic",
    "methodId": "HelloWorld",
    "diagnostics": "LogId,ServiceLog",
    ......
}

  • ClientInfo 속성

    ClientInfo 속성은 클라이언트의 컴퓨터 이름, IP, MAC 주소 등을 포함하는 FoxClientInfo 객체를 담는 속성입니다. 이 속성은 Fox Web API 클라이언트가 서비스를 호출할 때 원격 서비스가 클라이언트에 대한 정보를 수집할 수 있도록 제공됩니다. 이 속성 값은 읽기 전용으로 FoxBizRequest 객체가 생성될 때 FoxClientInfo.Instance 싱글톤 정적 값으로 자동으로 채워집니다.

    다음은 Fox Biz Service 가 ClientInfo 속성으로부터 수집한 클라이언트의 컴퓨터 이름, IP, MAC 주소 등 클라이언트 정보를 수집하여 로그에 출력한 예를 줍니다.

    1
2
    >> Biz Service Start: Execute  Requests=1  UserId=  ClientMachine=MYHOST  ClientIP=172.20.96.1  ClientMAC=0-15-5D-EF-FC-42
......

    JSON 형태에서 ClientInfo 속성은 clientInfo 속성으로 표현됩니다.

    1
2
3
4
5
6
7
8
9
    {
    "classId": "BizLib.BizLogic",
    "methodId": "HelloWorld",
    "clientInfo": {
        "machineName": "MYHOST",
        "ipAddress": "172.20.96.1",
        "macAddress": "0-15-5D-A3-23-4C"
    }
}

    Note

    일반적으로 클라이언트 정보는 Fox Web API Client 라이브러리를 사용하는 데스크톱 닷넷 클라이언트에서 제공되며 Javascript 기반의 웹 클라이언트는 클라이언트 정보를 제공하지 않습니다.

  • SerializeClientInfo 속성

    이 속성은 Fox Web API 클라이언트가 원격 서비스를 호출할 때 ClientInfo 속성에 담긴 클라이언트 정보를 직렬화하여 전송할 것인지 여부를 나타냅니다. 기본값은 true 입니다. 이 속성이 false 이면 ClientInfo 속성에 담긴 클라이언트 정보는 직렬화되지 않고 원격 서비스에 전달되지 않습니다.

    Fox Web API 클라이언트 클래스인 FoxBizServiceClient 클래스는 SendClientInfo 속성을 통해 이 속성 값을 변경합니다. 따라서 FoxBizRequest 객체의 SerializeClientInfo 속성은 FoxBizServiceClient.SendClientInfo 속성 값에 따라 자동으로 설정됩니다. 즉, SerializeClientInfo 속성은 Fox Web API 클라이언트를 사용할 때에는 직접 설정할 필요가 없으며 FoxBizServiceClient.SendClientInfo 속성을 통해 간접적으로 설정하면 됩니다.

    1
2
3
4
    FoxBizServiceClient client = new();
client.SendClientInfo = false; // 클라이언트 정보 직렬화하지 않음
FoxBizRequest request = new FoxBizRequest("BizLib.BizLogic", "HelloWorld");
client.Execute(request); // request.SerializeClientInfo 속성은 false 로 설정됨

    이 속성은 Fox Web API 의 클라이언트에서만 참조되고 사용되며 JSON 으로 직렬화되지 않습니다.

FoxBizRequestCollection 객체

FoxBizRequestCollection 객체는 여러 개의 FoxBizRequest 객체를 담는 리스트 스타일(IList<T>) 컬렉션입니다. Fox Biz Service 의 ExecuteMultiple 메서드는 이 컬렉션을 입력으로 받아 여러 개의 비즈 메서드를 한 번에 수행할 수 있습니다. FoxBizRequestCollection 객체는 다음과 같은 속성들을 통해 ExecuteMultiple 메서드 수행 시에 필요한 정보를 담을 수 있습니다.

컬렉션 기본 속성들

  • 인덱서 속성

    FoxBizRequestCollection 객체는 IList<T> 인터페이스를 구현하고 있으므로 인덱서를 통해 컬렉션에 포함된 FoxBizRequest 객체를 접근할 수 있습니다. ExecuteMultiple 메서드는 컬렉션에 포함된 각 FoxBizRequest 객체를 통해 순차적으로 비즈 메서드를 수행하므로 컬렉션 내에서 각 FoxBizRequest 객체의 순서가 중요합니다. 따라서 컬렉션에 포함된 각 FoxBizRequest 객체는 비즈 메서드를 수행할 순서대로 추가해야 합니다.

    FoxBizRequestCollection 객체는 다른 IList<T> 컬렉션과 같이 JSON 형태에서 items 속성에서 배열로 표현됩니다.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    {
    "items": [
        {
            "classId": "BizLib.BizLogic",
            "methodId": "HelloWorld"
        },
        {
            "classId": "BizLib.BizLogic",
            "methodId": "Echo",
            "parameters": { "input": "Hello World!" }
        }
    ]
}

  • ThrowException 속성

    예외가 발생했을 때 FoxBizServiceException 예외를 발생시켜 호출자에게 예외를 전파할 것인지 여부를 나타냅니다. 기본값은 true 입니다.

    이 값이 false 이고 예외가 발생하면 ExecuteMultiple 메서드는 FoxBizResponseCollection 객체의 Success 속성을 false 로 설정하고 ErrorInfo 속성에 예외 정보를 포함하여 반환합니다. 예외 정보를 담고 있는 FoxServiceErrorInfo 객체의 Index 속성은 컬렉션 내의 몇 번째 비즈 메서드를 수행하는 도중에 예외가 발생했는지를 나타냅니다.

    예외 처리에 대한 상세한 내용은 Fox Biz Service 예외 처리 항목을 참조하십시오.

    JSON 형태에서 ThrowException 속성은 FoxBizRequest 객체와 동일하게 throwException 속성으로 표현됩니다.

  • ContinueOnError 속성

    ExecuteMultiple 메서드 수행 중 예외가 발생한 경우, 나머지 비즈 메서드들을 계속 수행할 것인지 여부를 나타냅니다. 기본값은 false 입니다. 상세한 내용은 Fox Biz Service 예외 처리에서 Continue On Error 항목을 참조하십시오.

    JSON 형태에서 ContinueOnError 속성은 continueOnError 속성으로 표현됩니다.

    1
2
3
4
5
6
7
    {
    "throwException": false,
    "continueOnError": true,
    "items": [
        ......
    ]
}

컬렉션 기타 속성

  • Diagnostics 속성

    ExecuteMultiple 메서드 수행 시에 적용되는 진단 플래그 속성입니다. 이 속성은 FoxBizRequest 객체의 Diagnostics 속성과 동일하게 FoxBizRequestDiagnostics 열거 타입을 사용하며 기본값은 None 입니다.

    이 속성에 사용할 수있는 값들은 FoxBizRequest 객체의 Diagnostics 속성을 참고하십시요. 또한 이 속성을 통해 로그 ID, 요청 시 로그, 요청 시 성능 정보, 요청 시 DB 프로파일 정보 등을 사용하는 상세한 방법에 대해서는 Fox Biz Service 고급 사용에서 로깅 항목, 성능 측정 항목을 참조하십시오.

    JSON 형태에서 Diagnostics 속성은 diagnostics 속성으로 표현됩니다.

    1
2
3
4
5
6
    {
    "diagnostics": "LogId,ServiceLog,DbProfileInfo",
    "items": [
        ......
    ]
}

  • ClientInfo 속성

    FoxBizRequest 객체의 ClientInfo 속성과 동일하게 클라이언트 정보를 담는 FoxClientInfo 객체를 포함하는 속성입니다. 상세한 내용은 FoxBizRequest 객체의 ClientInfo 속성을 참고하십시요.

  • SerializeClientInfo 속성

    FoxBizRequest 객체의 SerializeClientInfo 속성과 동일하게 클라이언트 정보를 직렬화하여 전송할 것인지 여부를 나타내는 속성입니다. 상세한 내용은 FoxBizRequest 객체의 SerializeClientInfo 속성을 참고하십시요.

팩터리 클래스

FoxBizRequest 객체와 FoxBizRequestCollection 객체는 모두 생성자를 통해 생성할 수 있습니다. 하지만 때때로 생성자만으로는 충분하지 않은 경우가 있습니다. 예를 들어 클라이언트에서 전반적인 모든 비즈 메서드 호출에 대해 성능 측정이 필요할 수도 있습니다. 이 때 수많은 클라이언트 코드들에서 두 객체의 생성 코드에 Diagnostics 속성을 일일이 설정하는 것은 번거롭고 실수할 가능성이 있습니다.

이러한 상황에 대비하기 위해 Fox Biz Service 클라이언트 라이브러리는 FoxBizRequestFactory 클래스와 FoxBizRequestCollectionFactory 클래스를 제공합니다. 이 두 클래스에서 파생하여 Create 메서드를 오버라이드 하고 이 팩터리 객체를 FoxBizRequest.Factory 혹은 FoxBizRequestCollection.Factory 속성에 등록할 수 있습니다. 이제 FoxBizRequest.Create 메서드 혹은 FoxBizRequestCollection.Create 메서드를 사용하면 이들 팩터리 클래스를 통해 객체를 생성하게 됩니다.

다음은 FoxBizRequestFactory 클래스를 상속하여 Create 메서드를 오버라이드 하는 간단한 FoxBizRequest 팩터리를 구현한 예제입니다. SimpleRequestFactory 클래스는 진단 모드를 설정하여 팩터리를 통해 생성되는 모든 FoxBizRequest 객체에 ServiceLog, PerformanceInfo 등의 진단 플래그를 설정할 수 있도록 구성되어 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
internal class SimpleRequestFactory(bool useDiagMode = false) : FoxBizRequestFactory
{
    public bool DiagnosticsMode { get; set; } = useDiagMode;

    public FoxBizRequestDiagnostics Diagnostics { get; set; } = FoxBizRequestDiagnostics.ServiceLog;

    // 팩터리 메서드 재정의
    public override FoxBizRequest Create(string? queryId, string? databaseName = null, IDictionary<string, object?>? parameters = null, DataSet? dataSet = null)
    {
        FoxBizRequest request = base.Create(queryId, databaseName, parameters, dataSet);
        if (this.DiagnosticsMode == true)
        {
            request.Diagnostics = this.Diagnostics;
        }
        else
        {
            request.Diagnostics = FoxBizRequestDiagnostics.None;
        }
        return request;
    }
}

FoxBizRequestFactory 클래스에서 파생된 팩터리는 FoxBizRequest.Factory 속성에 등록하여 FoxBizRequest.Create 메서드를 통해 생성되는 모든 요청 객체에 다음과 같이 일괄적으로 적용할 수 있습니다.

1
2
3
4
5
// 신규 팩터리 등록
FoxBizRequest.Factory = new SimpleRequestFactory(true);
// 팩터리를 통해 FoxBizRequest 객체 생성
FoxBizRequest request = FoxBizRequest.Create("BizLib.BizLogic", "HelloWorld");
client.Execute(request);

Note

물론, 다른 팩터리 패턴을 사용하여 FoxBizRequest 객체를 생성하도록 구현할 수도 있습니다. 하지만 FoxBizRequest.Create 메서드는 Fox Web API 클라이언트에서 FoxBizRequest 객체를 생성할 때 내부적으로 사용하므로 이 메서드를 통해 생성되는 모든 요청 객체에 일괄적으로 적용할 수 있습니다. 예를 들어, Fox Web API 클라이언트의 Execute 메서드는 FoxBizRequest 객체 외에도 비즈 클래스 ID, 비즈 메서드 ID, 파라미터 등을 인자로 받아 내부적으로는 FoxBizRequest.Create 메서드를 호출하여 요청 객체를 생성합니다.

1
2
FoxBizRequest.Factory = new SimpleRequestFactory(true);
client.Execute("BizLib.BizLogic", "HelloWorld");    // 내부적으로 팩터리 사용

Summary

FoxBizRequest 객체와 FoxBizRequestCollection 객체는 Fox Biz Service 를 호출하기 위해 다양한 정보를 포함합니다. 핵심적인 비즈 클래스 ID, 비즈 메서드 ID, 파라미터 등의 정보를 포함하며, 필요에 따라 진단 정보도 설정할 수 있습니다. 이러한 객체들은 생성자뿐만 아니라 팩터리 클래스를 통해서도 생성할 수 있으며, 팩터리를 사용하면 일관된 방식으로 객체를 초기화할 수 있습니다.