Uso de tipos definidos por el usuario en SQL Server Native Client

  • Artículo

Se aplica a: SQL Server Azure SQL Database Not supported. Azure Synapse Analytics Analytics Platform System (PDW)

Importante

SQL Server Native Client (a menudo abreviado SNAC) se ha quitado de SQL Server 2022 (16.x) y SQL Server Management Studio 19 (SSMS). No se recomienda SQL Server Native Client (SQLNCLI o SQLNCLI11) ni el proveedor OLE DB de Microsoft heredado para SQL Server (SQLOLEDB) para el desarrollo de nuevas aplicaciones. Cambie al nuevo controlador OLE DB de Microsoft (MSOLEDBSQL) para SQL Server o al controlador ODBC de Microsoft ODBC Driver for SQL Server más reciente de ahora en adelante. Para SQLNCLI que se incluye como componente de motor de base de datos de SQL Server (versiones 2012 a 2019), consulte esta excepción de ciclo de vida de soporte técnico.

Los tipos definidos por el usuario (UDT) se introdujeron en SQL Server 2005 (9.x). Los UDT amplían el sistema de tipos SQL, ya que permiten almacenar objetos y estructuras de datos personalizadas en una base de datos de SQL Server. Los UDT pueden contener varios tipos de datos y pueden presentar distintos comportamientos, lo que los diferencia de los tipos de datos de alias tradicionales que constan de un único tipo de datos del sistema de SQL Server. Los UDT pueden definirse mediante cualquiera de los lenguajes compatibles con .NET Common Language Runtime (CLR) que genere código comprobable, Esto incluye C# y Visual Basic .NET. Los datos se exponen como campos y propiedades de una clase o estructura de .NET, y los métodos de esa clase o estructura definen los comportamientos.

Un UDT se puede usar como definición de columnas de una tabla, como una variable de un lote de Transact-SQL o como un argumento de una función o un procedimiento almacenado de Transact-SQL.

Proveedor OLE DB de SQL Server Native Client

El proveedor OLE DB de SQL Server Native Client admite udT como tipos binarios con información de metadatos, lo que permite administrar udT como objetos. Las columnas UDT se exponen como DBTYPE_UDT y sus metadatos se exponen mediante la interfaz OLE DB básica IColumnRowset y la nueva interfaz ISSCommandWithParameters.

Nota

El método IRowsetFind::FindNextRow no funciona con el tipo de datos UDT. Si el UDT se usa como un tipo de columna de búsqueda, se devuelve DB_E_BADCOMPAREOP.

Enlaces y conversiones de datos

En la tabla siguiente se describe el enlace y la conversión que tiene lugar al usar los tipos de datos enumerados con un UDT de SQL Server. Las columnas UDT se exponen a través del proveedor OLE DB de SQL Server Native Client como DBTYPE_UDT. Puede obtener metadatos mediante los conjuntos de filas de esquema adecuados, de modo que pueda administrar sus propios tipos definidos como objetos.

Tipo de datos A datos XML

UDT		 A datos XML

non-UDT		 Desde datos XML

UDT		 Desde datos XML

non-UDT
DBTYPE_UDT Compatible6 Error1 Compatible6 Error5
DBTYPE_BYTES Compatible6 N/D2 Compatible6 N/D2
DBTYPE_WSTR Compatible3,6 N/D2 Compatible4,6 N/D2
DBTYPE_BSTR Compatible3,6 N/D2 Compatible4 N/D2
DBTYPE_STR Compatible3,6 N/D2 Compatible4,6 N/D2
DBTYPE_IUNKNOWN No compatible N/D2 No compatible N/D2
DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) Compatible6 N/D2 Compatible4 N/D2
DBTYPE_VARIANT (VT_BSTR) Compatible3,6 N/D2 N/D N/D2

1Si se especifica un tipo de servidor distinto de DBTYPE_UDT con ICommandWithParameters::SetParameterInfo y el tipo de descriptor de acceso es DBTYPE_UDT, se produce un error cuando se ejecuta la instrucción (DB_E_ERRORSOCCURRED; el estado del parámetro es DBSTATUS_E_BADACCESSOR). De lo contrario, los datos se envían al servidor, pero el servidor devuelve un error que indica que no hay ninguna conversión implícita de UDT al tipo de datos del parámetro.

2Más allá del ámbito de este tema.

3Las cadenas hexadecimales se convierten en datos binarios.

4Los datos binarios se convierten en cadenas hexadecimales.

