Verwenden von benutzerdefinierten Typen in SQL Server Native Client

  • Artikel

Gilt für: SQL Server Azure SQL-Datenbank Not supported. Azure Synapse Analytics Analytics Platform System (PDW)

Wichtig

Der SQL Server Native Client (häufig abgekürzt mit SNAC) wurde aus SQL Server 2022 (16.x) und SQL Server Management Studio 19 (SSMS) entfernt. Der SQL Server Native Client (SQLNCLI oder SQLNCLI11) und der Microsoft OLE DB-Legacyanbieter für SQL Server (SQLOLEDB) werden für neue Anwendungsentwicklungen nicht empfohlen. Verwenden Sie in Zukunft den neuen Microsoft OLE DB-Treiber für SQL Server (MSOLEDBSQL) oder den neuesten Microsoft ODBC Driver for SQL Server. Informationen zu SQLNCLI, das als Komponente der SQL Server Datenbank-Engine (Versionen 2012 bis 2019) ausgeliefert wird, finden Sie in dieser Ausnahme für den Supportlebenszyklus.

In SQL Server 2005 (9.x) wurden benutzerdefinierte Typen (User-Defined Types, UDTs) eingeführt. UDTs erweitern das SQL-Typsystem, indem sie es ermöglichen, Objekte und benutzerdefinierte Datenstrukturen in einer SQL Server-Datenbank zu speichern. UDTs können mehrere Datentypen enthalten und Verhalten zeigen, das sie von den herkömmlichen Aliasdatentypen aus einem einzelnen SQL Server-Systemdatentyp unterscheidet. UDTs werden in einer beliebigen, von .NET CLR (Common Language Runtime) unterstützten Sprache definiert, die überprüfbaren Code generiert. Dazu gehören C# und Visual Basic .NET. Die Daten werden in Feldern und Eigenschaften einer .NET-Klasse oder -Struktur verfügbar gemacht. Das Verhalten wird durch die Methoden der Klasse oder Struktur definiert.

Ein UDT kann als Spaltendefinition einer Tabelle, als Variable in einem Transact-SQL-Batch oder als Argument einer Transact-SQL-Funktion oder gespeicherten Prozedur verwendet werden.

SQL Server Native Client OLE DB-Anbieter

Der OLE DB-Anbieter von SQL Server Native Client unterstützt UDTs als Binäre Typen mit Metadateninformationen, mit denen Sie UDTs als Objekte verwalten können. UDT-Spalten werden als DBTYPE_UDT verfügbar gemacht, und ihre Metadaten werden über die OLE DB-Kernschnittstelle IColumnRowset und die neue ISSCommandWithParameters-Schnittstelle bereitgestellt.

Hinweis

Die IRowsetFind::FindNextRow-Methode funktioniert nicht mit dem UDT-Datentyp. DB_E_BADCOMPAREOP wird zurückgegeben, wenn der UDT als Suchspaltentyp verwendet wird.

Datenbindungen und -umwandlungen

Die folgende Tabelle veranschaulicht die Bindung und Umwandlung bei Verwendung der aufgeführten Datentypen mit einem SQL Server-UDT. UDT-Spalten werden über den OLE DB-Anbieter des SQL Server Native Client als DBTYPE_UDT verfügbar gemacht. Die Metadaten können Sie über die entsprechenden Schemarowsets abrufen und so Ihre benutzerdefinierten Typen als Objekte verwalten.

Datentyp Zu Server

UDT		 Zu Server

non-UDT		 Von Server

UDT		 Von Server

non-UDT
DBTYPE_UDT Unterstützt6 Fehler1 Unterstützt6 Fehler5
DBTYPE_BYTES Unterstützt6 Nicht zutreffend2 Unterstützt6 Nicht zutreffend2
DBTYPE_WSTR Unterstützt3,6 Nicht zutreffend2 Unterstützt4,6 Nicht zutreffend2
DBTYPE_BSTR Unterstützt3,6 Nicht zutreffend2 Unterstützt4 Nicht zutreffend2
DBTYPE_STR Unterstützt3,6 Nicht zutreffend2 Unterstützt4,6 Nicht zutreffend2
DBTYPE_IUNKNOWN Nicht unterstützt Nicht zutreffend2 Nicht unterstützt Nicht zutreffend2
DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) Unterstützt6 Nicht zutreffend2 Unterstützt4 Nicht zutreffend2
DBTYPE_VARIANT (VT_BSTR) Unterstützt3,6 Nicht zutreffend2 – Nicht zutreffend2

