Migrasi dari System.Data.SqlClient ke Microsoft. Data.SqlClient

Microsoft. Data.SqlClient adalah penyedia yang didukung untuk fitur SQL Server baru dalam aplikasi .NET. Ia mempertahankan model pemrograman ADO.NET yang digunakan oleh System.Data.SqlClient, tetapi paket, namespace, default, dan beberapa tipe publik berbeda.

Perlakukan migrasi sebagai pembaruan provider, bukan hanya penggantian namespace.

Merencanakan migrasi

Sebelum mengubah kode:

  1. Catat versi layanan .NET, System.Data.SqlClient, SQL Server, dan Microsoft SQL yang didukung aplikasi.

  2. Mode autentikasi inventaris, kata kunci string koneksi, sertifikat kustom, penyedia Always Encrypted, konfigurasi DbProviderFactories, tipe yang ditentukan pengguna SQL Server, dan penggunaan System.Data.SqlTypes.

  3. Jalankan pengujian aplikasi saat ini dan simpan baseline untuk perilaku koneksi, query, transaksi, percobaan ulang, dan performa.

  4. Cari referensi paket langsung dan transitif:

    dotnet list package --include-transitive

Migrasikan satu aplikasi atau pustaka akses data bersama pada satu waktu. Jangan berpindah objek khusus penyedia antara kode yang masih menggunakan System.Data.SqlClient dan kode yang menggunakan Microsoft.Data.SqlClient.

Ganti paket

Hapus referensi paket eksplisit System.Data.SqlClient , jika ada:

dotnet remove package System.Data.SqlClient

Tambahkan Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Jika Microsoft. Data.SqlClient 7.0 atau versi lebih baru menggunakan mode otentikasi Microsoft Entra yang disediakan oleh driver, tambahkan juga:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

Untuk pemilihan versi dan paket, lihat Instal, perbarui, dan sebarkan Microsoft. Data.SqlClient.

Perbarui namespace

Ganti namespace penyedia utama:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

Perbarui nama berkualifikasi lengkap, alias, kode yang dihasilkan, pendaftaran injeksi dependensi, string refleksi, konfigurasi, dan objek pengganti pengujian yang merujuk ke System.Data.SqlClient.

Jangan ganti namespace umum System.Data atau System.Data.Common. Microsoft.Data.SqlClientterus menggunakan tipe ADO.NET seperti CommandType, DbType, IsolationLevel, DataTable, DbConnection, , dan DbCommand dari namespace tersebut.

Beberapa tipe khusus SQL Server pindah ke namespace lainMicrosoft.Data:

Tipe Namespace sebelumnya Namespace Microsoft.Data.SqlClient
SqlDataRecord, SqlMetaData Microsoft.SqlServer.Server Microsoft.Data.SqlClient.Server
SqlFileStream System.Data.SqlTypes Microsoft.Data.SqlTypes
SqlNotificationRequest System.Data.Sql Microsoft.Data.Sql
OperationAbortedException System.Data Microsoft.Data

Pada Microsoft.Data.SqlClient versi 5.0 dan yang lebih baru, tipe common language runtime (CLR) SQL Server lainnya tetap berada di Microsoft.SqlServer.Server. Perbarui setiap tipe berdasarkan kesalahan kompiler dan referensi API Microsoft.Data.SqlClient, alih-alih mengganti seluruh namespace.

Perbarui konfigurasi .NET Framework

Aplikasi yang mencari provider melalui DbProviderFactories mungkin memerlukan pendaftaran provider di App.config atau Web.config:

<configuration>
  <system.data>
    <DbProviderFactories>
      <add name="SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description=".NET data provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

Kode pembaruan yang meminta nama invarian penyedia:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

Jangan tambahkan konfigurasi ini saat aplikasi membuat SqlConnection langsung dan tidak menggunakan DbProviderFactories.

Tinjau enkripsi dan validasi sertifikat

Microsoft. Data.SqlClient menggunakan pengaturan default yang lebih aman dibandingkan System.Data.SqlClient.

Behavior System.Data.SqlClient Microsoft.Data.SqlClient
Enkripsi bawaan Encrypt=false Encrypt=true mulai dari versi 4.0
Validasi sertifikat server Memvalidasi sertifikat hanya ketika enkripsi klien diaktifkan Mulai dari versi 2.0, sertifikat divalidasi sesuai dengan TrustServerCertificate saat server memaksa enkripsi, meskipun Encrypt=false
Enkripsi ketat Tidak didukung Encrypt=Strict mulai dari versi 5.0 untuk server yang mendukung TDS 8.0
SqlConnectionStringBuilder.Encrypt jenis bool SqlConnectionEncryptOption mulai dari versi 5.0

