Usando tipos definidos pelo usuário no SQL Server Native Client
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure 
Azure Synapse Analytics PDW (Analytics Platform System)
Importante
O SQL Server Native Client (SNAC) não é fornecido com:
- SQL Server 2022 (16.x) e versões posteriores
- SQL Server Management Studio 19 e versões posteriores
O SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o provedor OLE DB para SQL Server (SQLOLEDB) da Microsoft herdado não são recomendados para desenvolver um novo aplicativo.
Para novos projetos, use um dos seguintes drivers:
Para SQLNCLI que é fornecido como um componente do Mecanismo de Banco de Dados do SQL Server (versões 2012 a 2019), confira esta exceção de Ciclo de Vida de Suporte.
O SQL Server 2005 (9.x) introduziu os UDTs (tipos definidos pelo usuário). Os UDTs estendem o sistema de tipos SQL, permitindo que você armazene objetos e estruturas de dados personalizadas em um banco de dados do SQL Server. Os UDTs podem conter vários tipos de dados e ter comportamentos, o que os diferencia dos tipos de dados de alias tradicionais, que consistem em um único tipo de dado do sistema no SQL Server. UDTs são definidos usando quaisquer dos idiomas com suporte pelo .NET CRL (Common Language Runtime) que gera código verificável. Isso inclui C# e Visual Basic .NET. Os dados são expostos como campos e propriedades de uma classe ou estrutura .NET e os comportamentos são definidos pelos métodos da classe ou estrutura.
Um UDT pode ser usado como a definição de coluna de uma tabela, como uma variável em um lote Transact-SQL ou como um argumento de uma função Transact-SQL ou procedimento armazenado.
Provedor OLE DB do SQL Server Native Client
O provedor OLE DB do SQL Server Native Client dá suporte a UDTs como tipos binários com informações de metadados, o que permite gerenciar UDTs como objetos. As colunas UDT são expostas como DBTYPE_UDT e seus metadados são expostos pela interface principal do OLE DB IColumnRowset e pela nova interface ISSCommandWithParameters.
Observação
O método IRowsetFind::FindNextRow não funciona com o tipo de dados UDT. DB_E_BADCOMPAREOP será retornado se o UDT for usado como um tipo de coluna de pesquisa.
Coerções e associações de dados
A tabela a seguir descreve a associação e a coerção que ocorrem ao usar os tipos de dados listados com o UDT SQL Server. As colunas UDT são expostas por meio do provedor OLE DB do SQL Server Native Client como DBTYPE_UDT. Você pode obter metadados por meio dos conjuntos de linhas de esquema apropriados de forma que possa gerenciar seus próprios tipos definidos como objetos.
| Tipo de dados | Para servidor UDT |
Para servidor não UDT |
Do servidor UDT |
Do servidor não UDT |
|---|---|---|---|---|
| DBTYPE_UDT | Compatível6 | Erro1 | Compatível6 | Erro5 |
| DBTYPE_BYTES | Compatível6 | N/A2 | Compatível6 | N/A2 |
| DBTYPE_WSTR | Compatível3, 6 | N/A2 | Compatível4, 6 | N/A2 |
| DBTYPE_BSTR | Compatível3, 6 | N/A2 | Compatível4 | N/A2 |
| DBTYPE_STR | Compatível3, 6 | N/A2 | Compatível4, 6 | N/A2 |
| DBTYPE_IUNKNOWN | Sem suporte | N/A2 | Sem suporte | N/A2 |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Compatível6 | N/A2 | Compatível4 | N/A2 |
| DBTYPE_VARIANT (VT_BSTR) | Compatível3, 6 | N/A2 | N/D | N/A2 |
1Se um tipo de servidor diferente de DBTYPE_UDT for especificado com ICommandWithParameters::SetParameterInfo e o tipo de acessador for DBTYPE_UDT, ocorrerá um erro quando a instrução for executada (para DB_E_ERRORSOCCURRED, o status do parâmetro é DBSTATUS_E_BADACCESSOR). Caso contrário, os dados serão enviados para o servidor, mas ele retornará um erro indicando que não há conversão implícita do UDT para o tipo de dados do parâmetro.
2 Além do escopo deste tópico.
3 Ocorre a conversão de dados de cadeia de caracteres hexadecimal para dados binários.
4 Ocorre a conversão de dados binários para cadeia de caracteres hexadecimal.
5Pode ocorrer a validação no momento de criação do acessador ou, no momento do fetch, o erro é DB_E_ERRORSOCCURRED, o status de associação está definido como DBBINDSTATUS_UNSUPPORTEDCONVERSION.
6BY_REF pode ser usado.
DBTYPE_NULL e DBTYPE_EMPTY podem ser associados a parâmetros de entrada, mas não a parâmetros ou resultados de saída. Quando eles são associados a parâmetros de entrada, o status precisa ser definido como DBSTATUS_S_ISNULL ou DBSTATUS_S_DEFAULT.
DBTYPE_UDT pode ser convertido em DBTYPE_EMPTY e DBTYPE_NULL, porém DBTYPE_NULL e DBTYPE_EMPTY não podem ser convertidos em DBTYPE_UDT. Isso é consistente com DBTYPE_BYTES.
Observação
Uma nova interface é usada para lidar com UDTs como parâmetros, ISSCommandWithParameters, herdada de ICommandWithParameters. Os aplicativos devem usar esta interface para definir pelo menos o SSPROP_PARAM_UDT_NAME da propriedade DBPROPSET_SQLSERVERPARAMETER definida para os parâmetros de UDT. Se isto não for feito, ICommand::Execute retornará DB_E_ERRORSOCCURRED. Esta interface e conjunto de propriedades serão descritos posteriormente neste tópico.
Se um tipo definido pelo usuário for inserido em uma coluna que não seja grande o suficiente para manter todos os dados, ICommand::Execute retornará S_OK com o status DB_E_ERRORSOCCURRED.
As conversões de dados fornecidas pelos serviços principais do OLE DB (IDataConvert) não são aplicáveis a DBTYPE_UDT. As demais associações não têm suporte.
Adições e alterações do conjunto de linhas do OLE DB
O SQL Server Native Client adiciona novos valores ou alterações a muitos dos principais conjuntos de linhas do esquema OLE DB.
O conjunto de linhas do esquema PROCEDURE_PARAMETERS
As adições a seguir foram feitas ao conjunto de linhas de esquema de PROCEDURE_PARAMETERS.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | O identificador de nome de três partes. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | O identificador de nome de três partes. |
| SS_UDT_NAME | DBTYPE_WSTR | O identificador de nome de três partes. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | O Nome Qualificado do Assembly, que inclui o nome de tipo e toda a identificação de assembly necessários para referência pelo CLR. |
O conjunto de linhas do esquema SQL_ASSEMBLIES
O provedor OLE DB do SQL Server Native Client expõe um novo conjunto de linhas de esquema específico do provedor que descreve os UDTs registrados. O servidor de ASSEMBLY pode ser especificado como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. Se não estiver especificado, o conjunto de linhas seguirá o padrão do servidor atual. O conjunto de linhas de esquema de SQL_ASSEMBLIES é definido na tabela a seguir.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | O nome de catálogo do assembly que contém o tipo. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | O nome do esquema ou nome do proprietário do assembly que contém o tipo. Embora os assemblies tenham escopo por banco de dados e não por esquema, eles ainda têm um proprietário que é refletido aqui. |
| ASSEMBLY_NAME | DBTYPE_WSTR | O nome do assembly que contém o tipo. |
| ASSEMBLY_ID | DBTYPE_UI4 | A id do objeto do assembly que contém o tipo. |
| PERMISSION_SET | DBTYPE_WSTR | Um valor que indica o escopo de acesso para o assembly. Valores incluem "SAFE", "EXTERNAL_ACCESS" e "UNSAFE". |
| ASSEMBLY_BINARY | DBTYPE_BYTES | A representação binária do assembly. |
O conjunto de linhas do esquema SQL_ASSEMBLIES_ DEPENDENCIES
O provedor OLE DB do SQL Server Native Client expõe um novo conjunto de linhas de esquema específico do provedor que descreve as dependências do assembly para um servidor especificado. O ASSEMBLY_SERVER pode ser especificado pelo chamador como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. Se não estiver especificado, o conjunto de linhas seguirá o padrão do servidor atual. O conjunto de linhas de esquema de SQL_ASSEMBLY_DEPENDENCIES é definido na tabela a seguir.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | O nome de catálogo do assembly que contém o tipo. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | O nome do esquema ou nome do proprietário do assembly que contém o tipo. Embora os assemblies tenham escopo por banco de dados e não por esquema, eles ainda têm um proprietário, que é refletido aqui. |
| ASSEMBLY_ID | DBTYPE_UI4 | A id do objeto do assembly. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | A id do objeto do assembly referenciado. |
O conjunto de linhas do esquema SQL_USER_TYPES
O provedor OLE DB do SQL Server Native Client expõe um novo conjunto de linhas de esquema, SQL_USER_TYPES, que descreve quando os UDTs registrados para um servidor especificado são adicionados. O UDT_SERVER deve ser especificado pelo chamador como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. O conjunto de linhas de esquema de SQL_USER_TYPES é definido na tabela a seguir.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido. |
| UDT_SCHEMANAME | DBTYPE_WSTR | Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido. |
| UDT_NAME | DBTYPE_WSTR | O nome do assembly que contém a classe do UDT. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | O AQN (nome de tipo completo) inclui o nome do tipo prefixado pelo namespace, se aplicável. |
O conjunto de linhas do esquema COLUMNS
Adições para o conjunto de linhas de esquema de COLUMNS incluem as colunas a seguir.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido. |
| SS_UDT_NAME | DBTYPE_WSTR | O nome do UDT |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | O AQN (nome de tipo completo) inclui o nome do tipo prefixado pelo namespace, se aplicável. |
Adições e alterações do conjunto de propriedades do OLE DB
O SQL Server Native Client adiciona novos valores ou alterações a muitos dos principais conjuntos de propriedades do OLE DB.
O conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER
Para dar suporte a UDTs por meio do OLE DB, o SQL Server Native Client implementa o novo conjunto de propriedades DBPROPSET_SQLSERVERPARAMETER que contém os valores a seguir.
| Nome | Tipo | DESCRIÇÃO |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | O identificador de nome de três partes. Para parâmetros de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o tipo definido pelo usuário é definido. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | O identificador de nome de três partes. Para parâmetros de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o tipo definido pelo usuário é definido. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | O identificador de nome de três partes. Para colunas de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome de apenas uma parte do tipo definido pelo usuário. |
SSPROP_PARAM_UDT_NAME é obrigatório. SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME são opcionais. Se alguma propriedade for especificada incorretamente, o DB_E_ERRORSINCOMMAND será retornado. Se SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME não forem especificados, então o UDT deverá ser definido no mesmo banco de dados e esquema que a tabela. Se a definição de UDT não estiver no mesmo esquema que a tabela (mas estiver no mesmo banco de dados), então SSPROP_PARAM_UDT_SCHEMANAME deverá ser especificado. Se a definição de UDT estiver em um banco de dados diferente, SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME deverão ser especificados.
O conjunto de propriedades de DBPROPSET_SQLSERVERCOLUMN
Para dar suporte à criação de tabelas na interface ITableDefinition, o SQL Server Native Client adiciona as três novas colunas a seguir ao conjunto de propriedades DBPROPSET_SQLSERVERCOLUMN.
| Nome | Descrição | Type | DESCRIÇÃO |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome de apenas uma parte do UDT. Para outros tipos de coluna, essa propriedade retorna uma cadeia de caracteres vazia. |
Observação
Os UDTs não aparecem no conjunto de linhas de esquema de PROVIDER_TYPES. Todas as colunas têm direito de leitura e gravação.
O ADO recorrerá a estas propriedades usando a entrada correspondente na coluna Descrição.
SSPROP_COL_UDTNAME é obrigatório. SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME são opcionais. Se uma das propriedades for especificada incorretamente, DB_E_ERRORSINCOMMAND será retornado.
Se SSPROP_COL_UDT_CATALOGNAME nem SSPROP_COL_UDT_SCHEMANAME forem especificados, o UDT deverá ser definido no mesmo banco de dados e esquema que a tabela.
Se a definição de UDT não estiver no mesmo esquema que a tabela (mas estiver no mesmo banco de dados), então SSPROP_COL_UDT_SCHEMANAME deverá ser especificado.
Se a definição de UDT estiver em um banco de dados diferente, SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME devem ser especificados.
Adições e alterações de interface do OLE DB
O SQL Server Native Client adiciona novos valores ou alterações a muitas das principais interfaces OLE DB.
A interface ISSCommandWithParameters
Para dar suporte a UDTs por meio do OLE DB, o SQL Server Native Client implementa várias alterações, incluindo a adição da interface ISSCommandWithParameters . Essa nova interface herda as propriedades da interface principal do OLE DB ICommandWithParameters. Além dos três métodos herdados de ICommandWithParameters; GetParameterInfo, MapParameterNames e SetParameterInfo; ISSCommandWithParameters fornece os métodos GetParameterProperties e SetParameterProperties que são usados para lidar com tipos de dados específicos do servidor.
Observação
A interface ISSCommandWithParameters também usa a nova estrutura SSPARAMPROPS.
A interface IColumnsRowset
Além da interface ISSCommandWithParameters , o SQL Server Native Client também adiciona novos valores ao conjunto de linhas retornado da chamada do método IColumnsRowset::GetColumnRowset , incluindo o seguinte.
| Nome da coluna | Type | DESCRIÇÃO |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | Um identificador do nome de catálogo do UDT. |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | Um identificador do nome do esquema do UDT. |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | Um identificador de nome do UDT. |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | O nome qualificado do assembly, que inclui o nome de tipo e toda a identificação de assembly necessários para referência pelo CLR. |
É possível diferenciar uma coluna de UDT do servidor de outros tipos binários quando DBCOLUMN_TYPE for definido como DBTYPE_UDT observando os metadados de UDT adicionados especificados acima. Se esses dados estiverem parcialmente completos, o tipo de servidor será um UDT. Para tipos de servidores não UDT, essas colunas são sempre retornadas como NULL.
Driver ODBC do SQL Server Native Client
Várias alterações foram feitas no driver ODBC do SQL Server Native Client para dar suporte a UDTs. O driver ODBC do SQL Server Native Client mapeia o UDT do SQL Server para SQL_SS_UDT identificador de tipo de dados SQL específico do driver. São exibidas colunas de UDT como SQL_SS_UDT. Se você mapear uma coluna UDT explicitamente para outro tipo em uma instrução SQL usando os métodos ToString ou ToXMLString do UDT ou por meio da função CAST/CONVERT , o tipo da coluna no conjunto de resultados refletirá o tipo real para o qual a coluna foi convertida
SQLColAttribute, SQLDescribeParam, SQLGetDescField
Quatro novos campos de descritor específicos do driver foram adicionados para fornecer informações adicionais para uma coluna UDT de um conjunto de resultados ou um parâmetro UDT de procedimento armazenado/consulta parametrizada, a ser recuperado por meio das funções SQLColAttribute, SQLDescribeParameter e SQLGetDescField .
Os quatro novos campos do descritor adicionados são SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME e SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.
SQLColumns, SQLProcedureColumns
Além disso, três novas colunas específicas do driver são adicionadas ao conjunto de resultados retornado das funções SQLColumns e SQLProcedureColumns para fornecer informações adicionais sobre uma coluna de conjunto de resultados UDT ou um parâmetro UDT. Essas três colunas novas são SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME e SS_UDT_ASSEMBLY_TYPE_NAME.
Conversões com suporte
Na conversão de tipos de dados SQL para C, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR a SQL_SS_UDT. Porém, observe que os dados binários são convertidos a uma cadeia de caracteres hexadecimais na conversão dos tipos de dados SQL_C_WCHAR e SQL_C_CHAR SQL.
Na conversão de tipos de dados C para SQL, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR a SQL_SS_UDT. Observe, no entanto, que os dados binários são convertidos em uma cadeia de caracteres hexadecimal ao converter dos tipos de dados SQL SQL_C_WCHAR e SQL_C_CHAR.
Confira também
Recursos do SQL Server Native Client
ISSCommandWithParameters (OLE DB)