1Wird ein anderer Servertyp als DBTYPE_UDT mit ICommandWithParameters::SetParameterInfo angegeben, und ist der Accessortyp DBTYPE_UDT, tritt bei Ausführung der Anweisung ein Fehler auf (DB_E_ERRORSOCCURRED; der Parameterstatus lautet DBSTATUS_E_BADACCESSOR). Andernfalls werden die Daten an den Server gesendet, der Server gibt jedoch einen Fehler zurück und zeigt an, dass keine implizite Umwandlung des UDT in den Parameterdatentyp erfolgt.

2Über den Umfang dieses Themas hinaus.

3Es erfolgt eine Datenkonvertierung einer hexadezimalen Zeichenfolge in Binärdaten.

4Es erfolgt eine Datenkonvertierung von Binärdaten in eine hexadezimale Zeichenfolge.

5Die Überprüfung kann zum Zeitpunkt der Accessorerstellung oder zum Zeitpunkt des Abrufens vorgenommen werden. Der Fehler ist DB_E_ERRORSOCCURRED, der Bindungsstatus ist auf DBBINDSTATUS_UNSUPPORTEDCONVERSION festgelegt.

6BY_REF wird möglicherweise verwendet.

DBTYPE_NULL und DBTYPE_EMPTY können für Eingabeparameter gebunden werden, aber nicht für Ausgabeparameter oder Ergebnisse. Ist der Status für Eingabeparameter gebunden, muss er auf DBSTATUS_S_ISNULL oder DBSTATUS_S_DEFAULT festgelegt werden.

DBTYPE_UDT kann auch in DBTYPE_EMPTY und DBTYPE_NULL umgewandelt werden, DBTYPE_NULL und DBTYPE_EMPTY können jedoch nicht in DBTYPE_UDT umgewandelt werden. Dies stimmt mit DBTYPE_BYTES überein.

Hinweis

Für den Umgang mit UDTs als Parametern wird eine neue Schnittstelle, ISSCommandWithParameters, verwendet, die von ICommandWithParameters erbt. Anwendungen müssen diese Schnittstelle verwenden, um mindestens SSPROP_PARAM_UDT_NAME der DBPROPSET_SQLSERVERPARAMETER-Eigenschaftengruppe für UDT-Parameter festzulegen. Andernfalls gibt ICommand::Execute DB_E_ERRORSOCCURRED zurück. Diese Schnittstelle und Eigenschaftengruppe werden im weiteren Verlauf dieses Themas erläutert.

Wird ein UDT in eine Spalte eingefügt, die nicht groß genug für alle Daten ist, gibt ICommand::Execute S_OK mit dem Status DB_E_ERRORSOCCURRED zurück.

Datenkonvertierungen durch OLE DB-Basisdienste (IDataConvert) sind nicht auf DBTYPE_UDT anwendbar. Es werden keine weiteren Bindungen unterstützt.

Hinzufügungen und Änderungen am OLE DB-Rowset

SQL Server Native Client fügt neue Werte oder Änderungen zu vielen der wichtigsten OLE DB-Schema-Rowsets hinzu.

Das PROCEDURE_PARAMETERS-Schemarowset

Die folgenden Hinzufügungen wurden am PROCEDURE_PARAMETERS-Schemarowset vorgenommen.

Spaltenname type BESCHREIBUNG
SS_UDT_CATALOGNAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.
SS_UDT_SCHEMANAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.
SS_UDT_NAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.
SS_UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR Der qualifizierte Name der Assembly mit dem Typnamen und allen zur CLR-Referenzierung erforderlichen Angaben zur Assembly-ID.

Das SQL_ASSEMBLIES-Schemarowset

Der OLE DB-Anbieter für SQL Server Native Client macht ein neues anbieterspezifisches Schema-Rowset verfügbar, das die registrierten UDTs beschreibt. Der ASSEMBLY-Server wird möglicherweise als DBTYPE_WSTR angegeben, ist aber nicht im Rowset vorhanden. Ohne Angabe wird das Rowset standardmäßig für den aktuellen Server festgelegt. Das SQL_ASSEMBLIES-Schemarowset wird in der folgenden Tabelle definiert.

Spaltenname type BESCHREIBUNG
ASSEMBLY_CATALOG DBTYPE_WSTR Der Katalogname der Assembly, die den Typ enthält.
ASSEMBLY_SCHEMA DBTYPE_WSTR Der Name des Schemas oder der Eigentümername der Assembly, die den Typ enthält. Obwohl der Bereich einer Assembly durch die Datenbank und nicht durch ein Schema definiert wird, hat sie einen Eigentümer, der hier angegeben wird.
ASSEMBLY_NAME DBTYPE_WSTR Der Name der Assembly, die den Typ enthält.
ASSEMBLY_ID DBTYPE_UI4 Die Objekt-ID der Assembly, die den Typ enthält.
PERMISSION_SET DBTYPE_WSTR Ein Wert, der den Zugriffsbereich für die Assembly angibt. Zulässige Werten sind "SAFE", "EXTERNAL_ACCESS" und "UNSAFE".
ASSEMBLY_BINARY DBTYPE_BYTES Die Binärdarstellung der Assembly.

