Ruang nama Microsoft.Data.SqlClient dan kompatibilitas

Namespace Microsoft.Data.SqlClient berisi penyedia data .NET yang didukung untuk basis data yang kompatibel dengan SQL Server. Ini bermula sebagai fork dari System.Data.SqlClient dan tetap mempertahankan model pemrograman ADO.NET yang familier, sembari menghadirkan fitur-fitur baru SQL Server secara independen dari runtime .NET.

Gunakan Microsoft.Data.SqlClient untuk pengembangan baru.

Instal dan impor namespace

Tambahkan paket NuGet:

dotnet add package Microsoft.Data.SqlClient

Impor ruang nama:

using Microsoft.Data.SqlClient;

Sebagian besar aplikasi menggunakan SqlConnection, SqlCommand, SqlParameter, SqlDataReader, dan SqlTransaction. Untuk cakupan publik lengkap, lihat referensi API Microsoft.Data.SqlClient.

Hubungan dengan ADO.NET

ADO.NET adalah model akses data yang terintegrasi dalam .NET. Ini mendefinisikan abstraksi yang independen dari penyedia dalam System.Data.Common namespace, dan Microsoft. Data.SqlClient menyediakan implementasi konkret.

Abstraksi ADO.NET Tipe SqlClient Kegunaan
DbConnection SqlConnection Membuka koneksi logis ke satu database.
DbCommand SqlCommand Menjalankan teks Transact-SQL (T-SQL) atau prosedur tersimpan.
DbParameter SqlParameter Mengirim nilai yang diketik secara terpisah dari teks perintah.
DbDataReader SqlDataReader Mengalirkan baris hasil dari server secara bertahap.
DbTransaction SqlTransaction Mengelompokkan perintah menjadi satu transaksi yang melakukan commit atau rollback sebagai satu unit.
DbDataAdapter SqlDataAdapter Mengisi dan memperbarui objek DataSet dan DataTable yang terputus.
DbBatch SqlBatch Mengirim beberapa perintah sebagai satu kumpulan pada kerangka kerja target yang didukung.

Microsoft. Data.SqlClient juga menyediakan API khusus SQL Server seperti:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Dukungan autentikasi, enkripsi, dan tipe data khusus SQL Server

Program terhadap abstraksi ADO.NET ketika sebuah pustaka harus mendukung beberapa penyedia basis data. Gunakan tipe SqlClient ketika sebuah aplikasi menargetkan SQL Server dan membutuhkan fitur khusus penyedia, seperti autentikasi Microsoft Entra, Always Encrypted, salinan massal, parameter bernilai tabel, atau logika retry yang dapat dikonfigurasi. Simpan kode spesifik penyedia di belakang batas akses data jika sisa aplikasi harus tetap independen dari penyedia.

Akses terhubung dan terputus

Akses terhubung menjaga koneksi tetap terbuka saat perintah berjalan dan saat aplikasi membaca hasilnya. Permintaan tipikal mengikuti urutan berikut:

  1. Buat SqlConnection dari string koneksi, lalu buka.
  2. Buat SqlCommand dan tambahkan nilai SqlParameter.
  3. Jalankan perintah .
  4. Proses nilai skalar, hitungan baris yang terpengaruh, atau SqlDataReader.
  5. Lepaskan pembaca, perintah, dan koneksi.

Gunakan akses terhubung untuk sebagian besar API web, layanan, pekerja, dan aplikasi baris perintah. SqlDataReader mengalirkan baris dan biasanya menggunakan memori lebih sedikit daripada memuat seluruh hasil ke dalam DataSet.

Akses terputus dari koneksi menggunakan SqlDataAdapter untuk menyalin data ke DataSet atau DataTable dalam memori. Aplikasi dapat menutup koneksi saat membaca atau mengubah data dalam memori, lalu terhubung kembali untuk mengirim pembaruan. Gunakan untuk pengikatan data, hubungan dan batasan dalam memori, suntingan offline yang akan Anda rekonsiliasi nanti, atau aplikasi yang sudah ada yang dibangun di sekitar DataAdapter. Untuk layanan baru yang berorientasi permintaan, mulai dengan SqlCommand dan SqlDataReader.

Masa pakai objek dan konkurensi

