Opsi koneksi untuk Microsoft. Data.SqlClient

Opsi koneksi Microsoft.Data.SqlClient mengontrol cara driver membuat, mengidentifikasi, mengarahkan, mencoba kembali, dan mengelola kumpulan koneksi. Tetapkan semuanya di dalam string koneksi atau melalui properti SqlConnectionStringBuilderyang sesuai.

Untuk autentikasi Microsoft Entra ID, lihat autentikasi Microsoft Entra ID. Untuk pengaturan TLS, lihat Enkripsi dan validasi sertifikat.

Atur opsi dengan SqlConnectionStringBuilder

Gunakan pembangun alih-alih menggabungkan fragmen string koneksi:

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = "Orders",
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    ConnectRetryCount = 3,
    ConnectRetryInterval = 10,
    MultiSubnetFailover = true,
};

Kode ini menggunakan nama properti pembangun. Tabel menggunakan penulisan string koneksi yang umum. Pengemudi juga menerima alias yang terdokumentasi.

Opsi batas waktu

Keyword Default Behavior Versi
Connect Timeout 15 detik Membatasi waktu untuk membangun koneksi. Ketika pool berada pada Max Pool Size, hal ini juga membatasi waktu tunggu untuk koneksi dalam pool yang dapat digunakan. Connection Timeout dan Timeout adalah alias. Semua versi Microsoft. Data.SqlClient
Command Timeout 30 detik Mengatur timeout default untuk perintah yang terkait dengan koneksi. Atur CommandTimeout pada perintah ketika satu operasi membutuhkan batas berbeda. Nilai 0 berarti tidak ada batas waktu dan dapat membuat pekerjaan tertunda tanpa batas waktu. Microsoft. Data.SqlClient 2.1 dan versi selanjutnya

Timeout koneksi dan perintah mengukur pekerjaan yang berbeda. Connect Timeout tidak membatasi eksekusi query. Command Timeout tidak membatasi autentikasi maupun waktu tunggu untuk memperoleh koneksi dari pool.

A CancellationToken terpisah dari kedua pengaturan tersebut. Teruskan ke OpenAsync, command execution, dan reader methods agar pemanggil dapat berhenti menunggu sebelum timeout berakhir.

Opsi identitas dan routing beban kerja

Keyword Default Behavior Versi
Application Name Nama yang didefinisikan oleh penyedia Mengidentifikasi beban kerja dalam sesi, audit, dan diagnostik SQL Server. Gunakan satu nama stabil dengan kardinalitas rendah untuk setiap beban kerja yang diterapkan. Semua versi Microsoft. Data.SqlClient
Application Intent ReadWrite ReadOnly meminta routing niat baca ketika target dan grup ketersediaan dikonfigurasi untuk itu. Ini tidak membuat pernyataan SQL menjadi baca saja. Semua versi Microsoft. Data.SqlClient

Application Intent=ReadOnly Biasanya dipasangkan dengan pendengar Availability Group atau endpoint layanan yang mendukung routing baca. Lihat Ketersediaan tinggi dan pemulihan bencana.

Opsi jaringan dan paket

Keyword Default Behavior Versi
Packet Size 8.000 byte Mengatur ukuran paket jaringan Tabular Data Stream (TDS). Nilai yang didukung adalah 512 hingga 32.768 byte. Pertahankan default kecuali pengukuran beban kerja dan konfigurasi server membenarkan perubahan. Semua versi Microsoft. Data.SqlClient
MultiSubnetFailover false Menggunakan percobaan koneksi TCP secara paralel ke alamat-alamat IP yang dikembalikan untuk endpoint dengan beberapa alamat. Atur nilainya ke true untuk endpoint Azure SQL, listener availability group, dan instans failover cluster yang diakses melalui TCP. Semua versi Microsoft. Data.SqlClient

MultiSubnetFailover=true tidak mendukung instance bernama, protokol non-TCP, pencerminan basis data, atau endpoint yang dikonfigurasi dengan lebih dari 64 alamat IP. Aman untuk endpoint TCP dengan satu alamat IP.

Microsoft. Data.SqlClient 7.0 juga memiliki switch AppContext yang dapat membuat setiap koneksi berperilaku seolah-olah MultiSubnetFailover=true. Default string koneksi tetap ada false saat switch tersebut tidak diaktifkan. Lihat AppContext switches di SqlClient.

Opsi pooling

Keyword Default Behavior Versi
Pooling true Menggunakan kembali koneksi fisik untuk mencocokkan konfigurasi koneksi. Nonaktifkan hanya untuk diagnosis atau beban kerja yang diukur yang tidak bisa dikumpulkan dengan aman. Semua versi Microsoft. Data.SqlClient
Min Pool Size 0 Mempertahankan setidaknya sejumlah koneksi fisik ini di dalam pool setelah pool dibuat. Nilai positif dapat menjaga sesi database tetap terbuka hingga pool atau proses berakhir. Semua versi Microsoft. Data.SqlClient
Max Pool Size 100 Menetapkan batas koneksi fisik dalam satu pool. Permintaan menunggu hingga Connect Timeout saat pool penuh. Semua versi Microsoft. Data.SqlClient
Load Balance Timeout 0 detik Membuang koneksi saat kembali ke pool jika usianya melebihi nilai ini. Connection Lifetime adalah alias. 0 menonaktifkan penghapusan berdasarkan usia. Semua versi Microsoft. Data.SqlClient
Pool Blocking Period Auto Mengontrol apakah pool untuk sementara meneruskan kembali kegagalan login yang disimpan dalam cache. Automenonaktifkan periode pemblokiran untuk endpoint Azure SQL yang diakui dan mengaktifkannya untuk endpoint lain. Semua versi Microsoft. Data.SqlClient
Enlist true Secara otomatis mendaftarkan koneksi yang terbuka dalam transaksi ambient System.Transactions . Semua versi Microsoft. Data.SqlClient