Das SQL_ASSEMBLIES_ DEPENDENCIES-Schemarowset

Der OLE DB-Anbieter von SQL Server Native Client macht ein neues anbieterspezifisches Schema-Rowset verfügbar, das die Assemblyabhängigkeiten für einen angegebenen Server beschreibt. ASSEMBLY_SERVER wird möglicherweise vom Aufrufer als DBTYPE_WSTR angegeben, ist aber nicht im Rowset vorhanden. Ohne Angabe wird das Rowset standardmäßig für den aktuellen Server festgelegt. Das SQL_ASSEMBLY_DEPENDENCIES-Schemarowset wird in der folgenden Tabelle definiert.

Spaltenname type BESCHREIBUNG
ASSEMBLY_CATALOG DBTYPE_WSTR Der Katalogname der Assembly, die den Typ enthält.
ASSEMBLY_SCHEMA DBTYPE_WSTR Der Name des Schemas oder der Eigentümername der Assembly, die den Typ enthält. Obwohl der Bereich einer Assembly durch die Datenbank und nicht durch ein Schema definiert wird, hat sie einen Eigentümer, der hier angegeben wird.
ASSEMBLY_ID DBTYPE_UI4 Die Objekt-ID der Assembly.
REFERENCED_ASSEMBLY_ID DBTYPE_UI4 Die Objekt-ID der referenzierten Assembly.

Das SQL_USER_TYPES-Schemarowset

Der OLE DB-Anbieter von SQL Server Native Client macht ein neues Schema-Rowset, SQL_USER_TYPES verfügbar, das beschreibt, wann die registrierten UDTs für einen angegebenen Server hinzugefügt werden. UDT_SERVER muss vom Aufrufer als DBTYPE_WSTR angegeben werden, ist aber nicht im Rowset vorhanden. Das SQL_USER_TYPES-Schemarowset wird in der folgenden Tabelle definiert.

Spaltenname type BESCHREIBUNG
UDT_CATALOGNAME DBTYPE_WSTR Bei UDT-Spalten ist diese Eigenschaft eine Zeichenfolge, die den Namen des Katalogs angibt, in dem der UDT definiert ist.
UDT_SCHEMANAME DBTYPE_WSTR Bei UDT-Spalten ist diese Eigenschaft eine Zeichenfolge, die den Namen des Schemas angibt, in dem der UDT definiert ist.
UDT_NAME DBTYPE_WSTR Der Name der Assembly, die die UDT-Klasse enthält.
UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR Vollständiger Typname (AQN) einschließlich Typname mit Namespace als Präfix (falls zutreffend).

Das COLUMNS-Schemarowset

Dem COLUMNS-Schemarowset wurden unter anderem die folgenden Spalten hinzugefügt.

Spaltenname type BESCHREIBUNG
SS_UDT_CATALOGNAME DBTYPE_WSTR Bei UDT-Spalten ist diese Eigenschaft eine Zeichenfolge, die den Namen des Katalogs angibt, in dem der UDT definiert ist.
SS_UDT_SCHEMANAME DBTYPE_WSTR Bei UDT-Spalten ist diese Eigenschaft eine Zeichenfolge, die den Namen des Schemas angibt, in dem der UDT definiert ist.
SS_UDT_NAME DBTYPE_WSTR Der Name des UDT.
SS_UDT_ASSEMBLY_TYPENAME DBTYPE_WSTR Vollständiger Typname (AQN) einschließlich Typname mit Namespace als Präfix (falls zutreffend).

Hinzufügungen und Änderungen an der OLE DB-Eigenschaftengruppe

SQL Server Native Client fügt neue Werte oder Änderungen an vielen der wichtigsten OLE DB-Eigenschaftensätze hinzu.

Die DBPROPSET_SQLSERVERPARAMETER-Eigenschaftengruppe

Um UDTs über OLE DB zu unterstützen, implementiert SQL Server Native Client den neuen DBPROPSET_SQLSERVERPARAMETER Eigenschaftensatz, der die folgenden Werte enthält.

Name Typ BESCHREIBUNG
SSPROP_PARAM_UDT_CATALOGNAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.