Buka dan buang SqlConnection untuk setiap unit kerja. Connection pooling menggunakan kembali koneksi fisik yang mendasarinya, jadi jangan biarkan satu koneksi global tetap terbuka selama masa pakai aplikasi. Hapus koneksi, perintah, pembaca, transaksi, dan objek salinan massal dengan cepat. Dalam kode asinkron, gunakan await using untuk tipe yang mengimplementasikan IAsyncDisposable pada kerangka kerja target, seperti SqlConnection dan SqlDataReader pada .NET, dan using biasa untuk tipe yang hanya mengimplementasikan IDisposable, seperti SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader, dan SqlTransaction tidak mendukung penggunaan bersamaan dari beberapa thread. Berikan setiap operasi bersamaan koneksi sendiri dan gunakan connection pooling. Multiple Active Result Sets (MARS) memungkinkan lebih dari satu set hasil aktif pada satu koneksi, tetapi tidak membuat objek SqlClient menjadi thread-safe.

Hubungan dengan System.Data.SqlClient

System.Data.SqlClient adalah penyedia yang lebih lama yang disertakan dalam .NET Framework dan rilis .NET sebelumnya. Microsoft.Data.SqlClient Menggunakan banyak nama tipe yang sama, tetapi memiliki paket, namespace, default, fitur, dan kebijakan dukungan yang berbeda.

Jangan merujuk kedua penyedia dalam kode aplikasi baru. Tipe dengan nama yang sama dari kedua paket tidak dapat dipertukarkan. System.Data.SqlClient.SqlConnection, misalnya, tidak dapat dilewatkan jika Microsoft.Data.SqlClient.SqlConnection diperlukan.

Migrasi biasanya dimulai dengan menambahkan Microsoft.Data.SqlClient paket dan mengubah referensi namespace, tetapi Anda juga harus meninjau enkripsi koneksi, parameter, konfigurasi, dependensi transitif, dan perilaku runtime. Ikuti Migrasi dari System.Data.SqlClient ke Microsoft. Data.SqlClient sebelum Anda menerapkan.

Kompatibilitas versi

Versi paket driver independen dari versi .NET aplikasi dan versi mesin database. Periksa ketiganya:

Komponen Apa yang harus diverifikasi
Microsoft.Data.SqlClient Garis rilis didukung dan berisi fitur yang digunakan aplikasi Anda.
.NET atau .NET Framework Aplikasi menargetkan runtime yang didukung oleh rilis driver tersebut.
Basis data kompatibel dengan SQL Server Rilis driver mendukung versi database dan server mendukung fitur protokol apa pun yang diminta, seperti TDS 8.0.

Untuk matriks saat ini, lihat siklus hidup dukungan driver SqlClient.

Perubahan khusus versi

Rilis driver dapat menambahkan API, memindahkan dependensi opsional, dan mengubah default yang aman. Tinjau perubahan sebelum setiap pembaruan kecil atau besar.

Contohnya meliputi:

  • Versi 4.0 diubah Encrypt menjadi default ke true.
  • Versi 5.0 memperkenalkan SqlConnectionEncryptOption dan Encrypt=Strict untuk TDS 8.0.
  • Versi 5.2 memperkenalkan SqlBatch pada target .NET modern yang didukung.
  • Versi 7.0 memindahkan autentikasi Microsoft Entra yang disediakan driver ke Microsoft.Data.SqlClient.Extensions.Azure.

Lihat Apa yang Baru di Microsoft. Data.SqlClient untuk tautan catatan rilis dan ringkasan pembaruan.

Beberapa fitur menggunakan tipe di luar namespace utama atau paket opsional.

Namespace atau paket Kegunaan
Microsoft.Data.SqlClient.Server Implementasi SqlClient dari SqlDataRecord dan SqlMetaData.
Microsoft.Data.SqlTypes Tipe khusus SqlClient seperti SqlFileStream, SqlJson, dan SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Payload peristiwa diagnostik bertipe kuat.
Microsoft.Data.SqlClient.Extensions.Azure Autentikasi Microsoft Entra yang disediakan oleh driver untuk versi 7.0 dan versi lebih baru.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Integrasi Azure Key Vault untuk Always Encrypted.

Jangan menyimpulkan persyaratan paket hanya dari namespace. Ikuti artikel fitur dan informasi ketergantungan paket NuGet untuk versi driver yang Anda gunakan.

Konten terkait

  • Terakhir diperbarui pada