Pengaturan pool berlaku untuk setiap pool yang berbeda, bukan untuk seluruh proses atau server database. Sebelum menaikkan Max Pool Size, pastikan koneksi dan pembaca dihapus dengan cepat dan database dapat menerima total hasil di setiap instance aplikasi.

Untuk kunci pool, perilaku token, periode pemblokiran, pembersihan, dan diagnostik, lihat penggabungan koneksi SQL Server.

Opsi pemulihan koneksi

Keyword Default Behavior Versi
Connect Retry Count 1 Mengatur jumlah percobaan ulang untuk memenuhi syarat kegagalan sementara selama koneksi awal dan untuk memulihkan koneksi idle yang rusak. Default yang berlaku adalah 2 untuk endpoint Azure SQL yang dikenali dan 5 untuk endpoint Azure Synapse dan endpoint sesuai permintaan yang dikenali. 0 menonaktifkan percobaan ulang ini. Semua versi Microsoft. Data.SqlClient
Connect Retry Interval 10 detik Mengatur penundaan sebelum upaya koneksi awal berikutnya atau pemulihan dari kondisi idle. Nilai yang valid adalah 1 hingga 60 detik. Semua versi Microsoft. Data.SqlClient

Percobaan ulang pertama saat pemulihan koneksi dilakukan segera. Connect Retry Interval berlaku sebelum percobaan selanjutnya. Untuk melewati percobaan ulang awal-terbuka bawaan untuk satu operasi, gunakan open overload dengan OpenWithoutRetry.

Kata kunci ini tidak mencoba ulang perintah yang gagal saat sedang berjalan. Gunakan logika retry yang dapat dikonfigurasi untuk kebijakan terbuka atau perintah khusus. Ulangi perintah hanya jika aman untuk mengulangi efeknya.

Opsi identitas dan sertifikat server

Opsi ini menyelesaikan persyaratan sertifikat atau penamaan Kerberos tertentu. Mereka tidak menggantikan autentikasi dan validasi sertifikat biasa.

Keyword Default Behavior Versi
Host Name In Certificate Nama host server Menyediakan Common Name (CN) atau Subject Alternative Name (SAN) yang diharapkan ketika koneksi menggunakan alias DNS yang berbeda dari sertifikat. Microsoft. Data.SqlClient 5.0 dan versi selanjutnya
Server Certificate Empty Menyediakan file PEM, DER, atau CER yang harus persis sesuai dengan sertifikat server saat Encrypt=Mandatory atau Encrypt=Strict. Microsoft. Data.SqlClient 5.1 dan versi selanjutnya
Server SPN Berasal dari nama server Mengesampingkan Service Principal Name (SPN) yang digunakan untuk autentikasi terintegrasi ke server utama. Atur ini hanya jika penamaan Kerberos yang digunakan memerlukan SPN yang eksplisit. Microsoft. Data.SqlClient 5.0 dan versi selanjutnya
Failover Partner SPN Berasal dari mitra failover Mengganti SPN untuk mitra failover pencerminan database. Pencerminan basis data sudah tidak diaktifkan. Gunakan grup ketersediaan untuk penerapan baru. Microsoft. Data.SqlClient 5.0 dan versi selanjutnya

Host Name In Certificate mengubah nama yang digunakan untuk pencocokan sertifikat. Ia tidak mempercayai penerbit yang tidak dipercaya. Server Certificate menyematkan file sertifikat tertentu dan memerlukan pembaruan aplikasi saat sertifikat tersebut diganti.

Penggantian SPN yang keliru dapat mencegah autentikasi Kerberos atau melemahkan verifikasi identitas yang dimaksud. Perbaiki registrasi DNS dan SPN alih-alih membuat pengaturan override jika memungkinkan.

Buat string koneksi tetap pendek. Tambahkan opsi hanya ketika Anda dapat menyatakan perilaku mana yang diubah dan bagaimana beban kerja memverifikasi perilaku tersebut.

Tinjau perubahan opsi

Sebelum mengubah opsi dalam produksi:

  1. Catat string koneksi saat ini, versi driver, tipe endpoint, dan masalah yang diamati.
  2. Ubah satu perilaku dalam satu waktu.
  3. Uji pembentukan koneksi, autentikasi, validasi sertifikat, penggabungan, failover, pembatalan, dan eksekusi kueri.
  4. Ukur jumlah koneksi baru, waktu tunggu pool, latensi koneksi, dan jumlah error.
  5. Konfirmasi pengaturan pada setiap instance yang dideploy.

String koneksi adalah bagian dari kunci pool. Peluncuran bertahap dapat sementara menciptakan pool lama dan baru, yang meningkatkan total jumlah koneksi database fisik.

Konten terkait

  • Last updated on