Membuat Jenis yang Ditentukan Pengguna - Persyaratan

Artikel
05/30/2023

Berlaku untuk: SQL Server

Anda harus membuat beberapa keputusan desain penting saat membuat jenis yang ditentukan pengguna (UDT) untuk diinstal di Microsoft SQL Server. Untuk sebagian besar UDT, membuat UDT sebagai struktur disarankan, meskipun membuatnya sebagai kelas juga merupakan pilihan. Definisi UDT harus sesuai dengan spesifikasi untuk membuat UDT agar terdaftar di SQL Server.

Persyaratan untuk Menerapkan UDT

Untuk berjalan di SQL Server, UDT Anda harus menerapkan persyaratan berikut dalam definisi UDT:

UDT harus menentukan Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute. Penggunaan System.SerializableAttribute bersifat opsional, tetapi disarankan.

UDT harus mengimplementasikan antarmuka System.Data.SqlTypes.INullable di kelas atau struktur dengan membuat metode Null statis publik (Dibagikan dalam Microsoft Visual Basic). SQL Server sadar null secara default. Ini diperlukan agar kode yang dijalankan di UDT dapat mengenali nilai null.
UDT harus berisi metode Parse statis publik (atau Bersama) yang mendukung penguraian dari, dan metode ToString publik untuk mengonversi ke representasi string objek.
UDT dengan format serialisasi yang ditentukan pengguna harus mengimplementasikan antarmuka System.Data.IBinarySerialize dan menyediakan metode Baca dan Tulis .
UDT harus menerapkan System.Xml.Serialization.IXmlSerializable, atau semua bidang dan properti publik harus dari jenis xml yang dapat diserialisasikan atau dihiasi dengan atribut XmlIgnore jika mengambil alih serialisasi standar diperlukan.
Hanya boleh ada satu serialisasi objek UDT. Validasi gagal jika rutinitas serialisasi atau deserialisasi mengenali lebih dari satu representasi objek tertentu.
SqlUserDefinedTypeAttribute.IsByteOrdered harus benar untuk membandingkan data dalam urutan byte. Jika antarmuka IComparable tidak diimplementasikan dan SqlUserDefinedTypeAttribute.IsByteOrdered salah, perbandingan urutan byte akan gagal.
UDT yang ditentukan dalam kelas harus memiliki konstruktor publik yang tidak mengambil argumen. Anda dapat secara opsional membuat konstruktor kelas tambahan yang kelebihan beban.
UDT harus mengekspos elemen data sebagai bidang publik atau prosedur properti.
Nama publik tidak boleh lebih panjang dari 128 karakter, dan harus sesuai dengan aturan penamaan SQL Server untuk pengidentifikasi seperti yang didefinisikan dalam Pengidentifikasi Database.
sql_variant kolom tidak boleh berisi instans UDT.
Anggota yang diwariskan tidak dapat diakses dari Transact-SQL karena sistem jenis SQL Server tidak mengetahui hierarki warisan di antara UDT. Namun, Anda dapat menggunakan pewarisan saat menyusun kelas dan Anda dapat memanggil metode tersebut dalam implementasi kode terkelola dari jenis tersebut.
Anggota tidak dapat kelebihan beban, kecuali untuk konstruktor kelas. Jika Anda membuat metode yang kelebihan beban, tidak ada kesalahan yang muncul saat Anda mendaftarkan rakitan atau membuat jenis di SQL Server. Deteksi metode kelebihan beban terjadi pada run time, bukan saat jenis dibuat. Metode yang kelebihan beban dapat ada di kelas selama metode tersebut tidak pernah dipanggil. Setelah Anda memanggil metode yang kelebihan beban, kesalahan akan muncul.
Setiap anggota statis (atau Bersama) harus dinyatakan sebagai konstanta atau sebagai baca-saja. Anggota statis tidak dapat diubah.
Jika bidang SqlUserDefinedTypeAttribute.MaxByteSize diatur ke -1, UDT berseri dapat sebesar batas ukuran objek besar (LOB) (saat ini 2 GB). Ukuran UDT tidak boleh melebihi nilai yang ditentukan di bidang MaxByteSized .

Catatan

Meskipun tidak digunakan oleh server untuk melakukan perbandingan, Anda dapat secara opsional mengimplementasikan antarmuka System.IComparable , yang mengekspos satu metode, CompareTo. Ini digunakan di sisi klien dalam situasi di mana diinginkan untuk membandingkan atau memesan nilai UDT secara akurat.

