Foxml File¶
Foxml 파일은 Fox Query 에서 SQL 문장과 DB 매개변수 정보 등을 기록하는 XML 파일입니다. 이 문서는 Foxml 파일에 대한 상세한 내용을 설명합니다.
이 문서와 관련된 예제 코드는 다음 예제를 참조 하십시요.
기본 구조 ¶
Foxml 파일은 <queryMap>
태그를 루트로 가져야 하며 네임스페이스 스키마(xmlns
) 속성 값은 http://schema.neodeex.net/fx/foxml/2023/04/
이어야 합니다. <queryMap>
태그는 SQL 문장들을 포함하는 <statements>
태그와 여러 SQL 문장에서 공통으로 사용가능한 DB 매개변수들을 정의하는 <alias>
태그를 가질 수 있습니다.
<alias>
태그는 여러 쿼리들에서 공통적이고 반복적으로 사용가능한 DB 매개변수들을 정의할 수 있습니다. 하위에 여러 개의 <parameter>
태그를 통해 DB 매개변수 정보들을 설정하고 <statement>
태그나 <procedure>
태그에서 이들을 참조할 수 있습니다. <alias>
태그에서 정의된 공통 DB 매개변수를 참조하는 방법은 추후에 공통 매개변수 참조 에서 설명하겠습니다.
<statements>
태그는 하위에 SQL 문장을 나타내는 <statement>
태그나 저장 프로시서 호출을 나타내는 <procedure>
태그를 가질 수 있습니다. 이 두 태그는 하위에 공통적으로 <text>
태그, <parameters>
태그, <macros>
태그를 포함 할 수 있습니다. 이들 중 <text>
태그는 필수이며 <parameters>
및 <macros>
태그는 선택 사항입니다.
자동 완성 설정 ¶
.foxml
파일을 편집하기 위해서는 Visual Studio 를 사용하는 것이 편리합니다. Visual Studio 는 XML 스키마를 통해해 자동 완성 기능을 제공하기 때문에 이 문서에서 설명하는 XML 스키마에 대해 잘 알지 못하더라도 손쉽게 Fox Query 를 작성할 수 있기 때문입니다.
가장 편리한 방법은 Foxml 스키마 파일(FoxQuerySchema.xsd)을 다운로드 하여 Visual Studio 의 Schemas 폴더에 복사해 넣는 것입니다. Schemas 폴더는 Visual Studio 설치 폴더(%ProgreamFiles%/Microsoft Visual Studio\2022\Enterprise
)의 Xml
하위 폴더에서 찾을 수 있습니다. 이렇게 복사된 Foxml 스키마 파일은 xmlns
속성 값이 http://schema.neodeex.net/fx/foxml/2023/04/
인 경우 자동으로 로드되어 자동 완성 기능에 사용됩니다.
또 하나의 방법은 Foxml 스키마 파일(FoxQuerySchema.xsd
)을 Visual Studio 설치 폴더에 복사하지 않고 임의의 디렉터리에 존재하는 스키마 파일을 적용하는 방법입니다. 먼저 .foxml
파일을 열고 속성 창(properties window)에서 Schemas
속성을 선택합니다.
XML 스키마 편집 윈도우가 나타나면 Add
버튼을 클릭하여 임의의 위치에 존재하는 Foxml 스키마 파일을 선택합니다.
이제 XML 편집기는 스키마를 로드하여 자동 완성 기능을 사용할 수 있습니다.
statement
tag ¶
<statement>
태그는 SQL 문장을 기술할 때 사용하는 태그로서 FoxDbAccess
객체가 CommandType.Text
타입의 Command
객체를 생성하여 수행합니다. <statement>
태그는 <statements>
태그 내에서 반복적으로 사용할 수 있으며 반드시 id
속성을 가져야 합니다. id
속성 값은 .foxml
파일 내에서 유일해야 하며 중복을 허용하지 않습니다. <statement>
태그의 하위 태그로 <text>
태그를 반드시 포함해야 하지만 <parameters>
태그와 <macros>
태그는 선택적으로 포함할 수 있습니다.
-
arrayBinding
Oracle 데이터베이스에 대해서
<statement>
태그 및<procedure>
태그는arrayBinding
속성을 선택적으로 사용할 수 있습니다. 이 속성은 ODP.NET 프로바이더에서 제공하는 Array Binding 기능을 위한 속성 입니다.arrayBinding
속성 값이true
이면 DB 매개변수 값들은 모두 배열로 간주되며 배열을 통해 배열 바인딩을 수행합니다. 구체적인 사용방법은 Oracle Array Binding 문서를 참고 하십시요.
procedure
tag ¶
<procedure>
태그는 SQL 문장을 기술할 때 사용하는 태그로서 FoxDbAccess
객체가 CommandType.StoredProcedure
타입의 Command
객체를 생성하여 수행합니다. <procedure>
태그는 <statements>
태그 내에서 반복적으로 사용할 수 있으며 반드시 id
속성을 가져야 합니다. id
속성 값은 .foxml
파일 내에서 유일해야 하며 중복을 허용하지 않습니다. <procedure>
태그의 하위 태그로 <text>
태그를 반드시 포함해야 하지만 <parameters>
태그와 <macros>
태그는 선택적으로 포함할 수 있습니다.
text
tag ¶
<text>
태그는 SQL 문장 혹은 저장 프로시저의 이름을 표시합니다. <statement>
태그에 포함된 <text>
태그는 수행할 SQL 문장을 나타내며 <procedure>
태그에 포함된 <text>
태그는 수행할 저장 프로시저의 이름을 나타냅니다.
SQL 문장에서는 DB 매개변수를 나타낼 수 있습니다. <text>
태그의 문자열 내에 #
문자로 둘러싸인 문자열이 나타나면 이 문자열을 DB 매개변수로 간주합니다. 다음 예제는 SQL 문장에 3개의 DB 매개변수 p0
, p1
, p2
를 사용하고 있습니다.
<text>
태그 안에 사용된 DB 매개변수는 #
문자들이 제거되고 매개변수를 나타내는 접두 문자가 앞에 붙습니다. 매개변수 접두 문자는 데이터베이스에 따라 다릅니다. 이러한 변환 작업은 FoxDbAccess
객체에 의해 Command
객체를 생성할 때 수행됩니다. 데이터베이스 별 매개변수 접두 문자는 다음과 같습니다.
- SQL Server:
@
- Oracle:
:
- PostgreSQL:
:
- MySQL:
@
예를 들어 위 Foxml 을 PostgreSQL 에 적용하면 변환된 SQL 문장은 다음과 같습니다.
만약 위 Foxml 을 SQL Server 에 대해 수행한다면 변환된 SQL 문장은 다음과 같습니다.
<text>
태그 내에서 사용된 DB 매개변수는 <parameter>
태그를 통해 DB 매개변수 정보를 설정할 수 있습니다. 만약 사용된 DB 매개변수가 <parameter>
태그로 정의되지 않았다면 DB 매개변수를 자동으로 추가합니다. 위 예제에서 p1
매개변수는 <parameter>
태그에 의해 정의되지 않았습니다. 하지만 생성된 Command
객체의 Parameters
컬렉션에는 p1
DB 매개변수가 추가됩니다. 자동으로 추가된 DB 매개변수는 모든 설정이 디폴트 설정으로 추가됩니다(이 경우 p1
매개변수의 DbType
은 String
이 됩니다). 다음은 자동으로 추가된 DB 매개변수를 확인하는 예제 코드 입니다.
Tip
SQL 문장에는 <
문자나 >
문자와 같이 XML 에서 허용되지 않는 문자가 사용될 수 있습니다. 이들을 <
나 >
로 변환할 수도 있지만 SQL 문장의 가독성이 떨어지게 됩니다. 따라서 SQL 문장을 <![CDATA[
과 ]]>
로 감싸면 제약 문자들을 임의로 사용할 수 있습니다.
parameter
tag ¶
<parameter>
태그는 SQL 문장에서 사용된 DB 매개변수나 저장 프로시저를 호출할 때 필요한 DB 매개변수에 대한 정보를 설정하는데 사용됩니다. <parameter>
태그는 <parameters>
태그나 <alias>
태그의 하위 태그로 포함될 수 있습니다. <parameters>
태그에 포함된 <parameter>
태그는 해당 FoxQuery 에서만 사용되는 DB 매개변수에 대한 정의 입니다. <alias>
태그에 포함된 <parameter>
태그는 여러 FoxQuery 에서 참조가 가능합니다. 즉, 여러 FoxQuery 에서 사용되는 DB 매개변수 정보를 <alias>
태그에서 정의하고 각 FoxQuery 에서 이들 DB 매개변수 정보를 재사용하는 개념입니다. 구체적인 방법은 공통 매개변수 참조 에서 설명합니다.
<parameter>
태그는 다양한 속성(attribute)을 사용하여 DB 매개변수 정보를 설정할 수 있습니다. 다음 목록은 <parameter>
태그에서 사용가능한 속성들입니다.
-
name
(required)DB 매개변수의 이름입니다.
<statement>
태그의 경우 SQL 문장에서 사용된 DB 매개변수 이름을<parameters>
태그에서 찾을 때name
속성이 사용됩니다.<procedure>
태그의 경우 저장 프로시저의 매개변수 이름으로name
태그가 사용됩니다. 예를 들어 저장 프로시저가p_id
,p_name
매개변수를 갖는다면<parameters>
태그 내에서는name
속성이p_id
인<parameter>
태그와p_name
인<parameter>
태그 2개가 존재해야 합니다.Note
<procedure>
태그로 저장 프로시저를 호출할 때 저장 프로시저의 매개변수를<parameters>
태그에 자동으로 추가해 주는 기능은 지원하지 않습니다. -
property
(optional)매개변수 인자 객체(
Dictionary
,DataRow
혹은은Object
)에서 매개변수 값을 읽을 때 사용하는 키, 컬럼 이름 혹은 속성 이름입니다. 생략되면name
속성 값을 사용합니다.DB 매개변수 값은 매개변수 인자 객체로부터 읽어 들입니다. 예를 들어 다음과 같은 FoxQuery 정의가 있을 때,
매개변수 인자로
Dictionary
객체가 주어지면product_id
키를 사용하여 첫번째 DB 매개변수 값으로 사용하고category_id
키를 사용하여 두번째 DB 매개변수 값으로 사용합니다. 비슷하게DataRow
객체가 매개변수 인자로 사용되면product_id
컬럼과category_id
컬럼의 값을 사용하며 일반적인 닷넷 객체가 사용되면product_id
속성과category_id
속성이 사용됩니다.만약 DB 매개변수 이름과 인자의 이름이 동일하지 않다면
property
속성을 이용하여 인자 이름을 명시할 수 있습니다. 예를 들어 다음과 같은 FoxQuery 호출 코드가 존재하는 경우,제공된
Dictionary
인자의 키가 DB 매개변수 이름과 일치하지 않기 때문에property
속성을 다음과 같이 명시하면 됩니다.Information
property
속성은 저장 프로시저 매개변수와 같이 매개변수 앞에p_
와 같은 접두사를 사용하는 상황에서 유용하게 사용할 수 있습니다DataRow
객체나Object
객체를 매개변수 인자 값으로 이들 저장 프로시저를 호출하는 경우를 생각해 봅시다. DB 매개변수 이름을 동일하게 맞추려면 컬럼 이름 혹은 속성 이름에p_
접두사를 동일하게 사용해야 합니다. 하지만 컬럼 이름이나 속성 이름에 이러한 접두사를 사용하는 것은 권장되지 않습니다. 이 때property
속성을 사용하면 컬럼 이름 혹은 속성 이름에p_
접두사를 사용하지 않을 수 있습니다. -
dbType
(optional)DB 매개변수 타입입니다.
dbType
속성에 사용할 수 있는 값은String
,Decimal
과 같은DbType
열거 타입 혹은 개별 데이터 프로바이더의 DB 타입(SqlDbType
,OracleDbType
,NpgsqlDbType
,MySqlDbType
,OdbcDbType
) 입니다. 예를 들어.foxml
파일이 Oracle 에 대해 사용되면dbType
속성에는Varchar2
,Blob
,RefCursor
와 같은 값을 사용할 수 있습니다. Fox Query 는dbType
속성 값을 먼저 개별 데이터 프로바이더의 DB 타입으로 변환을 시도(Enum.TryParse
)하고 실패하면DbType
으로 변환을 시도합니다 (대소문자를 구별하지 않습니다).dbType
속성이 생략되면 매개변수 인자 값으로부터 유추된 값이 사용됩니다.Information
동일한
.foxml
파일이 어떤 데이터베이스에 사용되는가에 따라서dbType
속성 값이 오류를 일으킬 수도 있습니다. 따라서 하나의.foxml
파일을 다양한 데이터베이스에 사용하고자 한다면String
,Object
과 같은DbType
열거 타입의 값을 사용하는 것이 좋습니다. 각 데이터 프로바이더 별 DB 타입에 대응되는DbType
값은 개별 매뉴얼을 참고 하십시요. -
size
(optional)DB 매개변수의 전체 길이를 바이트 길이로 나타냅니다.
Varchar
와 같은 데이터 타입에는 의미가 있지만Int32
나Date
와 같은 타입에 대해서는 의미가 없습니다.생략되면 매개변수 인자 값으로부터 유추됩니다.
-
direction
(optional)DB 매개변수의 입출력 방향을 나타냅니다.
direction
속성에 사용할 수 있는 값은ParameterDirection
열거 타입의 값인Input
/Output
/InputOutput
/ReturnValue
중 하나이며 대소문자는 구분하지 않습니다.생략되면
Input
값이 사용됩니다. -
precision
/scale
(optional)실수 DB 매개변수 값에 대해 전체 자리 개수와 소수점 이하 자리 개수를 나타냅니다. 명시되지 않으면 0 으로 제한없음을 나타냅니다.
-
rowVersion
(optional)DB 매개변수 인자 값으로
DataRow
객체일 때에만 참조되며DataRow
에서 읽을 데이터 버전을 나타냅니다.DataRow
객체는 원본 값, 현재 값, 변경된 값 등을 유지할 수 있습니다. 이들 값들에 대한 버전을 나타내는DataRowVersion
열거 타입을 이 속성에 명시하면 해당 버전의 값을 DB 매개변수 값으로 사용합니다.DataRow
객체를 사용하여 데이터를 추가/수정/삭제할 때 사용되며 명시되지 않으면Default
값이 사용됩니다. -
optional
(optional)DB 매개변수의 optional 여부를 나타내는 불린값(
ture
/false
) 입니다. 저장 프로시저가 optional 매개변수를 가진 경우에만 사용하며 이 매개변수에 대한 인자 값을 생략할 수 있습니다. 명시되지 않으면false
입니다. -
associativeArray
/associativeArrayLength
(optional)Oracle 의 associative array 를 처리하기 위한 속성입니다.
Warning
현재 버전에서 아직 지원되지 않습니다.
-
ambient
(optional)매개변수 인자가 제공되지 않더라도 주변 값(ambient value)으로부터 매개변수 인자 값을 사용할지 여부입니다. 이 속성이
true
이면FoxDbAccess
객체는property
속성 값으로부터 읽어들일 주변 값을 결정합니다. 예를 들어 다음과 같은<parameter>
태그가 주어진다면,매개변수 인자 값은 현재 사용자의 ID 를 나타내는
FoxUserInfoContext.Current.UserId
속성 값이 사용됩니다. 현재 사용자 정보나 앱에서 설정되는 환경적인 값들을 매번 DB 매개변수 인자로 전달하지 않아되 되기 때문에 편리하게 사용가능합니다.주변 값 등록 및 사용에 대한 상세한 내용은 Ambient Value Manager을 참고 하십시요.
macro
tag ¶
<macro>
태그는 <macros>
태그의 하위에만 추가될 수 있습니다. <macro>
태그는 name
속성을 반드시 가져야 하며 name
속성의 값은 <macros>
태그 내에서 유일해야 합니다.
<macro>
태그는 <text>
태그에 사용된 매크로에 대한 매크로 스트립트를 정의합니다. <text>
태그에 사용된 매크로 이름은 $$
문자로 둘러쌓여야 하며 ()
문자를 사용하여 매크로 호출임을 나타내야 합니다. 예를 들어 $$MY_MACRO()$$
는 MY_MACRO
를 참조하며 <macros>
내에 name
속성 값이 MY_MACRO
인 <macro>
태그가 존재해야 합니다.
<macro>
태그 값은 매크로 스크립트 코드로서 C# 스크립트 코드입니다. C# 스크립트 코드는 env
전역 객체(global object)를 통해 <parameters>
태그에서 정의된 DB 매개변수 정보와 코드에서 제공된 매개변수 인자에 접근할 수 있습니다. C# 매크로 스크립트는 문자열을 반환하며 반환된 문자열은 <text>
태그에서 매크로 호출을 치환합니다. 다음은 매크로를 사용하는 FoxQuery 와 호출 코드의 예를 보여줍니다.
동적 쿼리에 사용되는 매크로 스크립트에 대한 상세한 내용은 동적 쿼리 문서를 참조 하십시요.
공통 매개변수 참조 ¶
.foxml
파일에는 다수의 FoxQuery 정의가 포함될 수 있습니다. 이 경우, 여러 <statement>
태그와 <procedure>
태그는 다수의 <parameter>
태그들을 포함할 수 있으며 이들 <parameter>
태그는 동일한 DB 매개변수 정보를 정의할 가능성이 높습니다. 예를 들어, 어떤 마스터 테이블의 주요 컬럼에 대한 DB 매개변수라면 이 매개변수에 대한 <parameter>
태그들은 모두 동일한 이름, DB 타입, 크기 등을 사용할 것입니다. 만약 개발 도중 어떠한 이유로 이 컬럼의 스키마가 변경된다면 모든 Fox Query 에서 DB 매개변수들을 찾아 수정해 주어야 할 것입니다. Foxml 은 이러한 상황을 제어할 수 있도록 공통 DB 매개변수 정보를 한번만 정의하고 여러 FoxQuery 내에서 이들을 참조할 수 있는 방법을 제공합니다.
Foxml 기본 구조에서 살펴본 대로 루트 태그인 <queryMap>
태그는 <alias>
태그를 포함할 수 있습니다. <alias>
태그에서 .foxml
파일 내에서 사용 가능한 공통 DB 매개변수 정보를 설정하고 <statement>
태그와 <procedure>
태그에서 이미 정의된 공통 DB 매개변수를 참조할 수 있습니다. <alias>
태그 내에는 <parameter>
태그들을 포함할 수 있으며 DB 매개변수 정보를 동일하게 설정할 수 있습니다. 그리고 다른 곳에서 이 DB 매개변수를 참조할 수 있도록 id
속성을 사용해야 합니다. id
속성의 값은 <alias>
태그 내에서 유일한 값이어야 합니다.
Warning
<alias>
태그 내에 존재하는 <parameter>
태그는 반드시 id
속성을 가져야 하며 이 속성이 없는 경우 FoxInvalidFoxQuery
예외를 유발합니다. 그리고 <statement>
태그나 <procedure>
태그 내에 존재하는 <parameter>
태그는 id
속성을 가질 수 없습니다.
다음은 <alias>
태그를 사용하여 공통 매개변수를 정의하는 예를 보여줍니다.
위 .foxml
은 2개의 공통 DB 매개변수를 정의하며 각각의 아이디는 pid
와 cid
입니다. 이들 공통 매개변수는 이 이후에서 참조하여 재사용이 가능합니다. 예를 들어 다음과 같은 <parameter>
태그들은 ref
속성에서 공통 매개변수의 아이디를 사용하여 DB 매개변수 정보를 참조합니다.
Warning
ref
속성이 사용된 <parameter>
태그는 ref
속성 이외의 속성은 사용할 수 없습니다.
Summary¶
Foxml 파일은 Fox Query에서 SQL 문장과 DB 매개변수 정보를 기록하는 XML 파일입니다. Foxml 파일의 기본 구조는 <queryMap>
태그가 루트로 사용되며, SQL 문장 혹은 저장 프로시저 호출은 <statements>
태그에 정의합니다. 공통 DB 매개변수는 <alias>
태그에 정의되며 각 FoxQuery 의 <parameter>
태그의 ref
속성을 사용하여 참조가 가능합니다. Foxml 파일에서 사용되는 주요 XML 태그는 다음과 같습니다.
-
<statement>
: SQL 문장을 기술하며 반드시id
속성을 가져야 합니다. -
<procedure>
: 저장 프로시저를 호출할 때 사용하며 역시id
속성을 가져야 합니다. -
<text>
: SQL 문장 또는 저장 프로시저 이름을 표시 합니다. -
<parameter>
: SQL 문장에서 사용되는 DB 매개변수를 설정 합니다. -
<macro>
: 동적 SQL 문장을 생성하기 위한 매크로 스크립트를 정의합니다.
Foxml 파일을 편집할 때의 팁으로 Visual Studio의 XML 스키마를 통해 Foxml 파일을 쉽게 작성하고 자동 완성 기능을 사용할 수 있습니다.