5La validación puede tener lugar en el momento de creación del descriptor de acceso o en el momento de la captura; el error es DB_E_ERRORSOCCURRED, con el estado de enlace establecido en DBBINDSTATUS_UNSUPPORTEDCONVERSION.

6Puede usarse BY_REF.

DBTYPE_NULL y DBTYPE_EMPTY pueden enlazarse en parámetros de entrada, pero no en parámetros de salida ni en resultados. Cuando se enlazan para parámetros de entrada, el estado tiene que establecerse en DBSTATUS_S_ISNULL o DBSTATUS_S_DEFAULT.

DBTYPE_UDT también puede convertirse en DBTYPE_EMPTY y DBTYPE_NULL, pero DBTYPE_NULL y DBTYPE_EMPTY no pueden convertirse en DBTYPE_UDT. Este comportamiento es coherente con el de DBTYPE_BYTES.

Nota

Se usa una nueva interfaz para tratar los UDT como parámetros, la interfaz ISSCommandWithParameters, que hereda de ICommandWithParameters. Las aplicaciones deben usar esta interfaz para establecer al menos la propiedad SSPROP_PARAM_UDT_NAME del conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER para los parámetros UDT. De lo contrario, ICommand::Execute devolverá DB_E_ERRORSOCCURRED. Esta interfaz y este conjunto de propiedades se describen más adelante en este tema.

Si un tipo definido por el usuario se inserta en una columna que no es lo suficientemente grande como para contener todos sus datos, ICommand::Execute devuelve S_OK con un estado DB_E_ERRORSOCCURRED.

Las conversiones de datos que proporcionan los servicios principales de OLE DB (IDataConvert) no son aplicables a DBTYPE_UDT. No se admite ningún otro enlace.

Adiciones y cambios en los conjuntos de filas de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchos de los conjuntos de filas de esquema OLE DB principales.

El conjunto de filas de esquema PROCEDURE_PARAMETERS

Se han realizado las siguientes adiciones al conjunto de filas de esquema PROCEDURE_PARAMETERS.

Nombre de la columna Tipo Descripción
SS_UDT_CATALOGNAME DBTYPE_WSTR Identificador de nombre de tres partes.
SS_UDT_SCHEMANAME DBTYPE_WSTR Identificador de nombre de tres partes.
SS_UDT_NAME DBTYPE_WSTR Identificador de nombre de tres partes.
SS_UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR Nombre de ensamblado completo, que incluye el nombre de tipo y toda la identificación de ensamblado necesaria a la que tiene que hacer referencia CLR.

El conjunto de filas de esquema SQL_ASSEMBLIES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema específico del proveedor que describe los UDT registrados. El servidor ASSEMBLY puede especificarse como DBTYPE_WSTR, pero no está presente en el conjunto de filas. Si no se especifica, el conjunto de filas tendrá como valor predeterminado el servidor actual. El conjunto de filas de esquema SQL_ASSEMBLIES se define en la tabla siguiente.

Nombre de la columna Tipo Descripción
ASSEMBLY_CATALOG DBTYPE_WSTR Nombre de catálogo del ensamblado que contiene el tipo.
ASSEMBLY_SCHEMA DBTYPE_WSTR Nombre de esquema o nombre de propietario del ensamblado que contiene el tipo. Aunque el ámbito de los ensamblados viene determinado por la base de datos y no por el esquema, los ensamblados tienen un propietario que se refleja aquí.
ASSEMBLY_NAME DBTYPE_WSTR Nombre del ensamblado que contiene el tipo.
ASSEMBLY_ID DBTYPE_UI4 Identificador de objeto del ensamblado que contiene el tipo.
PERMISSION_SET DBTYPE_WSTR Valor que indica el ámbito de acceso del ensamblado. Entre los valores posibles se incluyen "SAFE", "EXTERNAL_ACCESS" y "UNSAFE".
ASSEMBLY_BINARY DBTYPE_BYTES Representación binaria del ensamblado.

El conjunto de filas de esquema SQL_ASSEMBLIES_DEPENDENCIES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema específico del proveedor que describe las dependencias de ensamblado para un servidor especificado. El autor de la llamada puede especificar ASSEMBLY_SERVER como DBTYPE_WSTR, pero no está presente en el conjunto de filas. Si no se especifica, el conjunto de filas tendrá como valor predeterminado el servidor actual. El conjunto de filas de esquema SQL_ASSEMBLY_DEPENDENCIES se define en la tabla siguiente.

