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> 태그는 선택적으로 포함할 수 있습니다.
-
arrayBindingOracle 데이터베이스에 대해서
<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 파일을 쉽게 작성하고 자동 완성 기능을 사용할 수 있습니다.