Bei UDT-Parametern ist diese Eigenschaft eine Zeichenfolge, die den Namen des Katalogs angibt, in dem der UDT definiert ist.
SSPROP_PARAM_UDT_SCHEMANAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.

Bei UDT-Parametern ist diese Eigenschaft eine Zeichenfolge, die den Namen des Schemas angibt, in dem der UDT definiert ist.
SSPROP_PARAM_UDT_NAME DBTYPE_WSTR Der dreiteilige Namensbezeichner.

Bei UDT-Spalten ist diese Eigenschaft eine Zeichenfolge, die den einteiligen Namen des UDT angibt.

SSPROP_PARAM_UDT_NAME ist erforderlich. SSPROP_PARAM_UDT_CATALOGNAME und SSPROP_PARAM_UDT_SCHEMANAME sind optional. Wenn Eigenschaften falsch angegeben werden, wird DB_E_ERRORSINCOMMAND zurückgegeben. Werden weder SSPROP_PARAM_UDT_CATALOGNAME noch SSPROP_PARAM_UDT_SCHEMANAME angegeben, muss der UDT in derselben Datenbank und im selben Schema definiert werden wie die Tabelle. Befindet sich der UDT nicht im selben Schema wie die Tabelle (aber in derselben Datenbank), muss SSPROP_PARAM_UDT_SCHEMANAME angegeben werden. Befindet sich die UDT-Definition in einer anderen Datenbank, müssen SSPROP_PARAM_UDT_CATALOGNAME und SSPROP_PARAM_UDT_SCHEMANAME angegeben werden.

Die DBPROPSET_SQLSERVERCOLUMN-Eigenschaftengruppe

Um die Erstellung von Tabellen in der ITableDefinition-Schnittstelle zu unterstützen, fügt SQL Server Native Client die folgenden drei neuen Spalten zum DBPROPSET_SQLSERVERCOLUMN Eigenschaftensatz hinzu.

Name Description type BESCHREIBUNG
SSPROP_COL_UDT_CATALOGNAME UDT_CATALOGNAME VT_BSTR Bei Spalten vom Typ DBTYPE_UDT ist diese Eigenschaft eine Zeichenfolge, die den Namen des Katalogs angibt, in dem der UDT definiert ist.
SSPROP_COL_UDT_SCHEMANAME UDT_SCHEMANAME VT_BSTR Bei Spalten vom Typ DBTYPE_UDT ist diese Eigenschaft eine Zeichenfolge, die den Namen des Schemas angibt, in dem der UDT definiert ist.
SSPROP_COL_UDT_NAME UDT_NAME VT_BSTR Bei Spalten vom Typ DBTYPE_UDT ist diese Eigenschaft eine Zeichenfolge, die den einteiligen Namen des UDT angibt. Für andere Spaltentypen gibt diese Eigenschaft eine leere Zeichenfolge zurück.

Hinweis

UDTs werden nicht im Schemarowset „PROVIDER_TYPES“ angezeigt. Alle Spalten haben Lese- und Schreibzugriff.

ADO verweist mit dem entsprechenden Eintrag aus der Beschreibungsspalte auf diese Eigenschaften.

SSPROP_COL_UDTNAME ist erforderlich. SSPROP_COL_UDT_CATALOGNAME und SSPROP_COL_UDT_SCHEMANAME sind optional. Wenn Eigenschaften falsch angegeben werden, wird DB_E_ERRORSINCOMMAND zurückgegeben.

Werden weder SSPROP_COL_UDT_CATALOGNAME noch SSPROP_COL_UDT_SCHEMANAME angegeben, muss der UDT in derselben Datenbank und im selben Schema definiert werden wie die Tabelle.

Befindet sich der UDT nicht im selben Schema wie die Tabelle (aber in derselben Datenbank), muss SSPROP_COL_UDT_SCHEMANAME angegeben werden.

Befindet sich die UDT-Definition in einer anderen Datenbank, müssen SSPROP_COL_UDT_CATALOGNAME und SSPROP_COL_UDT_SCHEMANAME angegeben werden.

Hinzufügungen und Änderungen an der OLE DB-Schnittstelle

SQL Server Native Client fügt neue Werte oder Änderungen an vielen der wichtigsten OLE DB-Schnittstellen hinzu.

Die ISSCommandWithParameters-Schnittstelle

Um UDTs über OLE DB zu unterstützen, implementiert SQL Server Native Client eine Reihe von Änderungen, einschließlich des Hinzufügens der ISSCommandWithParameters-Schnittstelle . Diese neue Schnittstelle erbt von der OLE DB-Kernschnittstelle ICommandWithParameters. Zusätzlich zu den drei von ICommandWithParameters geerbten Methoden; GetParameterInfo, MapParameterNames und SetParameterInfo; ISSCommandWithParameters stellt die Methoden "GetParameterProperties " und "SetParameterProperties" bereit, die zum Verarbeiten serverspezifischer Datentypen verwendet werden.