Serialisasi Asli

Memilih atribut serialisasi yang tepat untuk UDT Anda tergantung pada jenis UDT yang ingin Anda buat. Format serialisasi Asli menggunakan struktur yang sangat sederhana yang memungkinkan SQL Server menyimpan representasi asli UDT yang efisien pada disk. Format Asli direkomendasikan jika UDT sederhana dan hanya berisi bidang dari jenis berikut:

bool, byte, sbyte, pendek, ushort, int, uint, long, ulong, float, double, SqlByte, SqlInt16, SqlInt32, SqlInt64, SqlDateTime, SqlSingle, SqlDouble, SqlMoney, SqlBoolean

Jenis nilai yang terdiri dari bidang dari jenis di atas adalah kandidat yang baik untuk format Asli , seperti struktur di Visual C#, (atau Struktur seperti yang diketahui di Visual Basic). Misalnya, UDT yang ditentukan dengan format Serialisasi asli mungkin berisi bidang UDT lain yang juga ditentukan dengan format Asli . Jika definisi UDT lebih kompleks dan berisi jenis data yang tidak ada di daftar di atas, Anda harus menentukan format serialisasi UserDefined sebagai gantinya.

Format Asli memiliki persyaratan berikut:

Jenis tidak boleh menentukan nilai untuk Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.MaxByteSize.
Semua bidang harus dapat diserialisasikan.
System.Runtime.InteropServices.StructLayoutAttribute harus ditentukan sebagai StructLayout.LayoutKindSequential jika UDT didefinisikan dalam kelas dan bukan struktur. Atribut ini mengontrol tata letak fisik bidang data dan digunakan untuk memaksa anggota ditata sesuai urutan tampilannya. SQL Server menggunakan atribut ini untuk menentukan urutan bidang untuk UDT dengan beberapa nilai.

Untuk contoh UDT yang ditentukan dengan serialisasi Asli , lihat Point UDT dalam Jenis yang Ditentukan Pengguna Pengodean.

Serialisasi UserDefined

Pengaturan format UserDefined untuk atribut Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute memberi pengembang kontrol penuh atas format biner. Saat menentukan properti Format atribut sebagai UserDefined, Anda harus melakukan hal berikut dalam kode Anda:

Tentukan properti atribut IsByteOrdered opsional. Nilai default-nya adalah salah.
Tentukan properti MaxByteSize dari Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.
Tulis kode untuk menerapkan metode Baca dan Tulis untuk UDT dengan mengimplementasikan antarmuka System.Data.Sql.IBinarySerialize .

Untuk contoh UDT yang ditentukan dengan serialisasi UserDefined , lihat Mata Uang UDT dalam Jenis yang Ditentukan Pengguna Pengkodean.

Catatan

Bidang UDT harus menggunakan serialisasi asli atau dipertahankan agar dapat diindeks.

Atribut Serialisasi

Atribut menentukan bagaimana serialisasi digunakan untuk membangun representasi penyimpanan UDT dan untuk mengirimkan UDT berdasarkan nilai ke klien. Anda diharuskan untuk menentukan Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute saat membuat UDT. Atribut Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute menunjukkan bahwa kelas adalah UDT dan menentukan penyimpanan untuk UDT. Anda dapat secara opsional menentukan atribut Serializable , meskipun SQL Server tidak memerlukan ini.

Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute memiliki properti berikut.

Format
Menentukan format serialisasi, yang dapat berupa Native atau UserDefined, tergantung pada jenis data UDT.

IsByteOrdered
Nilai Boolean yang menentukan bagaimana SQL Server melakukan perbandingan biner pada UDT.

IsFixedLength
Menunjukkan apakah semua instans UDT ini memiliki panjang yang sama.

MaxByteSize
Ukuran maksimum instans, dalam byte. Anda harus menentukan MaxByteSize dengan format serialisasi UserDefined . Untuk UDT dengan serialisasi yang ditentukan pengguna yang ditentukan, MaxByteSize mengacu pada ukuran total UDT dalam bentuk serial seperti yang didefinisikan oleh pengguna. Nilai MaxByteSize harus dalam rentang 1 hingga 8000, atau diatur ke -1 untuk menunjukkan bahwa UDT lebih besar dari 8000 byte (ukuran total tidak boleh melebihi ukuran LOB maksimum). Pertimbangkan UDT dengan properti string 10 karakter (System.Char). Ketika UDT diserialisasikan dengan menggunakan BinaryWriter, ukuran total string yang diserialisasikan adalah 22 byte: 2 byte per karakter Unicode UTF-16, dikalikan dengan jumlah karakter maksimum, ditambah 2 byte kontrol overhead yang dikeluarkan dari serialisasi aliran biner. Oleh karena itu, ketika menentukan nilai MaxByteSize, ukuran total UDT berseri harus dipertimbangkan: ukuran data yang diserialisasikan dalam bentuk biner ditambah overhead yang dikeluarkan oleh serialisasi.

