Utilisation des types définis par l'utilisateur
Les types définis par l'utilisateur (UDT) ont été introduits dans SQL Server 2005. 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 Microsoft Visual 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 UDT peut être utilisé en tant que définition de colonne d'une table, en tant que variable dans un lot Transact-SQL ou en tant qu'argument d'une fonction ou d'une procédure stockée Transact-SQL. Pour plus d'informations sur les UDT, consultez Utilisation de types CLR définis par l'utilisateur.
Fournisseur OLE DB de SQL Server Native Client
Le fournisseur OLE DB de 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.
[!REMARQUE]
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 de SQL Server Native Client sous la forme 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 |
Non applicable2 |
Pris en charge6 |
Non applicable2 |
DBTYPE_WSTR |
Pris en charge3,6 |
Non applicable2 |
Pris en charge4,6 |
Non applicable2 |
DBTYPE_BSTR |
Pris en charge3,6 |
Non applicable2 |
Pris en charge4 |
Non applicable2 |
DBTYPE_STR |
Pris en charge3,6 |
Non applicable2 |
Pris en charge4,6 |
Non applicable2 |
DBTYPE_IUNKNOWN |
Non pris en charge |
Non applicable2 |
Non pris en charge |
Non applicable2 |
DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) |
Pris en charge6 |
Non applicable2 |
Pris en charge4 |
Non applicable2 |
DBTYPE_VARIANT (VT_BSTR) |
Pris en charge3,6 |
Non applicable2 |
N/A |
Non applicable2 |
1Si un type serveur autre que DBTYPE_UDT est spécifié avec ICommandWithParameters::SetParameterInfo et si le type d'accesseur est DBTYPE_UDT, une erreur se produit lorsque l'instruction est exécutée (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.
2Non traité dans cette rubrique.
3La conversion d'une chaîne hexadécimale en données binaire est réalisée.
4La conversion de données binaires en chaîne hexadécimale est réalisée.
5La validation peut se produire au moment de la création de l'accesseur, ou au moment de l'extraction ; l'erreur est DB_E_ERRORSOCCURRED ; l'état de 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_XML peut également être converti en DBTYPE_EMPTY et DBTYPE_NULL, mais DBTYPE_NULL et DBTYPE_EMPTY ne peuvent pas être converti en DBTYPE_UDT, ce qui est cohérent avec DBTYPE_BYTES.
[!REMARQUE]
Une nouvelle interface est utilisée pour traiter les UDT comme paramètres, ISSCommandWithParameters, qui hérite de 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 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 apporte des modifications à un grand nombre d'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 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 de SQL Server Native Client expose un nouvel ensemble de lignes de schéma spécifique au fournisseur qui décrit les UDT enregistrés. 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 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 de 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 d'un serveur donné. 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 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 de SQL Server Native Client expose le nouvel ensemble de lignes de schéma, SQL_USER_TYPES, qui décrit quand sont ajoutés les types définis par l'utilisateur (UDT) enregistrés pour un serveur donné. 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 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 où 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 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 apporte des modifications à un grand nombre de jeux de propriétés OLE DB principaux.
Jeu de propriétés DBPROPSET_SQLSERVERPARAMETER
Pour permettre la prise en charge des types définis par l'utilisateur (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 permettre la prise en charge de 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. |
[!REMARQUE]
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 de ces 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 apporte des modifications à un grand nombre des interfaces OLE DB principales.
Interface ISSCommandWithParameters
Pour prendre en charge les types définis par l'utilisateur (UDT) via OLE DB, SQL Server Native Client implémente différentes modifications, notamment l'ajout de l'interface ISSCommandWithParameters. Cette nouvelle interface hérite de l'interface OLE DB ICommandWithParameters principale. Outre les trois méthodes héritées de ICommandWithParameters (GetParameterInfo, MapParameterNames et SetParameterInfo), ISSCommandWithParameters fournit les méthodes GetParameterProperties et SetParameterProperties employées pour la gestion 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é en appelant la méthode IColumnsRowset::GetColumnRowset, notamment les valeurs suivantes.
Nom de 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
Différentes modifications ont été apportées au pilote ODBC SQL Server Native Client pour prendre en charge les types définis par l'utilisateur (UDT). Le pilote ODBC SQL Server Native Client mappe le type défini par l'utilisateur SQL Server à un identificateur de type de données SQL spécifique au pilote, SQL_SS_UDT. Les colonnes UDT sont signalées en tant que SQL_SS_UDT. Si vous mappez une colonne UDT explicitement à un autre type dans une instruction SQL à l'aide des méthodes ToString ou ToXMLString du type défini par l'utilisateur 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.
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 pour un paramètre UDT d'une procédure stockée/requête paramétrable. Ces champs de descripteur sont extraits 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
De plus, 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 sur 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écimale lors de la conversion depuis les types de données SQL SQL_C_WCHAR et SQL_C_CHAR.
Voir aussi