Uso de tipos definidos por el usuario en SQL Server Native Client
Se aplica a: SQL Server
Azure SQL Database
Azure Synapse Analytics
Analytics Platform System (PDW)
Importante
SQL Server Native Client (SNAC) no se incluye con:
- SQL Server 2022 (16.x) y versiones posteriores
- SQL Server Management Studio 19 y versiones posteriores
Sql Server Native Client (SQLNCLI o SQLNCLI11) y el proveedor MICROSOFT OLE DB heredado para SQL Server (SQLOLEDB) no se recomiendan para el desarrollo de aplicaciones nuevas.
En el caso de los proyectos nuevos, use uno de los siguientes controladores:
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)