SQL Server Native Client에서 사용자 정의 형식 사용
적용 대상: 
SQL Server Azure SQL Database 
Azure Synapse Analytics PDW(Analytics Platform System)
Important
SNAC(SQL Server Native Client)는 다음과 함께 제공되지 않습니다.
- SQL Server 2022(16.x) 이상 버전
- SQL Server Management Studio 19 이상 버전
SQL Server Native Client(SQLNCLI 또는 SQLNCLI11)와 레거시 Microsoft OLE DB Provider for SQL Server(SQLOLEDB)는 새로운 응용 프로그램 개발에 권장되지 않습니다.
새 프로젝트의 경우 다음 드라이버 중 하나를 사용합니다.
SQL Server 데이터베이스 엔진(버전 2012부터 2019까지)의 구성 요소로 제공되는 SQLNCLI의 경우 이 수명 주기 예외 지원을 참조하세요.
SQL Server 2005(9.x)에는 UDT(사용자 정의 형식)가 도입되었습니다. UDT는 SQL Server 데이터베이스에 개체 및 사용자 지정 데이터 구조를 저장할 수 있도록 하여 SQL 형식 시스템을 확장합니다. UDT는 단일 SQL Server 시스템 데이터 형식으로 구성된 일반적인 별칭 데이터 형식과 달리 여러 데이터 형식을 포함할 수 있으며 관련 동작이 있을 수 있습니다. UDT는 확인 가능한 코드를 생성하는 .NET CLR(공용 언어 런타임)에서 지원하는 언어를 사용하여 정의됩니다. 여기에는 C# 및 Visual Basic .NET이 포함됩니다. 데이터는 .NET 클래스 또는 구조체의 필드 및 속성으로 노출되며 동작은 클래스 또는 구조체의 메서드에 의해 정의됩니다.
UDT를 테이블의 열 정의, Transact-SQL 일괄 처리의 변수 또는 Transact-SQL 함수나 저장 프로시저의 인수로 사용할 수 있습니다.
SQL Server Native Client OLE DB 공급자
SQL Server Native Client OLE DB 공급자는 메타데이터 정보를 사용하여 UDT를 이진 형식으로 지원하므로 UDT를 개체로 관리할 수 있습니다. UDT 열은 DBTYPE_UDT 노출되고 해당 메타데이터는 핵심 OLE DB 인터페이스 IColumnRowset 및 새 ISSCommandWithParameters 인터페이스를 통해 노출됩니다 .
참고 항목
IRowsetFind::FindNextRow 메서드는 UDT 데이터 형식과 함께 사용할 수 없습니다. UDT가 검색 열 유형으로 사용되는 경우 DB_E_BADCOMPAREOP가 반환됩니다.
데이터 바인딩 및 강제 변환
다음 표에서는 SQL Server UDT와 함께 나열된 데이터 형식을 사용할 때 발생하는 바인딩 및 강제 변환에 대해 설명합니다. UDT 열은 SQL Server Native Client OLE DB 공급자를 통해 DBTYPE_UDT 노출됩니다. 사용자 고유의 정의된 형식을 개체로 관리할 수 있도록 적절한 스키마 행 집합을 통해 메타데이터를 가져올 수 있습니다.
| 데이터 형식 | To Server UDT |
To Server 비 UDT |
서버에서 UDT |
서버에서 비 UDT |
|---|---|---|---|---|
| DBTYPE_UDT | 지원됨6 | 오류1 | 지원됨6 | 오류5 |
| DBTYPE_BYTES | 지원됨6 | 해당 없음2 | 지원됨6 | 해당 없음2 |
| DBTYPE_WSTR | 지원됨3,6 | 해당 없음2 | 지원되는4,6 | 해당 없음2 |
| DBTYPE_BSTR | 지원됨3,6 | 해당 없음2 | 지원되는4 | 해당 없음2 |
| DBTYPE_STR | 지원됨3,6 | 해당 없음2 | 지원되는4,6 | 해당 없음2 |
| DBTYPE_IUNKNOWN | 지원되지 않음 | 해당 없음2 | 지원되지 않음 | 해당 없음2 |
| DBTYPE_VARIANT(VT_UI1 | VT_ARRAY) | 지원됨6 | 해당 없음2 | 지원되는4 | 해당 없음2 |
| DBTYPE_VARIANT (VT_BSTR) | 지원됨3,6 | 해당 없음2 | 해당 없음 | 해당 없음2 |
1DBTYPE_UDT 이외의 서버 형식이 ICommandWithParameters::SetParameterInfo로 지정되고 접근자 형식이 DBTYPE_UDT 경우 문이 실행될 때 오류가 발생합니다(DB_E_ERRORSOCCURRED; 매개 변수 상태는 DBSTATUS_E_BADACCESSOR). 그렇지 않으면 데이터가 서버로 전송되지만 서버는 UDT에서 매개 변수의 데이터 형식으로의 암시적 변환이 없음을 나타내는 오류를 반환합니다.
2이 항목의 범위를 벗어나봅니다.
3 16진수 문자열에서 이진 데이터로의 데이터 변환이 발생합니다.
4 이진 데이터에서 16진수 문자열로의 데이터 변환이 발생합니다.
5유효성 검사는 만들기 접근자 시간 또는 페치 시 오류가 DB_E_ERRORSOCCURRED 바인딩 상태가 DBBINDSTATUS_UNSUPPORTEDCONVERSION 설정할 때 발생할 수 있습니다.
6BY_REF 사용할 수 있습니다.
DBTYPE_NULL 및 DBTYPE_EMPTY 입력 매개 변수에 바인딩할 수 있지만 출력 매개 변수 또는 결과에는 바인딩할 수 없습니다. 입력 매개 변수에 대해 바인딩할 경우 상태를 DBSTATUS_S_ISNULL 또는 DBSTATUS_S_DEFAULT로 설정해야 합니다.
DBTYPE_UDT DBTYPE_EMPTY 및 DBTYPE_NULL 변환할 수도 있지만 DBTYPE_NULL 및 DBTYPE_EMPTY DBTYPE_UDT 변환할 수 없습니다. 이는 DBTYPE_BYTES 일치합니다.
참고 항목
새 인터페이스는 ICommandWithParameters에서 상속되는 매개 변수인 ISSCommandWithParameters로 UDT를 처리하는 데 사용됩니다. 애플리케이션은 이 인터페이스를 사용하여 UDT 매개 변수에 대해 설정된 DBPROPSET_SQLSERVERPARAMETER 속성의 SSPROP_PARAM_UDT_NAME 이상 설정해야 합니다. 이 작업이 수행 되지 않으면 ICommand::Execute 가 DB_E_ERRORSOCCURRED 반환합니다. 이 인터페이스 및 속성 집합은 이 항목의 뒷부분에 설명되어 있습니다.
사용자 정의 형식이 모든 데이터를 저장할 만큼 크지 않은 열에 삽입되는 경우 ICommand::Execute 는 DB_E_ERRORSOCCURRED 상태의 S_OK 반환합니다.
OLE DB 핵심 서비스(IDataConvert)에서 제공하는 데이터 변환은 DBTYPE_UDT 적용되지 않습니다. 다른 바인딩은 지원되지 않습니다.
OLE DB 행 집합 추가 및 변경 내용
SQL Server Native Client는 많은 핵심 OLE DB 스키마 행 집합에 새 값 또는 변경 내용을 추가합니다.
PROCEDURE_PARAMETERS 스키마 행 집합
PROCEDURE_PARAMETERS 스키마 행 집합에 다음이 추가되었습니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. |
| SS_UDT_NAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | CLR에서 참조하는 데 필요한 형식 이름 및 모든 어셈블리 ID를 포함하는 어셈블리 정규화된 이름입니다. |
SQL_ASSEMBLIES 스키마 행 집합
SQL Server Native Client OLE DB 공급자는 등록된 UDT를 설명하는 새 공급자 특정 스키마 행 집합을 노출합니다. ASSEMBLY 서버가 DBTYPE_WSTR로 지정되지만 행 집합에는 없을 수 있습니다. 이 속성이 지정되지 않은 경우 행 집합은 기본적으로 현재 서버를 사용합니다. SQL_ASSEMBLIES 스키마 행 집합은 다음 표에 정의되어 있습니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | 형식을 포함하는 어셈블리의 카탈로그 이름입니다. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | 형식을 포함하는 어셈블리의 스키마 이름 또는 소유자 이름입니다. 어셈블리는 스키마가 아닌 데이터베이스로 범위가 지정되지만 여기에 반영된 소유자가 있습니다. |
| ASSEMBLY_NAME | DBTYPE_WSTR | 형식을 포함하는 어셈블리의 이름입니다. |
| ASSEMBLY_ID | DBTYPE_UI4 | 형식을 포함하는 어셈블리의 개체 ID입니다. |
| PERMISSION_SET | DBTYPE_WSTR | 어셈블리에 대한 액세스 범위를 나타내는 값입니다. 값에는 "SAFE", "EXTERNAL_ACCESS" 및 "UNSAFE"가 포함됩니다. |
| ASSEMBLY_BINARY | DBTYPE_BYTES | 어셈블리의 이진 표현입니다. |
SQL_ASSEMBLIES_ 종속성 스키마 행 집합
SQL Server Native Client OLE DB 공급자는 지정된 서버에 대한 어셈블리 종속성을 설명하는 새 공급자별 스키마 행 집합을 노출합니다. ASSEMBLY_SERVER 호출자가 DBTYPE_WSTR 지정할 수 있지만 행 집합에는 없습니다. 이 속성이 지정되지 않은 경우 행 집합은 기본적으로 현재 서버를 사용합니다. SQL_ASSEMBLY_DEPENDENCIES 스키마 행 집합은 다음 표에 정의되어 있습니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | 형식을 포함하는 어셈블리의 카탈로그 이름입니다. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | 형식을 포함하는 어셈블리의 스키마 이름 또는 소유자 이름입니다. 어셈블리는 스키마가 아닌 데이터베이스로 범위가 지정되지만 여기에 반영된 소유자가 있습니다. |
| ASSEMBLY_ID | DBTYPE_UI4 | 어셈블리의 개체 ID입니다. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | 참조된 어셈블리의 개체 ID입니다. |
SQL_USER_TYPES 스키마 행 집합
SQL Server Native Client OLE DB 공급자는 지정된 서버에 등록된 UDT가 추가되는 시기를 설명하는 새 스키마 행 집합인 SQL_USER_TYPES 노출합니다. UDT_SERVER 호출자가 DBTYPE_WSTR 지정해야 하지만 행 집합에는 없습니다. SQL_USER_TYPES 스키마 행 집합은 다음 표에 정의되어 있습니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | UDT 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다. |
| UDT_SCHEMANAME | DBTYPE_WSTR | UDT 열의 경우 이 속성이 UDT가 정의되어 있는 스키마의 이름을 지정하는 문자열입니다. |
| UDT_NAME | DBTYPE_WSTR | UDT 클래스를 포함하는 어셈블리의 이름입니다. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | AQN(전체 형식 이름)에는 해당하는 경우 네임스페이스로 접두사로 지정된 형식 이름이 포함됩니다. |
COLUMNS 스키마 행 집합
COLUMNS 스키마 행 집합에 추가된 열에는 다음 열이 포함됩니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | UDT 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | UDT 열의 경우 이 속성이 UDT가 정의되어 있는 스키마의 이름을 지정하는 문자열입니다. |
| SS_UDT_NAME | DBTYPE_WSTR | UDT의 이름 |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | AQN(전체 형식 이름)에는 해당하는 경우 네임스페이스로 접두사로 지정된 형식 이름이 포함됩니다. |
OLE DB 속성 집합 추가 및 변경 내용
SQL Server Native Client는 많은 핵심 OLE DB 속성 집합에 새 값 또는 변경 내용을 추가합니다.
DBPROPSET_SQLSERVERPARAMETER 속성 집합
OLE DB를 통해 UDT를 지원하기 위해 SQL Server Native Client는 다음 값을 포함하는 새 DBPROPSET_SQLSERVERPARAMETER 속성 집합을 구현합니다.
| 속성 | 형식 | 설명 |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. UDT 매개 변수의 경우 이 속성은 사용자 정의 형식이 정의된 카탈로그의 이름을 지정하는 문자열입니다. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. UDT 매개 변수의 경우 이 속성은 사용자 정의 형식이 정의된 스키마의 이름을 지정하는 문자열입니다. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | 세 부분으로 구성된 이름 식별자입니다. UDT 열의 경우 이 속성이 사용자 정의 형식의 단일 부분으로 구성된 이름을 지정하는 문자열입니다. |
SSPROP_PARAM_UDT_NAME은 필수입니다. SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 선택 사항입니다. 이러한 속성 중 하나가 잘못 지정되면 DB_E_ERRORSINCOMMAND가 반환됩니다. SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 모두 지정되지 않은 경우 테이블과 동일한 데이터베이스 및 스키마에 UDT를 정의해야 합니다. UDT 정의가 테이블과 동일한 스키마에 있지 않지만 동일한 데이터베이스에 있는 경우 SSPROP_PARAM_UDT_SCHEMANAME 지정해야 합니다. UDT 정의가 다른 데이터베이스에 있는 경우 SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 모두 지정해야 합니다.
DBPROPSET_SQLSERVERCOLUMN 속성 집합
ITableDefinition 인터페이스에서 테이블 만들기를 지원하기 위해 SQL Server Native Client는 DBPROPSET_SQLSERVERCOLUMN 속성 집합에 다음 세 개의 새 열을 추가합니다.
| 속성 | Description | Type | 설명 |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | DBTYPE_UDT 형식 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | DBTYPE_UDT 형식 열의 경우 이 속성은 UDT가 정의된 스키마의 이름을 지정하는 문자열입니다. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | DBTYPE_UDT 형식 열의 경우 이 속성은 UDT의 단일 부분 이름을 지정하는 문자열입니다. 다른 열 형식의 경우 이 속성은 빈 문자열을 반환합니다. |
참고 항목
UDT는 PROVIDER_TYPES 스키마 행 집합에 표시되지 않습니다. 모든 열에는 읽기 및 쓰기 권한이 있습니다.
ADO는 설명 열의 해당 항목을 사용하여 이러한 속성을 참조합니다.
SSPROP_COL_UDTNAME 필수입니다. SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME 선택 사항입니다. 속성이 잘못 지정된 경우 DB_E_ERRORSINCOMMAND 반환됩니다.
SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME이 모두 지정되지 않은 경우 테이블과 동일한 데이터베이스와 스키마에서 UDT를 정의해야 합니다.
UDT 정의가 테이블과 동일한 스키마에 있지 않지만 동일한 데이터베이스에 있는 경우 SSPROP_COL_UDT_SCHEMANAME 지정해야 합니다.
UDT 정의가 다른 데이터베이스에 있는 경우 SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME 모두 지정해야 합니다.
OLE DB 인터페이스 추가 및 변경 내용
SQL Server Native Client는 많은 핵심 OLE DB 인터페이스에 새 값 또는 변경 내용을 추가합니다.
ISSCommandWithParameters 인터페이스
OLE DB를 통해 UDT를 지원하기 위해 SQL Server Native Client는 ISSCommandWithParameters 인터페이스 추가 를 포함하여 다양한 변경 내용을 구현합니다 . 이 새 인터페이스는 핵심 OLE DB 인터페이스인 ICommandWithParameters에서 상속됩니다. ICommandWithParameters에서 상속된 세 가지 메서드 외에; GetParameterInfo, MapParameterNames 및 SetParameterInfo; ISSCommandWithParameters는 서버 특정 데이터 형식을 처리하는 데 사용되는 GetParameterProperties 및 SetParameterProperties 메서드를 제공합니다.
참고 항목
또한 ISSCommandWithParameters 인터페이스는 새 SSPARAMPROPS 구조를 사용합니다.
IColumnsRowset 인터페이스
ISSCommandWithParameters 인터페이스 외에도 SQL Server Native Client는 다음을 포함하여 IColumnsRowset::GetColumnRowset 메서드를 호출하여 반환된 행 집합에 새 값을 추가합니다.
| 열 이름 | Type | 설명 |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | UDT 카탈로그 이름 식별자입니다. |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | UDT 스키마 이름 식별자입니다. |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | UDT 이름 식별자입니다. |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | 형식 이름 및 CLR에서 참조하는 데 필요한 모든 어셈블리 ID를 포함하는 어셈블리 정규화된 이름입니다. |
DBCOLUMN_TYPE이 DBTYPE_UDT로 설정되어 있는 경우 위에 지정된 추가적인 UDT 메타데이터를 찾아 서버의 UDT 열을 다른 이진 형식과 구분할 수 있습니다. 해당 데이터가 부분적으로 완료된 경우 서버 유형은 UDT입니다. UDT가 아닌 서버 형식의 경우 이러한 열은 항상 NULL로 반환됩니다.
SQL Server Native Client ODBC 드라이버
UDT를 지원하기 위해 SQL Server Native Client ODBC 드라이버에서 여러 가지 변경 사항이 적용되었습니다. SQL Server Native Client ODBC 드라이버는 SQL Server UDT를 드라이버별 SQL 데이터 형식 식별자를 SQL_SS_UDT 매핑합니다. UDT 열은 SQL_SS_UDT로 표시됩니다. UDT의 ToString 또는 ToXMLString 메서드를 사용하거나 CAST/CONVERT 함수를 통해 SQL 문의 다른 형식에 UDT 열을 명시적으로 매핑하는 경우 결과 집합의 열 형식은 열이 변환된 실제 형식을 반영합니다.
SQLColAttribute, SQLDescribeParam, SQLGetDescField
SQLColAttribute, SQLDescribeParam 및 SQLGetDescField 함수를 통해 검색할 결과 집합의 UDT 열 또는 저장 프로시저/매개 변수가 있는 쿼리의 UDT 매개 변수에 대한 추가 정보를 제공하기 위해 4개의 새로운 드라이버 관련 설명자 필드가 추가되었습니다.
추가된 4개의 새 설명자 필드는 SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME 및 SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.
SQLColumns, SQLProcedureColumns
또한 UDT 결과 집합 열 또는 UDT 매개 변수에 대한 추가 정보를 제공하기 위해 SQLColumns 및 SQLProcedureColumns 함수에서 반환된 결과 집합에 세 개의 새 드라이버 특정 열이 추가됩니다. 이 새로운 세 개의 열은 SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME 및 SS_UDT_ASSEMBLY_TYPE_NAME입니다.
지원되는 변환
SQL에서 C 데이터 형식으로 변환할 때 SQL_C_WCHAR, SQL_C_BINARY 및 SQL_C_CHAR 모두 SQL_SS_UDT 변환할 수 있습니다. 그러나 이진 데이터는 SQL_C_WCHAR 변환하고 SQL 데이터 형식을 SQL_C_CHAR 때 16진수 문자열로 변환됩니다.
C에서 SQL 데이터 형식으로 변환할 때 SQL_C_WCHAR, SQL_C_BINARY 및 SQL_C_CHAR 모두 SQL_SS_UDT 변환할 수 있습니다. 그러나 이진 데이터는 SQL_C_WCHAR 변환하고 SQL 데이터 형식을 SQL_C_CHAR 때 16진수 문자열로 변환됩니다.
참고 항목
SQL Server Native Client 기능
ISSCommandWithParameters(OLE DB)