문서 정보
* 작성일: 2026-03-21
* 대상: UBi3 Framework 기반 업무화면 개발자
* 템플릿: UBi_FORM_SEC
* 프레임워크 버전: UBi3 / .NET Framework 4.7.2

UBi 프레임워크는 유비덤(UBiDum)에서 개발한 WinForm 기반 업무화면 개발 프레임워크입니다. 개발자는 UBi_FORM_SEC 템플릿 프로젝트를 복사하여 새로운 업무화면을 빠르게 구성할 수 있습니다.

UBi_FORM_SEC/
├── Properties/
│   ├── AssemblyInfo.cs          ← 어셈블리 메타정보 (프로젝트명, 설명)
│   ├── licenses.licx            ← DevExpress 라이선스
│   ├── Resources.resx           ← 리소스 정의
│   └── Resources.Designer.cs    ← 리소스 자동 생성 코드
├── UBi_FORM_SEC.cs              ← ★ 메인 비즈니스 로직 (개발자 작성 영역)
├── UBi_FORM_SEC.Designer.cs     ← ★ 디자이너 코드 (Visual Studio 디자이너)
├── UBi_FORM_SEC.resx            ← 폼 리소스
└── UBi_FORM_SEC.csproj          ← 프로젝트 파일

개발자가 직접 코드를 작성하는 파일입니다. BaseModule을 상속받아 업무화면을 구현합니다.

Visual Studio 디자이너가 자동 생성하는 파일입니다. 컨트롤 배치, DataAdapter 설정, 컬럼 정의 등이 포함됩니다.

빌드 설정, 참조 DLL, PostBuild 이벤트(afterbuild) 등을 정의합니다.

1. UBi_FORM_SEC 폴더를 복사합니다
2. 폴더명을 새 업무화면 ID로 변경합니다 (예: UBi_FORM_ORD001)
3. 폴더 내 모든 파일명에서 UBi_FORM_SEC를 새 이름으로 변경합니다

예) UBi_FORM_SEC → UBi_FORM_ORD001
    UBi_FORM_SEC.cs → UBi_FORM_ORD001.cs
    UBi_FORM_SEC.Designer.cs → UBi_FORM_ORD001.Designer.cs
    UBi_FORM_SEC.csproj → UBi_FORM_ORD001.csproj
    UBi_FORM_SEC.resx → UBi_FORM_ORD001.resx

UBi_FORM_SEC.cs와 UBi_FORM_SEC.Designer.cs 파일에서 클래스명을 변경합니다.

// 변경 전
public partial class 프로젝트명을지정하시오 : BaseModule
 
// 변경 후 (예시)
public partial class UBi_FORM_ORD001 : BaseModule

클래스 상단의 XML 주석을 작성합니다.

/// <summary>
/// 주문등록 화면
/// 고객 주문을 등록하고 관리하는 화면입니다.
/// 작성자 : 홍길동
/// 작성일 : 2026-03-21
/// </summary>
[ToolboxItem(false)]
public partial class UBi_FORM_ORD001 : BaseModule

Properties/AssemblyInfo.cs에서 어셈블리 정보를 수정합니다.

[assembly: AssemblyTitle("UBi_FORM_ORD001")]
[assembly: AssemblyDescription("주문등록 화면")]

1. Visual Studio에서 솔루션 열기
2. 솔루션 탐색기 → 우클릭 → 기존 프로젝트 추가
3. 새로 만든 .csproj 파일 선택

System.Windows.Forms.UserControl
  └─ BaseModule (UBi.WinForm.Controls)
       └─ 업무화면 클래스 (개발자 작성)

BaseModule은 MDI 자식 폼으로 동작하며, 공통 버튼 인터페이스(IButton)를 제공합니다.

화면의 데이터 접근을 총괄하는 컴포넌트입니다.

초기화 방법:

// Form_Load에서 호출
uBiDataManager1.Init();
// → IsOnLoadSelect="Y"인 DataAdapter가 자동으로 SELECT 프로시저 실행

개별 데이터 세트(DataSet)에 대한 CRUD 작업을 담당합니다.

Oracle 저장 프로시저는 패키지 형태로 관리됩니다.

명명규칙: PKG_{업무구분}${프로시저명}
예시: PKG_SYS$GET_CHILDS

표준 OUT 파라미터:

모든 프로시저는 다음 OUT 파라미터를 포함합니다:

• N_RETURN (INT) — 결과 코드 (0: 성공)
• V_RETURN (VARCHAR, 4000) — 결과 메시지

그리드 및 Lookup 컬럼의 속성을 정의합니다.

DevExpress의 LayoutControl을 확장한 컨트롤로, 화면의 전체 레이아웃을 관리합니다. Dock = Fill 모드로 폼 전체를 차지하며, 내부에 조회조건 영역과 데이터 그리드 등을 배치합니다.