Jangan tetapkan Encrypt=false atau TrustServerCertificate=true sebagai solusi umum untuk migrasi. Konfigurasikan sertifikat yang dipercaya klien dan gunakan nama server yang sesuai dengan sertifikat. Gunakan TrustServerCertificate=true hanya untuk lingkungan pengembangan terkontrol di mana validasi tidak memungkinkan.

Perubahan ke SqlConnectionEncryptOption kompatibel dengan kode sumber dalam penetapan umum melalui konversi implisit, tetapi merupakan perubahan yang merusak kompatibilitas biner. Kompilasi ulang setiap assembly yang mengakses SqlConnectionStringBuilder.Encrypt.

Untuk detailnya, lihat Enkripsi dan validasi sertifikat.

Tinjau string koneksi

Microsoft. Data.SqlClient menambahkan kata kunci dan alias yang tidak dikenali oleh System.Data.SqlClient. Misalnya, ia menerima alias dengan spasi seperti Application Intent dan Multi Subnet Failover.

Jangan buat string koneksi dengan Microsoft.Data.SqlClient.SqlConnectionStringBuilder lalu meneruskannya ke System.Data.SqlClient. Selama migrasi bertahap, pastikan setiap string koneksi builder dipasangkan dengan penyedianya.

Tinjau kata kunci autentikasi, enkripsi, coba ulang, failover, dan sertifikat berdasarkan sintaks string koneksi.

Tinjau perilaku parameter

Uji parameter tanggal dan waktu secara eksplisit:

Parameter Perilaku System.Data.SqlClient Perilaku Microsoft.Data.SqlClient
DbType.Time dengan nilai DateTime Menerima nilai Gunakan sebuah TimeSpan nilai
DbType.Date dengan nilai DateTime Dapat mengirim komponen tanggal dan waktu Memangkas komponen waktu

Tentukan SqlDbType, panjang, presisi, dan skala untuk parameter di mana inferensi tipe SQL Server dapat mengubah rencana kueri atau perilaku konversi. Jangan gunakan AddWithValue sebagai pintasan migrasi ketika tipe database sudah diketahui.

Periksa referensi penyedia transitif

Menghapus paket secara langsung tidak menjamin bahwa System.Data.SqlClient sudah terhapus. Run:

dotnet list package --include-transitive

Jika kedua penyedia tetap ada:

  1. Identifikasi paket yang membawa masuk System.Data.SqlClient.
  2. Perbarui atau ganti ketergantungan tersebut jika memungkinkan.
  3. Pertahankan tipe khusus penyedia di dalam batas dependensi jika keduanya memang harus tetap ada.
  4. Gunakan alias namespace eksplisit hanya sebagai bantuan sementara. Jangan teruskan koneksi, transaksi, parameter, atau pembaca dari satu penyedia ke penyedia lain.

Beri perhatian khusus pada pustaka jenis CLR SQL Server dan kerangka kerja akses data lama yang mengekspos tipe System.Data.SqlClient dalam API publiknya.

Tinjau perilaku globalisasi

.NET Framework dan versi .NET sebelum .NET 5 menggunakan fitur globalisasi National Language Support (NLS) pada Windows. Versi .NET saat ini menggunakan Komponen Internasional untuk Unicode (ICU) secara default di Windows, Linux, dan macOS.

Perbedaan runtime ini dapat mengubah hasil beberapa perbandingan SqlString. SQL Server menggunakan perilaku perbandingan NLS. Jika perbandingan di sisi klien SqlString harus cocok dengan perilaku server, uji nilai yang terdampak dan tinjau Globalisasi dan ICU. Sebuah aplikasi dapat menggunakan NLS sebagai pengganti ICU jika diperlukan.

Mode invarian globalisasi tidak didukung oleh Microsoft.Data.SqlClient.

Validasi aplikasi yang dimigrasi

Buat dan uji pada setiap kerangka kerja target dan sistem operasi yang didukung.

Validasi:

  • Paket pemulihan dan output yang dipublikasikan.
  • Autentikasi SQL, autentikasi terintegrasi Windows, dan autentikasi Microsoft Entra yang digunakan oleh aplikasi.
  • Negosiasi TLS, validasi sertifikat, dan string koneksi parsing.
  • Penggabungan koneksi dan penyegaran token akses.
  • Jenis parameter, nilai null, presisi, skala, tanggal, dan perilaku waktu.
  • Transaksi, pembatalan, batas waktu, percobaan ulang, dan pengalihan saat kegagalan.
  • Selalu Terenkripsi, tipe CLR SQL Server, salinan massal, notifikasi kueri, dan fitur spesifik penyedia lainnya yang digunakan oleh aplikasi.
  • Pencatatan, penghitung, pelacakan, dan penanganan pengecualian.

Jalankan kueri representatif terhadap setiap versi mesin basis data yang didukung. Kompilasi yang berhasil tidak memvalidasi keamanan koneksi, ketergantungan runtime, atau konversi data.

Konten terkait

  • Last updated on