Hinweis

Die ISSCommandWithParameters-Schnittstelle nutzt auch die neue SSPARAMPROPS-Struktur.

Die IDBColumnsRowset-Schnittstelle

Zusätzlich zur ISSCommandWithParameters-Schnittstelle fügt SQL Server Native Client auch neue Werte zum Rowset hinzu, das vom Aufrufen der IColumnsRowset::GetColumnRowset-Methode zurückgegeben wird, einschließlich der folgenden.

Spaltenname type BESCHREIBUNG
DBCOLUMN_SS_UDT_CATALOGNAME DBTYPE_WSTR Ein UDT-Katalognamensbezeichner.
DBCOLUMN_SS_UDT_SCHEMANAME DBTYPE_WSTR Ein UDT-Schemanamensbezeichner.
DBCOLUMN_SS_UDT_NAME DBTYPE_WSTR Ein UDT-Namensbezeichner.
DBCOLUMN_SS_ASSEMBLY_TYPENAME DBTYPE_WSTR Der qualifizierte Name der Assembly mit dem Typnamen und allen zur CLR-Referenzierung erforderlichen Angaben zur Assembly-ID.

Ist DBCOLUMN_TYPE auf DBTYPE_UDT festgelegt, können Sie eine Server-UDT-Spalte von anderen Binärtypen unterscheiden, indem Sie die oben genannten neuen UDT-Metadaten betrachten. Sind diese Daten teilweise vollständig, handelt es sich bei dem Servertyp um einen UDT. Für Nicht-UDT-Servertypen werden diese Spalten immer als NULL zurückgegeben.

ODBC-Treiber für SQL Server Native Client

Im SQL Server Native Client ODBC-Treiber wurden einige Änderungen vorgenommen, um UDTs zu unterstützen. Der SQL Server Native Client ODBC-Treiber ordnet den SQL Server-UDT SQL_SS_UDT treiberspezifischen SQL-Datentypbezeichner zu. UDT-Spalten werden als SQL_SS_UDT angegeben. Wenn Sie eine UDT-Spalte explizit einem anderen Typ in einer SQL-Anweisung zuordnen, indem Sie die Methoden ToString oder ToXMLString der UDT oder über die CAST/CONVERT-Funktion verwenden, gibt der Typ der Spalte im Resultset den tatsächlichen Typ der Spalte wieder, in den die Spalte konvertiert wurde.

SQLColAttribute, SQLDescribeParam, SQLGetDescField

Es wurden vier neue treiberspezifische Deskriptorfelder hinzugefügt, um zusätzliche Informationen für eine UDT-Spalte eines Resultsets oder einen UDT-Parameter der gespeicherten Prozedur/parametrisierten Abfrage bereitzustellen, die über die Funktionen SQLColAttribute, SQLDescribeParam und SQLGetDescField abgerufen werden sollen.

Die vier neuen Deskriptorfelder sind SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME und SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.

SQLColumns, SQLProcedureColumns

Darüber hinaus werden drei neue treiberspezifische Spalten zum Resultset hinzugefügt, das aus den Funktionen SQLColumns und SQLProcedureColumns zurückgegeben wird, um zusätzliche Informationen zu einer UDT-Resultsetspalte oder einem UDT-Parameter bereitzustellen. Diese drei neuen Spalten sind SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME und SS_UDT_ASSEMBLY_TYPE_NAME.

Unterstützte Umwandlungen

Bei der Umwandlung von SQL- in C-Datentypen können SQL_C_WCHAR, SQL_C_BINARY und SQL_C_CHAR in SQL_SS_UDT umgewandelt werden. Beachten Sie jedoch, dass Binärdaten bei der Umwandlung der SQL-Datentypen SQL_C_WCHAR und SQL_C_CHAR in eine hexadezimale Zeichenfolge umgewandelt werden.

Bei der Umwandlung von C- in SQL-Datentypen können SQL_C_WCHAR, SQL_C_BINARY und SQL_C_CHAR in SQL_SS_UDT umgewandelt werden. Beachten Sie jedoch, dass Binärdaten beim Konvertieren aus dem SQL_C_WCHAR und SQL_C_CHAR SQL-Datentypen in eine Hex-Zeichenfolge konvertiert werden.

Weitere Informationen

SQL Server Native Client-Funktionen
ISSCommandWithParameters (OLE DB)