BaseModule은 MDI 프레임(UBiMdiForm)의 공통 툴바 버튼과 연결되는 가상 메서드를 제공합니다. 개발자는 필요한 메서드만 override하여 구현합니다.

public override void OnSearchClick(UBiMdiForm f)
{
    base.OnSearchClick(f);
    try
    {
        UBiMessageBox.ShowWait("Loading...", "Loading...");
 
        // 방법 1: 컨트롤에서 직접 호출
        gridMain.DataAdapter.Select(true);
 
        // 방법 2: DataManager에서 이름으로 호출
        // uBiDataManager1.GetAdapter("TEST").Select(true);
    }
    catch (Exception ex)
    {
        ex.UBiShowException(this);
    }
    finally
    {
        UBiMessageBox.CloseWait();
    }
}

public override void OnSaveClick(UBiMdiForm f)
{
    base.OnSaveClick(f);
    try
    {
        UBiMessageBox.ShowWait("Wait", "Saving into Database...");
 
        // 저장 전 유효성 검사
        // ...
 
        ResponseDB res = gridMain.DataAdapter.Update();
        if (res.Code == 0)
        {
            UBiMessageBox.Show(res.Message, MessageBoxIcon.Information, true);
            OnSearchClick(f); // 재조회
        }
        else
        {
            UBiMessageBox.Show(res.Message, MessageBoxIcon.Error, true);
        }
    }
    catch (Exception ex)
    {
        ex.UBiShowException(this);
    }
    finally
    {
        UBiMessageBox.CloseWait();
    }
}

UBi 프레임워크의 그리드(UBiGridView)는 DevExpress GridView를 확장한 컨트롤입니다. 다양한 이벤트를 통해 셀 편집, 스타일링, 합계 계산 등을 처리할 수 있습니다.

특정 컬럼의 값이 변경되었을 때 처리합니다.

gridMain.CellValueChanged += (a, b) =>
{
    if (b.Column.FieldName.Equals("IS_CHK"))
    {
        // 체크박스 변경 시 처리 코드
    }
};

데이터 값에 따라 셀의 글자색, 배경색 등을 동적으로 변경합니다.

gridMain.RowCellStyle += (a, b) =>
{
    if (b.RowHandle >= 0)
    {
        UBiGridView view = a as UBiGridView;
 
        // 수량이 0보다 크면 파란색
        if (view.GetRowCellValue(b.RowHandle, "PLAN_QTY").Nvl("0").ToInt() > 0)
        {
            b.Appearance.ForeColor = Color.Blue;
        }
 
        // 특정 컬럼 값에 따라 빨간색
        if (b.Column.FieldName.Equals("ISBUY"))
        {
            if (b.CellValue.Nvl("N").Equals("Y"))
                b.Appearance.ForeColor = Color.Red;
        }
    }
};

특정 조건에서 셀 편집을 막아야 할 때 사용합니다.

gridMain.ShowingEditor += (a, b) =>
{
    if (gridMain.GetFocusedDataRow()["INPUT_LOCK"].Nvl("Y").Equals("Y"))
    {
        b.Cancel = true;
        UBiMessageBox.Show("투입 LOCK이 걸려 있습니다.",
            MessageBoxIcon.Information, false);
        SystemSounds.Beep.Play();
        return;
    }
};

특정 조건을 만족하는 행만 합계에 포함시킬 때 사용합니다.

decimal sumAMT = 0;
 
gridMain.CustomSummaryCalculate += (a, b) =>
{
    gridSub.UpdateCurrentRow();
 
    if (!b.IsTotalSummary
        || !((b.Item as GridSummaryItem).FieldName == "AMT"))
        return;
 
    if (b.SummaryProcess == DevExpress.Data.CustomSummaryProcess.Start)
    {
        sumAMT = 0;
    }
    if (b.SummaryProcess == DevExpress.Data.CustomSummaryProcess.Calculate)
    {
        if (b.Row is DataRowView r)
        {
            if (r.Row["END_CHK"].Nvl().Equals("Y"))
            {
                if ((b.Item as GridSummaryItem).FieldName == "AMT")
                    sumAMT += (decimal)b.FieldValue;
            }
        }
    }
    if (b.SummaryProcess == DevExpress.Data.CustomSummaryProcess.Finalize)
    {
        if ((b.Item as GridSummaryItem).FieldName == "AMT")
            b.TotalValue = sumAMT;
    }
};

화면이 호출될 때 부모 화면에서 전달하는 파라미터를 Param 속성으로 접근합니다.

private void Form_Load(object sender, EventArgs e)
{
    if (Param != null)
    {
        // 파라미터 접근
        string message = Param["message"].Nvl();
        UBiMessageBox.Show(message, MessageBoxIcon.Information, true);
    }
 
    uBiDataManager1.Init();
}