Nombre de la columna Tipo Descripción
ASSEMBLY_CATALOG DBTYPE_WSTR Nombre de catálogo del ensamblado que contiene el tipo.
ASSEMBLY_SCHEMA DBTYPE_WSTR Nombre de esquema o nombre de propietario del ensamblado que contiene el tipo. Aunque el ámbito de los ensamblados viene determinado por la base de datos y no por el esquema, los ensamblados tienen un propietario que se refleja aquí.
ASSEMBLY_ID DBTYPE_UI4 Identificador de objeto del ensamblado.
REFERENCED_ASSEMBLY_ID DBTYPE_UI4 Identificador de objeto del ensamblado al que se hace referencia.

El conjunto de filas de esquema SQL_USER_TYPES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema, SQL_USER_TYPES, que describe cuándo se agregan los UDT registrados para un servidor especificado. El autor de la llamada debe especificar UDT_SERVER como DBTYPE_WSTR, pero no está presente en el conjunto de filas. El conjunto de filas de esquema SQL_USER_TYPES se define en la tabla siguiente.

Nombre de la columna Tipo Descripción
UDT_CATALOGNAME DBTYPE_WSTR Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.
UDT_SCHEMANAME DBTYPE_WSTR Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.
UDT_NAME DBTYPE_WSTR Nombre del ensamblado que contiene la clase UDT.
UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR El nombre de tipo completo (AQN) incluye el nombre de tipo precedido del espacio de nombres, si procede.

El conjunto de filas de esquema COLUMNS

Las adiciones al conjunto de filas de esquema COLUMNS incluyen las columnas siguientes.

Nombre de la columna Tipo Descripción
SS_UDT_CATALOGNAME DBTYPE_WSTR Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.
SS_UDT_SCHEMANAME DBTYPE_WSTR Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.
SS_UDT_NAME DBTYPE_WSTR Nombre del UDT.
SS_UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR El nombre de tipo completo (AQN) incluye el nombre de tipo precedido del espacio de nombres, si procede.

Adiciones y cambios en los conjuntos de propiedades de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchos de los conjuntos de propiedades OLE DB principales.

El conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER

Para admitir udT a través de OLE DB, SQL Server Native Client implementa el nuevo conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER que contiene los valores siguientes.

Nombre Escribir Descripción
SSPROP_PARAM_UDT_CATALOGNAME DBTYPE_WSTR Identificador de nombre de tres partes.

Para los parámetros UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el tipo definido por el usuario.
SSPROP_PARAM_UDT_SCHEMANAME DBTYPE_WSTR Identificador de nombre de tres partes.

Para los parámetros UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el tipo definido por el usuario.
SSPROP_PARAM_UDT_NAME DBTYPE_WSTR Identificador de nombre de tres partes.

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre de una sola parte del tipo definido por el usuario.

La propiedad SSPROP_PARAM_UDT_NAME es obligatoria. Las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME son opcionales. Si alguna de las propiedades se especifica incorrectamente, se devolverá DB_E_ERRORSINCOMMAND. Si no se especifican las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME, el UDT debe definirse en la misma base de datos y esquema que la tabla. Si la definición UDT no está en el mismo esquema que la tabla (pero está en la misma base de datos), debe especificarse la propiedad SSPROP_PARAM_UDT_SCHEMANAME. Si la definición UDT está en una base de datos diferente, deben especificarse las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME.

El conjunto de propiedades DBPROPSET_SQLSERVERCOLUMN

Para admitir la creación de tablas en la interfaz ITableDefinition , SQL Server Native Client agrega las tres columnas nuevas siguientes al conjunto de propiedades DBPROPSET_SQLSERVERCOLUMN.

Nombre Description Tipo Descripción
SSPROP_COL_UDT_CATALOGNAME UDT_CATALOGNAME VT_BSTR Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.
SSPROP_COL_UDT_SCHEMANAME UDT_SCHEMANAME VT_BSTR Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.
SSPROP_COL_UDT_NAME UDT_NAME VT_BSTR Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre de una sola parte del UDT. Para otros tipos de columna, esta propiedad devuelve una cadena vacía.

Nota

Los UDT no aparecerán en el conjunto de filas de esquema PROVIDER_TYPES. Todas las columnas tienen acceso de lectura y escritura.

ADO hará referencia a estas propiedades utilizando la entrada correspondiente de la columna Descripción.

La propiedad SSPROP_COL_UDTNAME es obligatoria. Las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME son opcionales. Si alguna de las propiedades se especifica de forma incorrecta, se devolverá DB_E_ERRORSINCOMMAND.

Si no se especifican las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME, el UDT debe definirse en la misma base de datos y esquema que la tabla.

Si la definición UDT no está en el mismo esquema que la tabla (pero está en la misma base de datos), debe especificarse la propiedad SSPROP_COL_UDT_SCHEMANAME.

