Uso di tipi definiti dall'utente in SQL Server Native Client
Si applica a: 
SQL Server Database SQL di Azure 
Azure Synapse Analytics Analytics Platform System (PDW)
Importante
SQL Server Native Client (SNAC) non viene fornito con:
- SQL Server 2022 (16.x) e versioni successive
- SQL Server Management Studio 19 e versioni successive
SQL Server Native Client (SQLNCLI o SQLNCLI11) e il provider OLE DB Microsoft legacy per SQL Server (SQLOLEDB) non sono consigliati per lo sviluppo di nuove applicazioni.
Per i nuovi progetti, usare uno dei driver seguenti:
Per SQLNCLI fornito come componente del motore di database di SQL Server (versioni dal 2012 al 2019), vedere questa Eccezione relativa al ciclo di vita del supporto.
SQL Server 2005 (9.x) ha introdotto i tipi definiti dall'utente (UDT). I tipi definiti dall'utente estendono il sistema di tipi SQL consentendo di archiviare oggetti e strutture di dati personalizzate in un database di SQL Server. I tipi definiti dall'utente possono contenere più tipi di dati e possono assumere comportamenti, differenziandoli dai tipi di dati alias tradizionali costituiti da un singolo tipo di dati di sistema di SQL Server. I tipi definiti dall'utente vengono definiti utilizzando uno dei linguaggi supportati da .NET Common Language Runtime (CLR) che generano codice verificabile, Sono inclusi C# e Visual Basic .NET. I dati vengono esposti come campi e proprietà di una classe o struttura .NET mentre i comportamenti vengono definiti dai metodi della classe o della struttura.
È possibile usare un UDT come definizione di colonna di una tabella, come variabile in un batch Transact-SQL oppure come argomento di una funzione o di una stored procedure Transact-SQL.
Provider OLE DB di SQL Server Native Client
Il provider OLE DB di SQL Server Native Client supporta tipi definiti dall'utente come tipi binari con informazioni sui metadati, che consentono di gestire i tipi definiti dall'utente come oggetti . Le colonne con tipo definito dall'utente vengono esposte come DBTYPE_UDT e i relativi metadati vengono esposti tramite l'interfaccia OLE DB principale IColumnRowset e la nuova interfaccia ISSCommandWithParameters.
Nota
Il metodo IRowsetFind::FindNextRow non funziona con il tipo di dati UDT. Se il tipo definito dall'utente viene utilizzato come tipo di colonna di ricerca, viene restituito DB_E_BADCOMPAREOP.
Associazione dati e coercizioni
Nella tabella seguente vengono descritte l'associazione e la coercizione che si verificano quando si usano i tipi di dati elencati con un tipo definito dall'utente di SQL Server. Le colonne definite dall'utente vengono esposte tramite il provider OLE DB di SQL Server Native Client come DBTYPE_UDT. È possibile ottenere i metadati tramite i set di righe dello schema appropriati in modo da potere gestire i tipi definiti personalizzati come oggetti.
| Tipo di dati | Al server UDT |
Al server non UDT |
Dal server UDT |
Dal server non UDT |
|---|---|---|---|---|
| DBTYPE_UDT | Supportato6 | Errore1 | Supportato6 | Errore5 |
| DBTYPE_BYTES | Supportato6 | N/D2 | Supportato6 | N/D2 |
| DBTYPE_WSTR | Supportato3,6 | N/D2 | Supportato4,6 | N/D2 |
| DBTYPE_BSTR | Supportato3,6 | N/D2 | Supportato4 | N/D2 |
| DBTYPE_STR | Supportato3,6 | N/D2 | Supportato4,6 | N/D2 |
| DBTYPE_IUNKNOWN | Non supportato | N/D2 | Non supportato | N/D2 |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Supportato6 | N/D2 | Supportato4 | N/D2 |
| DBTYPE_VARIANT (VT_BSTR) | Supportato3,6 | N/D2 | N/D | N/D2 |
1Se viene specificato un tipo di server diverso da DBTYPE_UDT con ICommandWithParameters::SetParameterInfo e il tipo di funzione di accesso è DBTYPE_UDT, si verifica un errore quando viene eseguita l'istruzione (DB_E_ERRORSOCCURRED; lo stato del parametro è DBSTATUS_E_BADACCESSOR). In caso contrario, i dati vengono inviati al server, ma il server restituisce un errore indicando che non è possibile eseguire una conversione implicita dal tipo definito dall'utente al tipo di dati del parametro.
2Oltre l'ambito di questo argomento.
3Si verifica la conversione dei dati da stringa esadecimale a dati binari.
4Si verifica la conversione dei dati da dati binari a stringa esadecimale.
5La convalida può verificarsi durante la creazione della funzione di accesso o durante il recupero, l'errore è DB_E_ERRORSOCCURRED, lo stato dell'associazione impostato su DBBINDSTATUS_UNSUPPORTEDCONVERSION.
6Può essere usato BY_REF.
DBTYPE_NULL e DBTYPE_EMPTY possono essere associati per i parametri di input ma non per i parametri di output o per i risultati. Se vengono associati per i parametri di input, lo stato deve essere impostato su DBSTATUS_S_ISNULL o DBSTATUS_S_DEFAULT.
DBTYPE_UDT può essere convertito anche in DBTYPE_EMPTY e DBTYPE_NULL, ma DBTYPE_NULL e DBTYPE_EMPTY non possono essere convertiti in DBTYPE_UDT. È coerente con DBTYPE_BYTES.
Nota
Viene usata una nuova interfaccia per la gestione dei tipi definiti dall'utente come parametri, ISSCommandWithParameters, che eredita da ICommandWithParameters. Le applicazioni devono utilizzare questa interfaccia per impostare almeno SSPROP_PARAM_UDT_NAME del set di proprietà DBPROPSET_SQLSERVERPARAMETER per i parametri UDT. In caso contrario, ICommand::Execute restituirà DB_E_ERRORSOCCURRED. Questo set di proprietà e questa interfaccia vengono descritti più avanti in questo argomento.
Se un tipo definito dall'utente viene inserito in una colonna che non consente di contenere tutti i relativi dati, ICommand::Execute restituirà S_OK con lo stato DB_E_ERRORSOCCURRED.
Le conversioni dei dati fornite dai servizi principali OLE DB (IDataConvert) non sono applicabili a DBTYPE_UDT. Non sono supportate altre associazioni.
Aggiunte e modifiche ai set di righe OLE DB
SQL Server Native Client aggiunge nuovi valori o modifiche a molti set di righe dello schema OLE DB di base.
Set di righe dello schema PROCEDURE_PARAMETERS
Al set di righe dello schema PROCEDURE_PARAMETERS sono state effettuate le seguenti aggiunte.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Identificatore del nome in tre parti. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Identificatore del nome in tre parti. |
| SS_UDT_NAME | DBTYPE_WSTR | Identificatore del nome in tre parti. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nome completo dell'assembly che include il nome del tipo e l'identificazione dell'assembly necessaria a cui deve fare riferimento CLR. |
Set di righe dello schema SQL_ASSEMBLIES
Il provider OLE DB di SQL Server Native Client espone un nuovo set di righe dello schema specifico del provider che descrive i tipi definiti dall'utente registrati. Il server ASSEMBLY può essere specificato come DBTYPE_WSTR, ma non è presente nel set di righe. Se non viene specificato, il set di righe imposterà come valore predefinito il server corrente. Il set di righe dello schema SQL_ASSEMBLIES viene definito nella tabella seguente.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nome del catalogo dell'assembly contenente il tipo. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nome dello schema o nome del proprietario dell'assembly contenente il tipo. Sebbene l'ambito degli assembly sia il database e non lo schema, gli assembly dispongono di un proprietario qui rappresentato. |
| ASSEMBLY_NAME | DBTYPE_WSTR | Nome dell'assembly contenente il tipo. |
| ASSEMBLY_ID | DBTYPE_UI4 | ID oggetto dell'assembly contenente il tipo. |
| PERMISSION_SET | DBTYPE_WSTR | Valore che indica l'ambito di accesso per l'assembly. I valori includono "SAFE", "EXTERNAL_ACCESS" e "UNSAFE". |
| ASSEMBLY_BINARY | DBTYPE_BYTES | Rappresentazione binaria dell'assembly. |
Set di righe dello schema SQL_ASSEMBLIES_ DEPENDENCIES
Il provider OLE DB di SQL Server Native Client espone un nuovo set di righe dello schema specifico del provider che descrive le dipendenze dell'assembly per un server specificato. ASSEMBLY_SERVER può essere specificato dal chiamante come DBTYPE_WSTR, ma non è presente nel set di righe. Se non viene specificato, il set di righe imposterà come valore predefinito il server corrente. Il set di righe dello schema SQL_ASSEMBLY_DEPENDENCIES viene definito nella tabella seguente.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nome del catalogo dell'assembly contenente il tipo. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nome dello schema o nome del proprietario dell'assembly contenente il tipo. Sebbene l'ambito degli assembly sia il database e non lo schema, gli assembly dispongono di un proprietario qui rappresentato. |
| ASSEMBLY_ID | DBTYPE_UI4 | ID oggetto dell'assembly. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | ID oggetto dell'assembly a cui viene fatto riferimento. |
Set di righe dello schema SQL_USER_TYPES
Il provider OLE DB di SQL Server Native Client espone un nuovo set di righe dello schema, SQL_USER_TYPES, che descrive quando vengono aggiunti i tipi definiti dall'utente registrati per un server specificato. UDT_SERVER deve essere specificato dal chiamante come DBTYPE_WSTR, ma non è presente nel set di righe. Il set di righe dello schema SQL_USER_TYPES viene definito nella tabella seguente.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | Per le colonne con tipo definito dall'utente questa proprietà è una stringa che specifica il nome del catalogo in cui viene definito il tipo definito dall'utente. |
| UDT_SCHEMANAME | DBTYPE_WSTR | Per le colonne con tipo definito dall'utente questa proprietà è una stringa che specifica il nome dello schema in cui viene definito il tipo definito dall'utente. |
| UDT_NAME | DBTYPE_WSTR | Nome dell'assembly contenente la classe UDT. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Il nome completo del tipo (AQN) include il nome del tipo preceduto dallo spazio dei nomi se applicabile. |
Set di righe dello schema COLUMNS
Le aggiunte al set di righe dello schema COLUMNS includono le colonne seguenti.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Per le colonne con tipo definito dall'utente questa proprietà è una stringa che specifica il nome del catalogo in cui viene definito il tipo definito dall'utente. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Per le colonne con tipo definito dall'utente questa proprietà è una stringa che specifica il nome dello schema in cui viene definito il tipo definito dall'utente. |
| SS_UDT_NAME | DBTYPE_WSTR | Nome del tipo definito dall'utente. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Il nome completo del tipo (AQN) include il nome del tipo preceduto dallo spazio dei nomi se applicabile. |
Aggiunte e modifiche ai set di proprietà OLE DB
SQL Server Native Client aggiunge nuovi valori o modifiche a molti dei set di proprietà OLE DB principali.
Set di proprietà DBPROPSET_SQLSERVERPARAMETER
Per supportare i tipi definiti dall'utente tramite OLE DB, SQL Server Native Client implementa il nuovo set di proprietà DBPROPSET_SQLSERVERPARAMETER che contiene i valori seguenti.
| Nome | Tipo | Descrizione |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | Identificatore del nome in tre parti. Per i parametri UDT questa proprietà è una stringa che specifica il nome del catalogo in cui viene definito il tipo definito dall'utente. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | Identificatore del nome in tre parti. Per i parametri UDT questa proprietà è una stringa che specifica il nome dello schema in cui viene definito il tipo definito dall'utente. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | Identificatore del nome in tre parti. Per le colonne con tipo definito dall'utente questa proprietà è una stringa che specifica il nome costituito da una sola parte del tipo definito dall'utente. |
SSPROP_PARAM_UDT_NAME è obbligatorio. SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME sono facoltativi. Se una delle proprietà viene specificata in modo non corretto, verrà restituito DB_E_ERRORSINCOMMAND. Se non vengono specificati SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME, il tipo definito dall'utente dovrà essere definito nello stesso database e nello stesso schema della tabella. Se la definizione UDT non è presente nello stesso schema della tabella, ma nello stesso database, sarà necessario specificare SSPROP_PARAM_UDT_SCHEMANAME. Se la definizione UDT è presente in un database diverso, sarà necessario specificare SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME.
Set di proprietà DBPROPSET_SQLSERVERCOLUMN
Per supportare la creazione di tabelle nell'interfaccia ITableDefinition , SQL Server Native Client aggiunge le tre nuove colonne seguenti al set di proprietà DBPROPSET_SQLSERVERCOLUMN.
| Nome | Descrizione | Tipo | Descrizione |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | Per le colonne di tipo DBTYPE_UDT questa proprietà è una stringa che specifica il nome del catalogo in cui viene definito il tipo definito dall'utente. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | Per le colonne di tipo DBTYPE_UDT questa proprietà è una stringa che specifica il nome dello schema in cui viene definito il tipo definito dall'utente. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | Per le colonne di tipo DBTYPE_UDT questa proprietà è una stringa che specifica il nome costituito da una singola parte del tipo definito dall'utente. Per gli altri tipi di colonna questa proprietà restituisce una stringa vuota. |
Nota
I tipi definiti dall'utente non sono presenti nel set di righe dello schema PROVIDER_TYPES. Tutte le colonne dispongono dell'accesso in lettura e scrittura.
ADO farà riferimento a queste proprietà tramite la voce corrispondente nella colonna Descrizione.
SSPROP_COL_UDTNAME è obbligatorio. SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME sono facoltativi. Se una delle proprietà viene specificata in modo non corretto, verrà restituito DB_E_ERRORSINCOMMAND.
Se non vengono specificati SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME, il tipo definito dall'utente dovrà essere definito nello stesso database e nello stesso schema della tabella.
Se la definizione UDT non è presente nello stesso schema della tabella, ma nello stesso database, sarà necessario specificare SSPROP_COL_UDT_SCHEMANAME.
Se la definizione UDT è presente in un database diverso, sarà necessario specificare SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME.
Aggiunte e modifiche alle interfacce OLE DB
SQL Server Native Client aggiunge nuovi valori o modifiche a molte delle interfacce OLE DB principali.
Interfaccia ISSCommandWithParameters
Per supportare i tipi definiti dall'utente tramite OLE DB, SQL Server Native Client implementa una serie di modifiche, inclusa l'aggiunta dell'interfaccia ISSCommandWithParameters . Questa nuova interfaccia eredita dall'interfaccia OLE DB principale ICommandWithParameters. Oltre ai tre metodi ereditati da ICommandWithParameters; GetParameterInfo, MapParameterNames e SetParameterInfo; ISSCommandWithParameters fornisce i metodi GetParameterProperties e SetParameterProperties usati per gestire tipi di dati specifici del server.
Nota
L'interfaccia ISSCommandWithParameters usa anche la nuova struttura SSPARAMPROPS.
Interfaccia IColumnsRowset
Oltre all'interfaccia ISSCommandWithParameters , SQL Server Native Client aggiunge anche nuovi valori al set di righe restituito dalla chiamata al metodo IColumnsRowset::GetColumnRowset , incluso quanto segue.
| Nome colonna | Tipo | Descrizione |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | Identificatore del nome di catalogo del tipo definito dall'utente. |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | Identificatore del nome dello schema del tipo definito dall'utente. |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | Identificatore del nome del tipo definito dall'utente. |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nome completo dell'assembly che include il nome del tipo e l'identificazione dell'assembly necessaria a cui deve fare riferimento CLR. |
È possibile differenziare una colonna con tipo definito dall'utente del server dagli altri tipi binari quando DBCOLUMN_TYPE è impostato su DBTYPE_UDT analizzando i metadati UDT aggiunti sopra specificati. Se tali dati sono parzialmente completi, il tipo di server sarà un tipo definito dall'utente. Per i tipi di server non UDT queste colonne vengono sempre restituite come NULL.
Driver ODBC di SQL Server Native Client
Sono state apportate alcune modifiche nel driver ODBC di SQL Server Native Client per supportare i tipi definiti dall'utente. Il driver ODBC di SQL Server Native Client esegue il mapping del tipo di dati SQL Server UDT a SQL_SS_UDT identificatore del tipo di dati SQL specifico del driver. Le colonne con tipo definito dall'utente vengono rilevate come SQL_SS_UDT. Se si esegue il mapping esplicito di una colonna UDT a un altro tipo in un'istruzione SQL utilizzando i metodi ToString o ToXMLString del tipo definito dall'utente o tramite la funzione CAST/CONVERT , il tipo della colonna nel set di risultati riflette il tipo effettivo in cui è stata convertita la colonna
SQLColAttribute, SQLDescribeParam, SQLGetDescField
Sono stati aggiunti quattro nuovi campi descrittori specifici del driver per fornire informazioni aggiuntive per una colonna UDT di un set di risultati o un parametro definito dall'utente della stored procedure/query con parametri, da recuperare tramite le funzioni SQLColAttribute, SQLDescribeParam e SQLGetDescField .
I quattro nuovi campi di descrizione aggiunti sono 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
Inoltre, vengono aggiunte tre nuove colonne specifiche del driver al set di risultati restituito dalle funzioni SQLColumns e SQLProcedureColumns per fornire informazioni aggiuntive su una colonna del set di risultati definito dall'utente o un parametro definito dall'utente. Queste tre nuove colonne sono SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME e SS_UDT_ASSEMBLY_TYPE_NAME.
Conversioni supportate
Quando si esegue la conversione dai tipi di dati SQL ai tipi di dati C, SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR possono essere convertiti tutti in SQL_SS_UDT. Tenere tuttavia presente che i dati binari vengono convertiti in una stringa esadecimale durante la conversione dai tipi di dati SQL SQL_C_WCHAR e SQL_C_CHAR.
Quando si esegue la conversione dai tipi di dati C ai tipi di dati SQL, SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR possono essere convertiti tutti in SQL_SS_UDT. Tenere tuttavia presente che i dati binari vengono convertiti in una stringa esadecimale durante la conversione dai tipi di dati SQL SQL_C_WCHAR e SQL_C_CHAR.
Vedi anche
Funzionalità di SQL Server Native Client
ISSCommandWithParameters (OLE DB)