ValidationMethodName
Nama metode yang digunakan untuk memvalidasi instans UDT.

Mengatur IsByteOrdered

Ketika properti Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.IsByteOrdered diatur ke true, Anda berlaku menjamin bahwa data biner berseri dapat digunakan untuk urutan semantik informasi. Dengan demikian, setiap instans objek UDT yang diurutkan byte hanya dapat memiliki satu representasi berseri. Ketika operasi perbandingan dilakukan di SQL Server pada byte yang diserialisasikan, hasilnya harus sama seperti jika operasi perbandingan yang sama telah terjadi dalam kode terkelola. Fitur berikut ini juga didukung ketika IsByteOrdered diatur ke true:

Kemampuan untuk membuat indeks pada kolom jenis ini.
Kemampuan untuk membuat kunci primer dan asing serta batasan CHECK dan UNIQUE pada kolom jenis ini.
Kemampuan untuk menggunakan klausa TRANSACT-SQL ORDER BY, GROUP BY, dan PARTITION BY. Dalam kasus ini, representasi biner dari jenis digunakan untuk menentukan urutan.
Kemampuan untuk menggunakan operator perbandingan dalam pernyataan Transact-SQL.
Kemampuan untuk mempertahankan kolom komputasi dari jenis ini.

Perhatikan bahwa format serialisasi Native dan UserDefined mendukung operator perbandingan berikut saat IsByteOrdered diatur ke true:

Sama dengan (=)
Tidak sama dengan (!=)
Lebih besar dari (>)
Kurang dari (<)
Lebih besar dari atau sama dengan (>=)
Kurang dari atau sama dengan (<=)

Menerapkan Nullability

Selain menentukan atribut untuk rakitan Anda dengan benar, kelas Anda juga harus mendukung nullability. UDT yang dimuat ke SQL Server bersifat null-aware, tetapi agar UDT mengenali nilai null, kelas harus mengimplementasikan antarmuka INullable . Untuk informasi selengkapnya dan contoh cara menerapkan nullability dalam UDT, lihat Pengodean Jenis yang Ditentukan Pengguna.

Konversi String

Untuk mendukung konversi string ke dan dari UDT, Anda harus menyediakan metode Parse dan metode ToString di kelas Anda. Metode Parse memungkinkan string untuk dikonversi menjadi UDT. Ini harus dinyatakan sebagai statis (atau Dibagikan di Visual Basic), dan mengambil parameter jenis System.Data.SqlTypes.SqlString. Untuk informasi selengkapnya dan contoh cara mengimplementasikan metode Penguraian dan ToString , lihat Pengodean Jenis yang Ditentukan Pengguna.

Serialisasi XML

UDT harus mendukung konversi ke dan dari jenis data xml dengan menyesuaikan dengan kontrak untuk serialisasi XML. Namespace System.Xml.Serialization berisi kelas yang digunakan untuk menserialisasikan objek ke dalam dokumen format XML atau aliran. Anda dapat memilih untuk menerapkan serialisasi xml dengan menggunakan antarmuka IXmlSerializable , yang menyediakan pemformatan kustom untuk serialisasi XML dan deserialisasi.

Selain melakukan konversi eksplisit dari UDT ke xml, serialisasi XML memungkinkan Anda untuk:

Gunakan Xquery atas nilai instans UDT setelah konversi ke jenis data xml .
Gunakan UDT dalam kueri berparameter dan metode Web dengan Native XML Web Services di SQL Server.
Gunakan UDT untuk menerima beban massal data XML.
Serialisasi Himpunan Data yang berisi tabel dengan kolom UDT.

UDT tidak diserialisasikan dalam kueri XML UNTUK. Untuk menjalankan kueri FOR XML yang menampilkan serialisasi XML UDT, konversikan setiap kolom UDT secara eksplisit ke jenis data xml dalam pernyataan SELECT. Anda juga dapat secara eksplisit mengonversi kolom menjadi varbinary, varchar, atau nvarchar.

Lihat Juga

Membuat Jenis yang Ditentukan Pengguna

Bagikan melalui