Si la definición UDT está en una base de datos diferente, deben especificarse las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME.

Adiciones y cambios en las interfaces de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchas de las interfaces OLE DB principales.

La interfaz ISSCommandWithParameters

Para admitir udT a través de OLE DB, SQL Server Native Client implementa varios cambios, incluida la adición de la interfaz ISSCommandWithParameters . Esta nueva interfaz hereda de la interfaz OLE DB básica ICommandWithParameters. Además de los tres métodos heredados de ICommandWithParameters; GetParameterInfo, MapParameterNames y SetParameterInfo; ISSCommandWithParameters proporciona los métodos GetParameterProperties y SetParameterProperties que se usan para controlar tipos de datos específicos del servidor.

Nota:

La interfaz ISSCommandWithParameters también usa la nueva estructura SSPARAMPROPS.

La interfaz IColumnsRowset

Además de la interfaz ISSCommandWithParameters , SQL Server Native Client también agrega nuevos valores al conjunto de filas devuelto desde la llamada al método IColumnsRowset::GetColumnRowset , incluido lo siguiente.

Nombre de la columna Tipo Descripción
DBCOLUMN_SS_UDT_CATALOGNAME DBTYPE_WSTR Identificador de nombre de catálogo UDT.
DBCOLUMN_SS_UDT_SCHEMANAME DBTYPE_WSTR Identificador de nombre de esquema UDT.
DBCOLUMN_SS_UDT_NAME DBTYPE_WSTR Identificador de nombre UDT.
DBCOLUMN_SS_ASSEMBLY_TYPENAME DBTYPE_WSTR Nombre de ensamblado completo, que incluye el nombre de tipo y toda la identificación de ensamblado necesaria a la que debe hacer referencia CLR.

Es posible diferenciar una columna UDT del servidor de otros tipos binarios cuando el parámetro DBCOLUMN_TYPE está establecido en DBTYPE_UDT; para ello, hay que examinar los metadatos UDT agregados especificados anteriormente. Si esos datos están parcialmente completos, el tipo del servidor es un UDT. Para los tipos del servidor que no son UDT, estas columnas se devuelven siempre como NULL.

Controlador ODBC de SQL Server Native Client

Se han realizado varios cambios en el controlador ODBC de SQL Server Native Client para admitir udT. El controlador ODBC de SQL Server Native Client asigna el UDT de SQL Server a SQL_SS_UDT identificador de tipo de datos SQL específico del controlador. Las columnas UDT se exponen como SQL_SS_UDT. Si asigna explícitamente una columna UDT a otro tipo de una instrucción SQL mediante los métodos ToString o ToXMLString del UDT o a través de la función CAST/CONVERT , el tipo de columna del conjunto de resultados refleja el tipo real en el que se convirtió la columna.

SQLColAttribute, SQLDescribeParam, SQLGetDescField

Se han agregado cuatro nuevos campos descriptores específicos del controlador para proporcionar información adicional para una columna UDT de un conjunto de resultados, o un parámetro UDT de una consulta almacenada o parametrizada, que se recuperarán a través de las funciones SQLColAttribute, SQLDescribeParam y SQLGetDescField .

Estos cuatro nuevos campos descriptores que se han agregado son SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME y SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.

SQLColumns, SQLProcedureColumns

Además, se agregan tres nuevas columnas específicas del controlador al conjunto de resultados devueltos por las funciones SQLColumns y SQLProcedureColumns para proporcionar información adicional sobre una columna del conjunto de resultados UDT o un parámetro UDT. Estas tres nuevas columnas son SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME y SS_UDT_ASSEMBLY_TYPE_NAME.

Conversiones admitidas

Al convertir tipos de datos de SQL a C, SQL_C_WCHAR, SQL_C_BINARY y SQL_C_CHAR pueden convertirse en SQL_SS_UDT. Tenga en cuenta, no obstante, que los datos binarios se convierten en una cadena hexadecimal cuando se realizan conversiones desde los tipos de datos SQL SQL_C_CHAR y SQL_C_WCHAR.

Al convertir tipos de datos de C a SQL, SQL_C_WCHAR, SQL_C_BINARY y SQL_C_CHAR pueden convertirse en SQL_SS_UDT. Tenga en cuenta, sin embargo, que los datos binarios se convierten en una cadena hexadecimal al convertir de los tipos de datos SQL_C_WCHAR y SQL_C_CHAR SQL.

Consulte también

Características de SQL Server Native Client
ISSCommandWithParameters (OLE DB)