Utilisation de types définis par l’utilisateur dans SQL Server Native Client
S’applique à : 
SQL Server Azure SQL Database 
Azure Synapse Analytics Analytics Platform System (PDW)
Important
SQL Server Native Client (SNAC) n’est pas fourni avec :
- 2022 - SQL Server 16 (16.x) et versions ultérieures
- SQL Server Management Studio 19 et versions ultérieures
SQL Server Native Client (SQLNCLI ou SQLNCLI11) et le fournisseur Microsoft OLE DB hérité pour SQL Server (SQLOLEDB) ne sont pas recommandés pour le nouveau développement d’applications.
Pour les nouveaux projets, utilisez l'un des pilotes suivants :
Pour SQLNCLI qui est fourni en tant que composant du moteur de base de données SQL Server (versions 2012 à 2019), consultez cette exception du cycle de vie du support.
Les types définis par l'utilisateur (UDT) ont été introduits dans SQL Server 2005 (9.x). Ils étendent le système de types SQL en vous permettant de stocker des objets et des structures de données personnalisées dans une base de données SQL Server. Les UDT peuvent contenir plusieurs types de données et avoir des comportements, ce qui les différencie des types de données d'alias traditionnels qui ne comportent qu'un seul type de données système SQL Server. Les UDT sont définis à l'aide de n'importe quel langage pris en charge par le CLR (Common Language Runtime) .NET capable de produire du code vérifiable, Cela inclut C# et Visual Basic .NET. Les données sont exposées en tant que champs et propriétés d'une classe ou d'une structure .NET, et les comportements sont définis par des méthodes de la classe ou de la structure.
Un type UDT peut être utilisé comme définition de colonne d’une table, comme variable dans un lot Transact-SQL ou comme argument d’une fonction ou d’une procédure stockée Transact-SQL.
Fournisseur OLE DB SQL Server Native Client
Le fournisseur OLE DB SQL Server Native Client prend en charge les UDT en tant que types binaires avec des informations de métadonnées, ce qui vous permet de gérer les UDT en tant qu’objets. Les colonnes UDT sont exposées comme DBTYPE_UDT, et leurs métadonnées sont exposées via l’interface OLE DB IColumnRowset principale et la nouvelle interface ISSCommandWithParameters.
Notes
La méthode IRowsetFind::FindNextRow ne fonctionne pas avec le type de données UDT. DB_E_BADCOMPAREOP est retourné si l'UDT est utilisé comme type de colonne de recherche.
Liaisons de données et forçages de type
Le tableau suivant décrit la liaison et le forçage de type survenant lorsque vous utilisez les types de données répertoriés avec un UDT SQL Server. Les colonnes UDT sont exposées via le fournisseur OLE DB SQL Server Native Client en tant que DBTYPE_UDT. Vous pouvez obtenir les métadonnées par le biais des ensembles de lignes de schéma appropriés et ainsi gérer en tant qu'objets vos propres types définis.
| Type de données | Vers le serveur UDT |
Vers le serveur Non-UDT |
Depuis le serveur UDT |
Depuis le serveur Non-UDT |
|---|---|---|---|---|
| DBTYPE_UDT | Pris en charge6 | Erreur1 | Pris en charge6 | Erreur5 |
| DBTYPE_BYTES | Pris en charge6 | N/A2 | Pris en charge6 | N/A2 |
| DBTYPE_WSTR | Pris en charge3,6 | N/A2 | Pris en charge4.6 | N/A2 |
| DBTYPE_BSTR | Pris en charge3,6 | N/A2 | Pris en charge4 | N/A2 |
| DBTYPE_STR | Pris en charge3,6 | N/A2 | Pris en charge4.6 | N/A2 |
| DBTYPE_IUNKNOWN | Non pris en charge | N/A2 | Non pris en charge | N/A2 |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Pris en charge6 | N/A2 | Pris en charge4 | N/A2 |
| DBTYPE_VARIANT (VT_BSTR) | Pris en charge3,6 | N/A2 | N/A | N/A2 |
1Si un type de serveur autre que DBTYPE_UDT est spécifié avec ICommandWithParameters::SetParameterInfo et si le type d’accesseur est DBTYPE_UDT, une erreur se produit lors de l’exécution de l’instruction (DB_E_ERRORSOCCURRED, l’état du paramètre est DBSTATUS_E_BADACCESSOR). Sinon, les données sont envoyées au serveur, mais le serveur retourne une erreur indiquant qu'il n'existe pas de conversion implicite entre l'UDT et le type de données du paramètre.
2Au-delà de la portée de cette rubrique.
3 La conversion de données d’une chaîne hexadécimale en données binaires est réalisée.
4 La conversion de données binaires en chaîne hexadécimale est réalisée.
5La validation peut avoir lieu au moment de créer l’accesseur ou au moment de l’extraction, l’erreur est DB_E_ERRORSOCCURRED ; l’état de la liaison est défini sur DBBINDSTATUS_UNSUPPORTEDCONVERSION.
6BY_REF peut être utilisé.
Les types DBTYPE_NULL et DBTYPE_EMPTY peuvent être liés pour des paramètres d'entrée mais pas pour des paramètres de résultats ou pour des sorties. S’ils sont liés pour des paramètres d’entrée, l’état doit être défini sur DBSTATUS_S_ISNULL ou DBSTATUS_S_DEFAULT.
DBTYPE_UDT peut également être converti en DBTYPE_EMPTY et DBTYPE_NULL, mais DBTYPE_NULL et DBTYPE_EMPTY ne peuvent pas être convertis en DBTYPE_UDT, ce qui est cohérent avec DBTYPE_BYTES.
Notes
Une nouvelle interface est utilisée pour traiter les UDT comme paramètres, ISSCommandWithParameters, qui hérite d’ICommandWithParameters. Les applications doivent utiliser cette interface pour définir au moins le SSPROP_PARAM_UDT_NAME de la propriété DBPROPSET_SQLSERVERPARAMETER définie pour les paramètres UDT. Si cela n’est pas fait, ICommand::Execute retourne DB_E_ERRORSOCCURRED. Ce jeu d'interface et de propriété est décrit plus loin dans cette rubrique.
Si un type défini par l’utilisateur est inséré dans une colonne qui n’est pas assez grande pour contenir toutes ses données, ICommand::Execute retourne S_OK avec l’état DB_E_ERRORSOCCURRED.
Les conversions de données fournies par les services principaux d’OLE DB (IDataConvert) ne s’appliquent pas à DBTYPE_UDT. Aucune autre liaison n'est prise en charge.
Ajout et modifications dans les ensembles de lignes OLE DB
SQL Server Native Client ajoute de nouvelles valeurs ou modifications à de nombreux ensembles de lignes de schéma OLE DB principaux.
Ensemble de lignes de schéma PROCEDURE_PARAMETERS
Les ajouts suivants ont été effectués dans l'ensemble de lignes de schéma PROCEDURE_PARAMETERS.
| Nom de la colonne | Type | Description |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Identificateur de nom en trois parties. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Identificateur de nom en trois parties. |
| SS_UDT_NAME | DBTYPE_WSTR | Identificateur de nom en trois parties. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Le nom complet d'assembly qui inclut le nom du type et toutes les identification d'assembly nécessaires pour être référencés par le CLR. |
Ensemble de lignes de schéma SQL_ASSEMBLIES
Le fournisseur OLE DB SQL Server Native Client expose un nouvel ensemble de lignes de schéma spécifique au fournisseur qui décrit les UDT inscrits. Le serveur ASSEMBLY peut être spécifié en tant que DBTYPE_WSTR, mais n'est pas présent dans l'ensemble de lignes. S'il n'est pas spécifié, l'ensemble de lignes aura comme valeur par défaut le serveur actuel. L'ensemble de lignes de schéma SQL_ASSEMBLIES est défini dans le tableau suivant.
| Nom de la colonne | Type | Description |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nom de catalogue de l'assembly qui contient le type. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nom de schéma ou de propriétaire de l'assembly qui contient le type. Bien que les assemblys aient une portée définie par base de données et non par schéma, ils conservent un propriétaire qui est indiqué ici. |
| ASSEMBLY_NAME | DBTYPE_WSTR | Nom de l'assembly qui contient le type. |
| ASSEMBLY_ID | DBTYPE_UI4 | ID d'objet de l'assembly qui contient le type. |
| PERMISSION_SET | DBTYPE_WSTR | Valeur qui indique la portée d'accès de l'assembly. Les valeurs incluent SAFE, EXTERNAL_ACCESS et UNSAFE. |
| ASSEMBLY_BINARY | DBTYPE_BYTES | Représentation binaire de l'assembly. |
Ensemble de lignes de schéma SQL_ASSEMBLIES_ DEPENDENCIES
Le fournisseur OLE DB SQL Server Native Client expose un nouvel ensemble de lignes de schéma spécifique au fournisseur qui décrit les dépendances d’assembly pour un serveur spécifié. ASSEMBLY_SERVER peut être spécifié par l'appelant en tant que DBTYPE_WSTR, mais n'est pas présent dans l'ensemble de lignes. S'il n'est pas spécifié, l'ensemble de lignes aura comme valeur par défaut le serveur actuel. L'ensemble de lignes de schéma SQL_ASSEMBLY_DEPENDENCIES est défini dans le tableau suivant.
| Nom de la colonne | Type | Description |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nom de catalogue de l'assembly qui contient le type. |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nom de schéma ou de propriétaire de l'assembly qui contient le type. Bien que les assemblys aient une portée définie par base de données et non par schéma, ils conservent un propriétaire qui est indiqué ici. |
| ASSEMBLY_ID | DBTYPE_UI4 | ID d'objet de l'assembly. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | ID d'objet de l'assembly référencé. |
Ensemble de lignes de schéma SQL_USER_TYPES
Le fournisseur OLE DB SQL Server Native Client expose un nouvel ensemble de lignes de schéma, SQL_USER_TYPES, qui décrit quand les UDT inscrits pour un serveur spécifié sont ajoutés. UDT_SERVER doit être spécifié en tant que DBTYPE_WSTR par l'appelant, mais n'est pas présent dans l'ensemble de lignes. L'ensemble de lignes de schéma SQL_USER_TYPES est défini dans le tableau suivant.
| Nom de la colonne | Type | Description |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | Pour les colonnes UDT, cette propriété est une chaîne qui spécifie le nom du catalogue dans lequel le schéma UDT est défini. |
| UDT_SCHEMANAME | DBTYPE_WSTR | Pour les colonnes UDT, cette propriété est une chaîne qui spécifie le nom du schéma dans lequel le schéma UDT est défini. |
| UDT_NAME | DBTYPE_WSTR | Nom de l'assembly contenant la classe UDT. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Le nom de type complet (AQN) inclut le nom de type précédé, le cas échéant, de l'espace de noms. |
Ensemble de lignes de schéma COLUMNS
Les colonnes suivantes ont été ajoutées à l'ensemble de lignes de schéma COLUMNS.
| Nom de la colonne | Type | Description |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Pour les colonnes UDT, cette propriété est une chaîne qui spécifie le nom du catalogue dans lequel le schéma UDT est défini. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Pour les colonnes UDT, cette propriété est une chaîne qui spécifie le nom du schéma dans lequel le schéma UDT est défini. |
| SS_UDT_NAME | DBTYPE_WSTR | Nom du type défini par l'utilisateur (UDT). |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Le nom de type complet (AQN) inclut le nom de type précédé, le cas échéant, de l'espace de noms. |
Ajouts et modifications effectués dans le jeu de propriétés OLE DB
SQL Server Native Client ajoute de nouvelles valeurs ou modifications à de nombreux ensembles de propriétés OLE DB principaux.
Jeu de propriétés DBPROPSET_SQLSERVERPARAMETER
Pour prendre en charge les UDT via OLE DB, SQL Server Native Client implémente le nouveau jeu de propriétés DBPROPSET_SQLSERVERPARAMETER qui contient les valeurs suivantes.
| Nom | Type | Description |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | Identificateur de nom en trois parties. Pour les paramètres UDT, cette propriété est une chaîne qui spécifie le nom du catalogue dans lequel le type défini par l'utilisateur est défini. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | Identificateur de nom en trois parties. Pour les paramètres UDT, cette propriété est une chaîne qui spécifie le nom du schéma dans lequel le type défini par l'utilisateur est défini. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | Identificateur de nom en trois parties. Pour les colonnes UDT, cette propriété est une chaîne qui spécifie le nom en une partie du type défini par l'utilisateur. |
SSPROP_PARAM_UDT_NAME est obligatoire. SSPROP_PARAM_UDT_CATALOGNAME et SSPROP_PARAM_UDT_SCHEMANAME sont facultatifs. Si l'une des propriétés est spécifiée de manière incorrecte, DB_E_ERRORSINCOMMAND est retourné. Si SSPROP_PARAM_UDT_CATALOGNAME et SSPROP_PARAM_UDT_SCHEMANAME ne sont pas spécifiés, le type défini par l'utilisateur (UDT) doit être défini dans la même base de données et dans le même schéma que la table. Si la définition du type défini par l'utilisateur ne se trouve pas dans le même schéma que la table (mais dans la même base de données), SSPROP_PARAM_UDT_SCHEMANAME doit être spécifié. Si la définition du type défini par l'utilisateur se trouve dans une base de données différente, SSPROP_PARAM_UDT_CATALOGNAME et SSPROP_PARAM_UDT_SCHEMANAME doivent être spécifiés.
Jeu de propriétés DBPROPSET_SQLSERVERCOLUMN
Pour prendre en charge la création de tables dans l’interface ITableDefinition , SQL Server Native Client ajoute les trois nouvelles colonnes suivantes au jeu de propriétés DBPROPSET_SQLSERVERCOLUMN.
| Nom | Description | Type | Description |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | Pour les colonnes de type DBTYPE_UDT, cette propriété est une chaîne qui spécifie le nom du catalogue dans lequel le type défini par l'utilisateur (UDT) est défini. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | Pour les colonnes de type DBTYPE_UDT, cette propriété est une chaîne qui spécifie le nom du schéma dans lequel le type défini par l'utilisateur (UDT) est défini. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | Pour les colonnes de type DBTYPE_UDT, cette propriété est une chaîne qui spécifie le nom en une partie du type défini par l'utilisateur (UDT). Pour les autres types de colonnes, cette propriété retourne une chaîne vide. |
Notes
Les types définis par l'utilisateur (UDT) n'apparaissent pas dans l'ensemble de lignes de schéma PROVIDER_TYPES. Toutes les colonnes ont un accès en lecture et écriture.
ADO fait référence à ces propriétés en utilisant l'entrée correspondante dans la colonne Description.
SSPROP_COL_UDTNAME est obligatoire. SSPROP_COL_UDT_CATALOGNAME et SSPROP_COL_UDT_SCHEMANAME sont facultatifs. Si l’une des propriétés est spécifiée de manière incorrecte, DB_E_ERRORSINCOMMAND est retourné.
Si ni SSPROP_COL_UDT_CATALOGNAME ni SSPROP_COL_UDT_SCHEMANAME n'est spécifié, le type défini par l'utilisateur (UDT) doit être défini dans la même base de données et dans le même schéma que la table.
Si la définition du type défini par l'utilisateur (UDT) ne se trouve pas dans le même schéma que la table (mais dans la même base de données), SSPROP_COL_UDT_SCHEMANAME doit être spécifié.
Si la définition du type défini par l'utilisateur (UDT) se trouve dans une base de données différente, SSPROP_COL_UDT_CATALOGNAME et SSPROP_COL_UDT_SCHEMANAME doivent être spécifiés.
Ajout et modifications dans l'interface OLE DB
SQL Server Native Client ajoute de nouvelles valeurs ou modifications à de nombreuses interfaces OLE DB principales.
Interface ISSCommandWithParameters
Pour prendre en charge les UDT via OLE DB, SQL Server Native Client implémente un certain nombre de modifications, notamment l’ajout de l’interface ISSCommandWithParameters . Cette nouvelle interface hérite de l’interface OLE DB ICommandWithParameters principale. En plus des trois méthodes héritées de ICommandWithParameters ; GetParameterInfo, MapParameterNames et SetParameterInfo ; ISSCommandWithParameters fournit les méthodes GetParameterProperties et SetParameterProperties utilisées pour gérer des types de données spécifiques au serveur.
Remarque
L’interface ISSCommandWithParameters exploite également la nouvelle structure SSPARAMPROPS.
Interface IColumnsRowset
Outre l’interface ISSCommandWithParameters , SQL Server Native Client ajoute également de nouvelles valeurs à l’ensemble de lignes retourné à partir de l’appel de la méthode IColumnsRowset ::GetColumnRowset , y compris les éléments suivants.
| Nom de la colonne | Type | Description |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | Identificateur du nom de catalogue d'un type défini par l'utilisateur (UDT). |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | Identificateur du nom de schéma d'un type défini par l'utilisateur (UDT). |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | Identificateur du nom d'un type défini par l'utilisateur (UDT). |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nom complet de l'assembly, incluant le nom du type et toutes les informations d'identification de l'assembly nécessaires pour qu'il soit référencé par le CLR. |
Vous pouvez différencier une colonne UDT de serveur d'autres types binaires lorsque DBCOLUMN_TYPE est défini sur DBTYPE_UDT en consultant les métadonnées UDT ajoutées spécifiées ci-dessus. Si ces données sont partiellement complètes, le type de serveur est un type défini par l'utilisateur (UDT). Pour les types serveur autres que des types définis par l'utilisateur (UDT), ces colonnes sont toujours retournées comme NULL.
Pilote ODBC SQL Server Native Client
Plusieurs modifications ont été apportées dans le pilote ODBC SQL Server Native Client pour prendre en charge les UDT. Le pilote ODBC SQL Server Native Client mappe l’UDT SQL Server à SQL_SS_UDT identificateur de type de données SQL spécifique au pilote. Les colonnes UDT sont signalées en tant que SQL_SS_UDT. Si vous mappez explicitement une colonne UDT à un autre type dans une instruction SQL à l’aide des méthodes ToString ou ToXMLString de l’UDT ou via la fonction CAST/CONVERT, le type de la colonne dans le jeu de résultats reflète le type réel dans lequel la colonne a été convertie en
SQLColAttribute, SQLDescribeParam, SQLGetDescField
Quatre nouveaux champs de descripteur spécifiques au pilote ont été ajoutés pour fournir des informations supplémentaires pour une colonne UDT d’un jeu de résultats ou un paramètre UDT de procédure stockée/requête paramétrable, à récupérer via les fonctions SQLColAttribute, SQLDescribeParam et SQLGetDescField .
Les quatre nouveaux champs de descripteur ajoutés sont SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME et SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.
SQLColumns, SQLProcedureColumns
En outre, trois nouvelles colonnes spécifiques au pilote sont ajoutées au jeu de résultats retourné par les fonctions SQLColumns et SQLProcedureColumns pour fournir des informations supplémentaires sur une colonne de jeu de résultats UDT ou un paramètre UDT. Ces trois nouvelles colonnes sont SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME et SS_UDT_ASSEMBLY_TYPE_NAME.
Conversions prises en charge
Lorsque vous procédez à des conversions entre des types de données SQL vers C, SQL_C_WCHAR, SQL_C_BINARY et SQL_C_CHAR peuvent tous être convertis en SQL_SS_XML. Notez toutefois que les données binaires sont converties en chaîne hexadécimale lors de la conversion depuis les types de données SQL SQL_C_WCHAR et SQL_C_CHAR.
Lorsque vous procédez à des conversions entre des types de données C vers SQL, SQL_C_WCHAR, SQL_C_BINARY et SQL_C_CHAR peuvent tous être convertis en SQL_SS_UDT. Notez toutefois que les données binaires sont converties en chaîne hexadécimal lors de la conversion à partir de la SQL_C_WCHAR et SQL_C_CHAR types de données SQL.
Voir aussi
Fonctionnalités de SQL Server Native Client
ISSCommandWithParameters (OLE DB)