大型 UDT

使用者定義類型 (UDT) 可讓開發人員將 Common Language Runtime (CLR) 物件儲存在 SQL Server 資料庫中來擴充伺服器的純量類型系統。 UDT 可包含多個項目並可具有不同的行為，與只含單一 SQL Server 系統資料類型的傳統別名資料類型有所不同。

注意

若要讓用戶端存取大型 UDT，請安裝 Microsoft.Data.SqlClient NuGet 套件，並匯入 Microsoft.Data.SqlClient。定義伺服器端 UDT 的 SQL CLR 類型仍保留在 Microsoft.SqlServer.Server；不要用客戶端-提供者型別替換這些類型。

在過去，UDT 的大小上限為 8 KB。在 SQL Server 2008 中，目前使用 UserDefined 格式的 UDT 已不再具有這項限制。

如需使用者定義型別的完整文件，請參閱 CLR 使用者定義型別。

使用 GetSchema 來擷取 UDT 結構描述

GetSchema 方法會在 DataTable 物件中回傳資料庫結構資訊。如需詳細資訊，請參閱 SQL Server 結構描述集合。

UDT 的 GetSchemaTable 資料欄值

GetSchemaTable 方法會在 DataTable 物件中傳回資料行中繼資料。下表描述 SQL Server 2005 與 SQL Server 2008 之間大型 UDT 之資料行中繼資料中的差異。

SqlDataReader 資料行	SQL Server 2005	SQL Server 2008 及更新版本
`ColumnSize`	不定	不定
`NumericPrecision`	255	255
`NumericScale`	255	255
`DataType`	`Byte[]`	UDT 執行個體
`ProviderSpecificDataType`	`SqlTypes.SqlBinary`	UDT 執行個體
`ProviderType`	21 （`SqlDbType.VarBinary`）	29 （`SqlDbType.Udt`）
`NonVersionedProviderType`	29 （`SqlDbType.Udt`）	29 （`SqlDbType.Udt`）
`DataTypeName`	`SqlDbType.VarBinary`	指定為 Database.SchemaName.TypeName 的三部分名稱。
`IsLong`	不定	不定

SqlDataReader 注意事項

該SqlDataReader類別在 SQL Server 2008 及之後版本中支援大型 UDT 值。讀取程式如何處理這些值取決於 SQL Server 版本以及連接字串中的 Type System Version。如需詳細資訊，請參閱ConnectionString。

當 Type System Version 為 SQL Server 2005 時，以下 SqlDataReader 方法使用大型 UDT 的二進位表示法：

GetProviderSpecificFieldType 會回傳 SqlBinary 的 Type 物件。
GetProviderSpecificValue 以及 GetSqlValue 返回 SqlBinary 值。
GetProviderSpecificValues 和 GetSqlValues 以特定提供者的資料行值填滿所提供的陣列，並回傳已填入的元素數。該陣列中較大的 UDT 值使用 SqlBinary。

對於相同的型別系統設定，GetValue 會回傳大型 UDT 值為 Byte[]。 GetValues 用欄位值填滿所提供的陣列，並回傳已填充的元素數量。該陣列中較大的 UDT 值使用 Byte[]。

請注意，不會針對目前的 ADO.NET 版本進行任何轉換。

指定 SqlParameters

以下 SqlParameter 屬性支援大型 UDT。

SqlParameter 屬性	說明
Value	取得或設定代表參數值的物件。預設值是 null。屬性可以是 `SqlBinary`、`Byte[]` 或受控物件。
SqlValue	取得或設定代表參數值的物件。預設值是 null。屬性可以是 `SqlBinary`、`Byte[]` 或受控物件。
Size	取得或設定要解析的參數值大小。預設值為 0。屬性可以是代表參數值大小的整數。對於大型 UDT 而言，這可能是 UDT 的實際大小，-1 則代表未知。

擷取資料範例

下列程式碼片段示範如何擷取大型 UDT 資料。該 connectionString 變數假設與 SQL Server 資料庫有有效連線，且 commandString 變數假設 SELECT 陳述式有效，且主鍵資料行列於最前。

using (SqlConnection connection = new SqlConnection(
    connectionString))
{
  connection.Open();
  SqlCommand command = new SqlCommand(commandString, connection);
  SqlDataReader reader = command.ExecuteReader();
  while (reader.Read())
  {
    // Retrieve the value of the Primary Key column.
    int id = reader.GetInt32(0);

    // Retrieve the value of the UDT.
    LargeUDT udt = (LargeUDT)reader[1];

    // You can also use GetSqlValue and GetValue.
    // LargeUDT udt = (LargeUDT)reader.GetSqlValue(1);
    // LargeUDT udt = (LargeUDT)reader.GetValue(1);

    Console.WriteLine(
     "ID={0} LargeUDT={1}", id, udt);
  }
reader.Close();
}

Using connection As New SqlConnection( _
    connectionString)
    connection.Open()
    Dim command As New SqlCommand(commandString, connection)
    Dim reader As SqlDataReader
    reader = command.ExecuteReader

    While reader.Read()
      ' Retrieve the value of the Primary Key column.
      Dim id As Int32 = reader.GetInt32(0)

      ' Retrieve the value of the UDT.
      Dim udt As LargeUDT = CType(reader(1), LargeUDT)

     ' You can also use GetSqlValue and GetValue.
     ' Dim udt As LargeUDT = CType(reader.GetSqlValue(1), LargeUDT)
     ' Dim udt As LargeUDT = CType(reader.GetValue(1), LargeUDT)

      ' Print values.
      Console.WriteLine("ID={0} LargeUDT={1}", id, udt)
    End While
    reader.Close()
End Using

另請參閱

上次更新時間： 2026-10-27