Skip to content

README.ko-KR.md

Latest commit

 

History

History
138 lines (104 loc) · 9.94 KB

README.ko-KR.md

File metadata and controls

138 lines (104 loc) · 9.94 KB

xpTURN.MegaData 라이브러리

xpTURN.MegaData는 .NET에서 데이터 구조를 정의·관리하고 대량 데이터를 다루기 위한 라이브러리입니다. 구조 정의와 데이터 관리는 주로 Excel로 진행합니다.

직렬화에는 Google의 Protocol Buffers를 사용합니다. xpTURN은 표준 라이브러리 대신 자체 변형 버전을 사용하며, 자세한 내용은 아래 참고 섹션을 보시면 됩니다.

또한 .proto 파일 파싱 및 코드 생성을 위해서 protobuf-net 라이브러리가 활용됩니다. 단, protobuf-net.Reflection 라이브러리를 일부 변형하여 제공됩니다.

Supported Runtimes

  • .NET 8.0+
  • .NET Standard 2.1 (for Unity3D IL2CPP Scripting backend)
  • (C# Language Version 9.0)

기본 사용법

통합 방법은 USAGE를 참고하세요.

데이터 구조 정의

일반적인 Protocol Buffers는 .proto 파일을 쓰지만, xpTURN.MegaData는 Excel Define 시트를 사용합니다. 시트가 문서이자 정의 소스 역할을 합니다. 예시는 아래와 같습니다.

A B C D E F
1
2 Type Name Obsolete FType ExtraOptions Desc
3 Table PersonDataTable
4 Num Name Obsolete FType ExtraOptions
5 1 Map Map<SFixed32,PersonData>
6 Type Name Obsolete FType ExtraOptions
7 Table PersonData
8 Num Name Obsolete FType ExtraOptions
9 1 Id SFixed32 Data Index Id
10 2 IdAlias String Data Alias Name
11 3 Name String
12 4 Role RoleType
13 5 Email String
14 6 Phone String
15 Type Name Obsolete FType ExtraOptions
16 Enum RoleType
17 Num Name Obsolete FType ExtraOptions
18 0 None
19 1 Staff
20 2 Manager
21 3 Executive

코드 생성

Define 시트를 기준으로 xpTURN.ProtoGen으로 C# 및 .proto를 생성합니다. 생성된 코드를 프로젝트에 포함해 빌드한 뒤, 해당 어셈블리가 xpTURN.Converter에서 로드될 수 있도록 해야 합니다. 예: Sample1.

dotnet ./xpTURN.ProtoGen.dll --input="../../../Samples/DataSet/Sample1/[Define]" --output="../../../Samples/xpTURN.TableSet.Samples/Sample1" --output-type="cs;proto" --namespace="Samples" --tableset="Sample1TableSet" --for-datatable

생성 결과 예: Sample

데이터 입력

A B C D E F G H
1
2 PersonDataTable Id IdAlias Name Role Email Phone
3 PersonData 1000001 spot_one_001 Emily Parker Staff xxx111@zmall.com (415) 555-0134
4 PersonData 1000002 spot_one_002 James Mitchell Staff xxx222@zmall.com (415) 555-0135
5 PersonData 1000003 spot_one_003 Olivia Brooks Staff xxx333@zmall.com (415) 555-0136
6 PersonData 1000004 spot_one_004 Michael Hayes Manager xxx333@zmall.com (415) 555-0137
7 PersonData 1000005 spot_one_005 Sophia Bennett Executive xxx333@zmall.com (415) 555-0138

데이터 가공

시트 파일에 입력된 데이터 구조나 값을 그대로 사용하는 것이 아니라, 가공이 필요한 경우에는 TableSetPostProcess를 상속받아 포스트 프로세서를 직접 구현할 수 있습니다. 예시는 Locale.Type2를 참고하시기 바랍니다.

데이터 직렬화

Excel/JSON 데이터를 런타임용 바이너리로 변환합니다. 예:

dotnet ./xpTURN.Converter.dll --input="../../../Samples/DataSet/Sample1" --output="../../../Samples/DataSet/Sample1/[Result]" --namespace="Samples" --tableset="Sample1TableSet"

런타임에서 활용

var personData1 = Sample1TableSet.Instance.GetPersonData(1000001);
var personData2 = Sample1TableSet.Instance.GetPersonData("spot_one_001");
var boxDataTable = Sample1TableSet.Instance.GetBoxDataTable();
foreach(var pair in boxDataTable.Map)
{
    var box = pair.Value;
    Console.WriteLine($"Box : {box.Name}");
}

참고: OnDemand 또는 WeakRef를 사용하는 테이블은 Table.Map에 직접 접근하지 말고, GetXXXData 같은 접근자만 사용하세요.

참고

주의사항

직렬화가 Protocol Buffers 규격을 따르기 때문에, 메시지/필드 정의를 바꾸면 버전 간 호환성이 깨질 수 있습니다.

xpTURN.Protobuf 라이브러리

Google.Protobuf CSharp를 수정한 변형판입니다. 주요 특징은 Descriptor 관련 의존성이 제거되어 있고 FieldCodec 관련 수정사항과 커스텀 타입 지원 등을 위해서 일부 수정이 이루어졌습니다.

xpTURN.ProtoGen

시트 혹은 .proto에 정의된 메시지 정의를 바탕으로 c# 코드를 생성하는 툴입니다.

생성된 코드는 Google 'Protocol Buffers'의 protoc가 생성하는 결과물과 유사하지만, 코드 생성량을 최소화하고 데이터 관리에 필요한 코드가 추가되어 있습니다. 또한 .proto 문법에서 설정할 수 없는 커스텀 설정도 추가되어 있습니다.

protoc에서 생성한 코드 결과물과 차이점

  • Descriptor, Json, UnknownFields 관련 코드 생성하지 않음, WellKnownTypes 미지원
  • gRPC 지원 제거
  • 프로퍼티 대신 필드 사용, Attribute, Const 변수, Parser 코드 생성 최소화
  • xpFieldCodec, xpRepeatedCodec, xpMapCodec 사용
  • RepeatedField<>, MapField<> 대신 List<>, Dictionary<> 사용
  • xpTURN.MegaData를 위한 전용 코드 생성
  • xpTURN 전용 커스텀 타입 지원: DateTime, TimeSpan, Uri, Guid (내부적으로 UInt64, Int64, String, String으로 처리)

.proto 생성

xpTURN.ProtoGen 툴은 시트 문서를 기반으로 .cs 및 .proto 파일을 생성하는 기능을 갖추고 있습니다.

.proto 정의를 바탕으로 c# 코드 생성

xpTURN.ProtoGen 툴에서는 .proto 파일로 .cs 소스코드 생성을 지원합니다. xpTURN.Protobuf의 간소화된 버전의 c# 코드를 네트워크 패킷 등에 활용하고자 하는 경우에 사용할 수 있습니다.

참고. .proto 파서는 protobuf-net.Reflection 라이브러리를 활용하고 있습니다. c# 코드 생성 시 커스터마이징을 위해서 일부 내용이 수정되어 제공됩니다.

최적화

  • 런타임 코드는 Reflection 사용과 GC 부담을 줄이도록 설계되어 있습니다.
  • Save와 TablePostProcess는 디자인 타임용이라 성능 최적화 대상이 아닙니다.

지원

문의 사항이 있으신 경우 Github 이슈 등록 또는 email로 연락해주시기 바랍니다.