Usando tipos definidos pelo usuário no SQL Server Native Client

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Not supported. Azure Synapse Analytics PDW (Analytics Platform System)

Importante

O SQL Server Native Client (geralmente abreviado como SNAC) foi removido do SQL Server 2022 (16.x) e do SSMS (SQL Server Management Studio) 19. O SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o Provedor OLE DB herdado da Microsoft para o SQL Server (SQLOLEDB) não são recomendados para um novo desenvolvimento de aplicativo. Alterne para o novo Driver do Microsoft OLE DB para SQL Server (MSOLEDBSQL) ou o Microsoft ODBC Driver for SQL Server mais recente no futuro. 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 oferece 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 de 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 as UDTs registradas para um servidor especificado são adicionadas. 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 OLE DB.

O conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER

Para oferecer 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 seguintes valores.

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 oferecer 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 interfaces OLE DB principais.

A interface ISSCommandWithParameters

Para oferecer 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 manipular 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 oferecer 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 em que 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, SQLDescribeParam 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_C_WCHAR e SQL_C_CHAR SQL.

Confira também

Recursos do SQL Server Native Client
ISSCommandWithParameters (OLE DB)