Использование определяемых пользователем типов в собственном клиенте SQL Server
Применимо:
SQL Server База данных SQL Azure
Azure Synapse Analytics Analytics Platform System (PDW)
Внимание
SQL Server Native Client (SNAC) не поставляется с:
- SQL Server 2022 (16.x) и более поздних версий
- SQL Server Management Studio 19 и более поздних версий
Собственный клиент SQL Server (SQLNCLI или SQLNCLI11) и устаревший поставщик Microsoft OLE DB для SQL Server (SQLOLEDB) не рекомендуется для разработки новых приложений.
Для новых проектов используйте один из следующих драйверов:
Сведения о SQLNCLI, которые поставляется в качестве компонента SQL Server ядро СУБД (версии 2012–2019), см. в этом исключении жизненного цикла поддержки.
SQL Server 2005 (9.x) представил определяемые пользователем типы (определяемые пользователем типы). Определяемые пользователем объекты расширяют систему типов SQL, позволяя хранить объекты и пользовательские структуры данных в базе данных SQL Server. Определяемые пользователем типы данных могут содержать несколько типов данных и могут иметь поведение, отличая их от традиционных типов данных псевдонимов, состоящих из одного типа системных данных SQL Server. Определяемые пользователем типы определяются с помощью любого языка, поддерживаемого средой .NET CLR, который создает поддающийся проверке код. К ним относятся C# и Visual Basic .NET. Данные представляются в виде полей и свойств класса или структуры .NET, а поведения определяются методами класса или структуры.
Пользовательские типы (UDT) можно применять в качестве идентификатора столбцов таблицы, как переменную в пакете Transact-SQL или как аргумент функции Transact-SQL либо хранимой процедуры.
Поставщик OLE DB для собственного клиента SQL Server
Поставщик OLE DB собственного клиента SQL Server поддерживает определяемые пользователем типы в виде двоичных типов с сведениями о метаданных, что позволяет управлять определяемыми пользователями в качестве объектов. Столбцы пользовательских типов представляются как DBTYPE_UDT, и их метаданные доступны через основной интерфейс OLE DB IColumnRowset и новый интерфейс ISSCommandWithParameters.
Примечание.
Метод IRowsetFind::FindNextRow не работает с пользовательским типом данных. Если определяемый пользователем тип используется в качестве типа столбца поиска, возвращается значение DB_E_BADCOMPAREOP.
Привязки данных и приведение типов
В следующей таблице описывается привязка и приведение, которое возникает при использовании перечисленных типов данных с определяемой пользователем SQL Server. Столбцы UDT предоставляются поставщиком OLE DB собственного клиента SQL Server как DBTYPE_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 |
1Если тип сервера, отличный от DBTYPE_UDT, указывается с помощью метода ICommandWithParameters::SetParameterInfo и типом метода доступа является DBTYPE_UDT, то при выполнении инструкции возникает ошибка (DB_E_ERRORSOCCURRED; состояние параметра — DBSTATUS_E_BADACCESSOR). В остальных случаях данные отсылаются на сервер, но сервер возвращает ошибку, указывающую на то, что нет неявного преобразования определяемого пользовательского типа в тип данных параметра.
2За пределами этой статьи.
3 Происходит преобразование шестнадцатеричной строки в двоичные данные.
4 Происходит преобразование двоичных данных в шестнадцатеричную строку.
5Во время создания метода доступа или во время выборки может произойти проверка данных. Ошибка — DB_E_ERRORSOCCURRED, состояние привязки устанавливается в значение DBBINDSTATUS_UNSUPPORTEDCONVERSION.
6Может использоваться BY_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.
Примечание.
Новый интерфейс ISSCommandWithParameters, наследуемый от интерфейса ICommandWithParameters, используется для работы с пользовательскими типами как с параметрами. Приложения должны использовать этот интерфейс для установки, по крайней мере, атрибута SSPROP_PARAM_UDT_NAME набора свойств DBPROPSET_SQLSERVERPARAMETER для параметров определяемых пользователем типов. Если это не сделано, метод ICommand::Execute возвратит ошибку DB_E_ERRORSOCCURRED. Этот интерфейс и набор свойств описан далее в этом разделе.
Если определяемый пользователем тип вставлен в столбец, который недостаточно велик для хранения всех его данных, метод ICommand::Execute вернет S_OK с состоянием DB_E_ERRORSOCCURRED.
Преобразования данных, выполняемые основными службами OLE DB (IDataConvert), неприменимы к типу DBTYPE_UDT. Другие привязки не поддерживаются.
Добавления и изменения для наборов строк OLE DB
Sql Server Native Client добавляет новые значения или изменения во многих основных наборах строк схемы OLE DB.
Набор строк схемы PROCEDURE_PARAMETERS
В набор строк схемы PROCEDURE_PARAMETERS были сделаны следующие добавления.
| Имя столбца | Тип | Описание |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. |
| SS_UDT_NAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Полное имя сборки, которое включает имя типа и все идентификационные данные сборки, необходимые для ссылки на сборку из среды CLR. |
Набор строк схемы SQL_ASSEMBLIES
Поставщик OLE DB собственного клиента SQL Server предоставляет новый набор строк схемы поставщика, описывающий зарегистрированные определяемые пользователем группы пользователей. Сервер ASSEMBLY может быть указан как тип DBTYPE_WSTR, но он отсутствует в наборе строк. Если значение не задано, то по умолчанию для набора строк будет использоваться текущий сервер. Набор строк схемы SQL_ASSEMBLIES определен в следующей таблице.
| Имя столбца | Тип | Описание |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Имя каталога сборки, содержащей тип. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Имя схемы или имя владельца сборки, содержащей тип. Хотя сборки ограничены базой данных, а не схемой, они все еще имеют владельца, отраженного здесь. |
| ASSEMBLY_NAME | DBTYPE_WSTR | Имя сборки, содержащей тип. |
| ASSEMBLY_ID | DBTYPE_UI4 | Идентификатор объекта сборки, содержащей тип. |
| PERMISSION_SET | DBTYPE_WSTR | Значение, определяющее область доступа сборки. Значения включают «SAFE», «EXTERNAL_ACCESS» и «UNSAFE». |
| ASSEMBLY_BINARY | DBTYPE_BYTES | Двоичное представление сборки. |
Набор строк схемы SQL_ASSEMBLIES_ DEPENDENCIES
Поставщик OLE DB собственного клиента SQL Server предоставляет новый набор строк схемы для конкретного поставщика, описывающий зависимости сборки для указанного сервера. ASSEMBLY_SERVER может быть указан участником как тип DBTYPE_WSTR, но отсутствовать в наборе строк. Если значение не задано, то по умолчанию для набора строк будет использоваться текущий сервер. Набор строк схемы SQL_ASSEMBLY_DEPENDENCIES определен в следующей таблице.
| Имя столбца | Тип | Описание |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Имя каталога сборки, содержащей тип. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Имя схемы или имя владельца сборки, содержащей тип. Хотя сборки ограничены базой данных, а не схемой, они все еще имеют владельца, отраженного здесь. |
| ASSEMBLY_ID | DBTYPE_UI4 | Идентификатор объекта сборки. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | Идентификатор объекта сборки, на которую присутствует ссылка. |
Набор строк схемы SQL_USER_TYPES
Поставщик OLE DB собственного клиента SQL Server предоставляет новый набор строк схемы, SQL_USER_TYPES, описывающий при добавлении зарегистрированных определяемых пользователем пользователей для указанного сервера. UDT_SERVER должен быть указан участником как тип DBTYPE_WSTR, но отсутствовать в наборе строк. Набор строк схемы SQL_USER_TYPES определен в следующей таблице.
| Имя столбца | Тип | Описание |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | Для столбцов определяемого пользователем типа данное свойство содержит строку, представляющую имя каталога, в котором определен этот тип. |
| UDT_SCHEMANAME | DBTYPE_WSTR | Для столбцов определяемого пользователем типа данное свойство содержит строку, представляющую имя схемы, в которой определен этот тип. |
| UDT_NAME | DBTYPE_WSTR | Имя сборки, содержащей класс определяемого пользователем типа. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Полное имя типа (AQN) включает имя типа и префикс пространства имен (если оно задано). |
Набор строк схемы COLUMNS
Добавления в наборе строк схемы COLUMNS включает следующие столбцы.
| Имя столбца | Тип | Описание |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Для столбцов определяемого пользователем типа данное свойство содержит строку, представляющую имя каталога, в котором определен этот тип. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Для столбцов определяемого пользователем типа данное свойство содержит строку, представляющую имя схемы, в которой определен этот тип. |
| SS_UDT_NAME | DBTYPE_WSTR | Имя определяемого пользователем типа. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Полное имя типа (AQN) включает имя типа и префикс пространства имен (если оно задано). |
Добавления и изменения для наборов свойств OLE DB
SQL Server Native Client добавляет новые значения или изменения во многих основных наборах свойств OLE DB.
Набор свойств DBPROPSET_SQLSERVERPARAMETER
Для поддержки определяемых пользователем пользователей с помощью OLE DB sql Server Native Client реализует новый набор свойств DBPROPSET_SQLSERVERPARAMETER, содержащий следующие значения.
| Имя. | Тип | Описание |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. Для параметров определяемого пользователем типа это свойство содержит строку, представляющую имя каталога, в котором определен этот тип. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. Для параметров определяемого пользователем типа данное свойство содержит строку, представляющую имя схемы, в которой определен этот тип. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | Идентификатор трехкомпонентного имени. Для столбцов определяемого пользователем типа это свойство содержит строку, представляющую однокомпонентное имя определяемого пользователем типа. |
Свойство SSPROP_PARAM_UDT_NAME является обязательным. Свойства SSPROP_PARAM_UDT_CATALOGNAME и SSPROP_PARAM_UDT_SCHEMANAME не обязательны. Если какое-либо свойство указывается неправильно, возвращается ошибка DB_E_ERRORSINCOMMAND. Если свойства SSPROP_PARAM_UDT_CATALOGNAME и SSPROP_PARAM_UDT_SCHEMANAME не указаны, то определяемый пользователем тип должен быть определен в той же базе данных и схеме, что и таблица. Если определение определяемого пользователем типа и таблица находятся в разных схемах (но в одной базе данных), то должно быть указано свойство SSPROP_PARAM_UDT_SCHEMANAME. Если определение определяемого пользователем типа находится в другой базе данных, то должны быть указаны свойства SSPROP_PARAM_UDT_CATALOGNAME и SSPROP_PARAM_UDT_SCHEMANAME.
Набор свойств DBPROPSET_SQLSERVERCOLUMN
Для поддержки создания таблиц в интерфейсе ITableDefinition SQL Server Native Client добавляет следующие три новых столбца в набор свойств DBPROPSET_SQLSERVERCOLUMN.
| Имя | Описание | Тип | Описание |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | Для столбцов типа DBTYPE_UDT это свойство содержит строку, указывающую имя каталога, в котором определен определяемый пользователем тип. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | Для столбцов типа DBTYPE_UDT это свойство содержит строку, указывающую имя схемы, в которой определен определяемый пользователем тип. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | Для столбцов типа DBTYPE_UDT это свойство содержит строку, указывающую однокомпонентное имя определяемого пользователем типа. Для других типов столбцов это свойство возвращает пустую строку. |
Примечание.
Определяемые пользователем типы не отображаются в наборе строк схемы PROVIDER_TYPES. Все столбцы доступны для чтения и записи.
ADO будет ссылаться на эти свойства с помощью соответствующей записи в столбце «Описание».
Свойство SSPROP_COL_UDTNAME является обязательным. Свойства SSPROP_COL_UDT_CATALOGNAME и SSPROP_COL_UDT_SCHEMANAME не обязательны. Если какое-либо свойство указывается неправильно, возвращается ошибка DB_E_ERRORSINCOMMAND.
Если ни свойство SSPROP_PARAM_UDT_CATALOGNAME, ни свойство SSPROP_PARAM_UDT_SCHEMANAME не указаны, то определяемый пользователем тип должен быть определен в той же базе данных и схеме, что и таблица.
Если определение определяемого пользователем типа и таблица находятся в разных схемах (но в одной базе данных), то должно быть указано свойство SSPROP_COL_UDT_SCHEMANAME.
Если определение определяемого пользователем типа находится в другой базе данных, то должны быть указаны свойства SSPROP_COL_UDT_CATALOGNAME и SSPROP_COL_UDT_CATALOGNAME.
Добавления и изменения для интерфейсов OLE DB
Sql Server Native Client добавляет новые значения или изменения во многих основных интерфейсах OLE DB.
Интерфейс ISSCommandWithParameters
Для поддержки определяемых пользователем объектов с помощью OLE DB собственный клиент SQL Server реализует ряд изменений, включая добавление интерфейса ISSCommandWithParameters . Этот новый интерфейс наследует основной интерфейс OLE DB — ICommandWithParameters. Помимо трех методов, унаследованных от ICommandWithParameters; GetParameterInfo, MapParameterNames и SetParameterInfo; ISSCommandWithParameters предоставляет методы GetParameterProperties и SetParameterProperties, используемые для обработки определенных типов данных сервера.
Примечание.
Интерфейс ISSCommandWithParameters также задействует возможности новой структуры SSPARAMPROPS.
Интерфейс IColumnsRowset
Помимо интерфейса ISSCommandWithParameters, собственный клиент SQL Server также добавляет новые значения в набор строк, возвращаемый из вызова метода IColumnsRowset::GetColumnRowset, включая следующее.
| Имя столбца | Тип | Описание |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | Идентификатор имени каталога определяемого пользователем типа. |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | Идентификатор имени схемы определяемого пользователем типа. |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | Идентификатор имени определяемого пользователем типа. |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Полное имя сборки, которое включает имя типа и все идентификационные данные сборки, необходимые для ссылки на сборку из среды CLR. |
Если столбец DBCOLUMN_TYPE имеет значение DBTYPE_UDT, то столбец определяемого пользователем типа сервера можно отличить от других двоичных типов, изучив добавленные метаданные определяемого пользователем типа, указанные выше. Если данные частично завершены, то тип сервера является определяемым пользователем типом. Для типов сервера, отличных от определяемых пользователем типов, эти столбцы всегда возвращают значение NULL.
Драйвер ODBC для собственного клиента SQL Server
В драйвер ODBC собственного клиента SQL Server были внесены некоторые изменения для поддержки определяемых пользователем пользователей. Драйвер ODBC для собственного клиента SQL Server сопоставляет UDT SQL Server SQL_SS_UDT с идентификатором типа данных SQL для конкретного драйвера. Столбцы определяемого пользователем типа отображаются как тип SQL_SS_UDT. Если столбец UDT сопоставляется явным образом с другим типом в инструкции SQL с помощью методов ToString или ToXMLString определяемого пользователем типа или с помощью функции CAST/CONVERT , тип столбца в результирующем наборе отражает фактический тип, в который был преобразован столбец.
SQLColAttribute, SQLDescribeParam, SQLGetDescField
Добавлены четыре новых поля дескриптора для конкретного драйвера, чтобы предоставить дополнительные сведения для столбца UDT результирующих наборов или параметра UDT хранимой процедуры или параметризованного запроса, которые необходимо получить с помощью функций SQLColAttribute, SQLDescribeParam и SQLGetDescField .
Это следующие поля дескриптора: 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
Кроме того, в результирующий набор добавляются три новых столбца драйвера, возвращаемых из функций SQLColumns и SQLProcedureColumns, чтобы предоставить дополнительные сведения о столбце результирующего набора UDT или параметре UDT. Это следующие столбцы: 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_C_CHAR SQL двоичные данные преобразуются в шестнадцатеричную строку.
При преобразовании из типов данных C в типы данных SQL типы SQL_C_WCHAR, SQL_C_BINARY и SQL_C_CHAR могут быть преобразованы в SQL_SS_UDT. Однако обратите внимание, что при преобразовании из типов данных SQL_C_WCHAR и SQL_C_CHAR SQL двоичные данные преобразуются в шестнадцатеричную строку.
См. также
Компоненты собственного клиента SQL Server
ISSCommandWithParameters (OLE DB)