Visual Studio 디자이너에서 uBiDataManager1을 선택한 후 속성 창에서 설정합니다.

1. ServiceUrl → REST API 서버 주소 설정
2. ServiceName → DB 서비스명 설정 (환경에 맞게 변경)
3. AdapterList → 어댑터 추가/편집

각 DataAdapter에서 설정할 항목:

1. NAME → 어댑터 식별 이름
2. SELECT_PROCEDURE_ID → 조회 프로시저
3. INSERT_PROCEDURE_ID → 등록 프로시저
4. UPDATE_PROCEDURE_ID → 수정 프로시저
5. DELETE_PROCEDURE_ID → 삭제 프로시저
6. IsOnLoadSelect → “Y”이면 화면 로드 시 자동 조회
7. LookupLayOut → 컬럼 정의 (UBiColProperty 컬렉션)
8. SelectParam → 조회 파라미터 (UBiParam 컬렉션)

1. DataAdapter의 LookupLayOut 컬렉션 편집기를 엽니다
2. Add 버튼으로 UBiColProperty를 추가합니다
3. 각 속성을 설정합니다:

FIELD_NAME  : DB 컬럼명 (예: ORDER_NO)
TITLE       : 화면 표시명 (예: 주문번호)
TITLE_ID    : 다국어 ID (예: ORDER_NO)
DATA_TYPE   : System.String | System.Int64 | System.Decimal
COL_TYPE    : (기본 TEXT) 또는 NUMERIC
DATA_ALIGN  : Near(좌측) | Center(중앙) | Far(우측)
SIZE        : 컬럼 너비 (기본 80)
ORDER       : 표시 순서 (10, 20, 30...)

1. DataAdapter의 SelectParam 컬렉션 편집기를 엽니다
2. Add 버튼으로 UBiParam을 추가합니다

ARGUMENT_NAME  : 프로시저 파라미터명 (예: A_ORDER_DATE)
DATA_TYPE      : VARCHAR | INT
DATA_LENGTH    : 문자열 길이 (예: 200)
IN_OUT         : IN 또는 OUT
SORT_ORDER     : 파라미터 순서 (1, 2, 3...)
SOURCE_NAME    : 바인딩 소스 이름

프로젝트는 Class Library(DLL) 형태로 빌드됩니다.

빌드 완료 후 자동으로 afterbuild 스크립트가 실행됩니다.

$(SolutionDir)\afterbuild $(SolutionDir) $(ProjectDir) $(TargetFileName)

이 스크립트는 빌드된 DLL을 실행 환경의 dll 폴더로 복사합니다.

새 프로젝트 생성 시 다음 참조가 필요합니다:

• POPUP_COMMON — 공통 팝업 프로젝트
• UXHelper — UX 도우미 유틸리티
• UBi 프레임워크 DLL — UBi3FrameWork/FrameWorkReference/ 경로의 DLL 파일들
• DevExpress v20.1 — UI 컨트롤 라이브러리

모든 업무화면은 UX 네임스페이스를 사용합니다.

namespace UX
{
    public partial class UBi_FORM_ORD001 : BaseModule
    { }
}

• try-catch-finally 패턴 필수: 조회/저장 등 DB 작업 시 항상 사용
• UBiMessageBox.ShowWait / CloseWait 쌍: 장시간 작업 시 반드시 쌍으로 사용
• base 호출: override 메서드에서 반드시 base.메서드명(f) 먼저 호출
• 이벤트 등록: Form_Load에서 그리드 이벤트를 람다로 등록
• 주석: 한글 주석으로 비즈니스 로직 설명 기재

→ DataAdapter의 IsOnLoadSelect 속성이 “Y”로 설정되어 있는지 확인하세요. 또한 Form_Load에서 uBiDataManager1.Init()이 호출되고 있는지 확인하세요.

→ DB 프로시저의 N_RETURN OUT 파라미터 값을 확인하세요. 프로시저 내부에서 오류 발생 시 0이 아닌 값을 반환합니다. V_RETURN에 상세 오류 메시지가 포함됩니다.

→ DataAdapter의 LookupLayOut 컬렉션에 컬럼 정의가 추가되어 있는지 확인하세요. ORDER 값이 올바르게 설정되어야 합니다.

→ PostBuild 이벤트(afterbuild)가 정상 실행되었는지 확인하세요. 실행 환경의 dll 폴더에 최신 DLL이 복사되었는지 점검합니다.

→ uBiDataManager1의 ServiceUrl, ServiceName, ServiceUserId, ServicePassword 속성이 올바른지 확인하세요. 개발 환경에 맞게 설정을 변경해야 합니다.

• DevExpress v20.1 문서: DevExpress WinForms Documentation
• .NET Framework 4.7.2: Microsoft .NET Framework

이 문서는 UBi_FORM_SEC 템플릿 프로젝트를 기반으로 작성되었습니다.
최종 수정: 2026-03-21