string koneksi untuk Microsoft.Data.SqlClient

String koneksi Microsoft.Data.SqlClient menentukan endpoint dan database yang kompatibel dengan SQL Server mana yang akan digunakan, cara melakukan autentikasi, dan cara mengonfigurasi koneksi. Teruskan ke SqlConnection atau SqlConnectionStringBuilder.

Mulailah dengan empat keputusan:

Server dan database mana yang digunakan aplikasi ini?
Identitas apa yang digunakan aplikasi tersebut?
Bagaimana klien memvalidasi sertifikat server?
Beban kerja memerlukan perilaku koneksi seperti apa?

Jaga kredensial dan token akses agar tidak masuk ke string koneksi ketika metode autentikasi yang dipilih mendukung desain tersebut.

Pilih pola autentikasi

Gunakan pola paling sempit yang sesuai dengan penerapan.

Environment	Pola yang disukai	String koneksi inti
SQL Server di Windows di bawah identitas domain atau identitas Windows lokal	Autentikasi terintegrasi Windows	`Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true`
Stasiun kerja pengembang terhubung ke database SQL di Microsoft Fabric	Rantai kredensial default di Microsoft Entra ID	`Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Aplikasi yang dihosting di Azure dan terhubung ke Azure SQL	Identitas terkelola Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict`
Workstation pengembang yang terhubung ke Azure SQL	Rantai kredensial bawaan Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Alat desktop interaktif yang menghubungkan ke Azure SQL	Autentikasi interaktif Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict`
Lingkungan yang memerlukan autentikasi SQL	Nama pengguna dan kata sandi dari secret store	`Server=<server>;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true`

Microsoft. Data.SqlClient 7.0 dan versi selanjutnya memerlukan paket versi yang cocok Microsoft.Data.SqlClient.Extensions.Azure untuk mode otentikasi Microsoft Entra ID yang disediakan driver. Anda tidak memerlukan ekstensi tersebut jika kode aplikasi menyediakan token akses atau fungsi callback token akses.

Autentikasi juga memerlukan pengguna sisi basis data, izin, dan konfigurasi identitas. Untuk matriks pilihan lengkap dan pengaturan, lihat autentikasi Microsoft Entra ID dan autentikasi SQL Server.

Tentukan server dan database

Gunakan Server dan Database sebagai nama kata kunci kanonik. Pengemudi juga menerima alias seperti Data Source for Server dan Initial Catalog for Database.

Formulir server yang umum meliputi:

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

Lebih memilih protokol eksplisit, nama host, dan port untuk koneksi TCP produksi. Gunakan nama DNS yang stabil yang sesuai dengan sertifikat server, bukan alamat IP.

Untuk listener grup ketersediaan, grup failover, titik akhir Azure SQL, atau titik akhir TCP multi-alamat lainnya, tinjau juga MultiSubnetFailover pada opsi koneksi.

Konfigurasikan enkripsi dan validasi sertifikat

Microsoft.Data.SqlClient 4.0 dan versi yang lebih baru secara default menetapkan Encrypt ke true. Microsoft.Data.SqlClient 5.0 dan versi yang lebih baru juga mendukung Encrypt=Strict untuk server yang menegosiasikan TDS 8.0.

Gunakan:

Encrypt=Strict ketika server mendukung TDS 8.0 dan memiliki sertifikat yang dapat divalidasi oleh klien.
Encrypt=true untuk koneksi terenkripsi ke server lain yang didukung.
TrustServerCertificate=false, adalah default, untuk validasi sertifikat produksi.

Jangan gunakan TrustServerCertificate=true sebagai solusi koneksi umum. Channel tersebut dienkripsi tapi melewati validasi identitas server. Batasi pada lingkungan pengembangan terkontrol di mana sertifikat terpercaya tidak tersedia.

Untuk persyaratan server, perilaku versi, dan opsi sertifikat, lihat Enkripsi dan validasi sertifikat.

Pahami sintaks string koneksi

string koneksi adalah daftar pasangan kata kunci dan nilai yang dipisahkan dengan titik koma:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=true

Ikuti aturan berikut:

Nama kata kunci tidak membedakan huruf besar dan huruf kecil.
Nilai dapat peka terhadap huruf besar/kecil.
Titik koma terakhir bersifat opsional.
Mengutip nilai dengan tanda kutip tunggal atau ganda ketika berisi titik koma atau spasi putih di depan atau belakang.
Hindari kutipan yang membungkus nilai dengan menggandakannya.
Jangan gunakan kata kunci duplikat. Parser menggunakan nilai terakhir, yang membuat konfigurasi efektif sulit untuk ditinjau.

Set kata kunci dan alias yang diterima adalah milik penyedia. String koneksi yang diterima oleh Microsoft.Data.SqlClient mungkin tidak berfungsi dengan System.Data.SqlClient atau penyedia data lain.

Buat string koneksi dengan aman

Gunakan SqlConnectionStringBuilder saat kode perlu menambah, memvalidasi, atau mengganti nilai. Jangan menggabungkan nilai yang tidak dipercaya ke dalam string koneksi.

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

Pembuatnya:

Menolak kata kunci yang tidak didukung dan nilai tidak valid.
Memetakan alias ke properti kanonik.
Mengutip nilai jika diperlukan.
Mencegah suatu nilai menyisipkan kata kunci lain.

Builder tidak melindungi kata sandi atau token setelah masuk ke memori proses. Juga tidak menentukan apakah pengaturan server, identitas, atau sertifikat aman.

Simpan informasi koneksi di luar kode

Muat string koneksi dari sistem konfigurasi yang digunakan oleh aplikasi. Aplikasi .NET saat ini umumnya menggunakan variabel lingkungan, user secrets untuk pengembangan lokal, Azure App Configuration, dan konfigurasi yang didukung Azure Key Vault.

Ikuti aturan berikut:

Jangan menyimpan kata sandi, rahasia klien, token akses, atau string koneksi produksi.
Lebih memilih metode autentikasi berbasis identitas yang tidak memerlukan kata sandi dalam string koneksi.
Batasi akses ke sumber konfigurasi.
Putar rahasia yang tersimpan dan restart atau refresh aplikasi yang menyimpan rahasia tersebut.
Jangan mencatat string koneksi ke log, pengecualian, pelacakan, atau telemetri.
Biarkan Persist Security Info=false, menjadi default, sehingga koneksi yang dibuka tidak menampilkan nilai sensitif keamanan melalui string koneksi-nya.

Untuk penyedia konfigurasi .NET, lihat Konfigurasi di .NET. Untuk kontrol tambahan, lihat Lindungi informasi koneksi.

Jaga kunci kolam tetap stabil

Connection pooling menggunakan konfigurasi koneksi yang tepat sebagai bagian dari kunci pool-nya. String yang setara dapat membuat pool terpisah ketika teksnya berbeda, termasuk ketika kata kunci muncul dalam urutan yang berbeda.

Buat satu string koneksi kanonis saat aplikasi dijalankan dan gunakan kembali. Jangan menambahkan ID permintaan, nama pengguna, token akses, atau nilai per-permintaan lainnya ke string. Untuk aturan kunci lengkap, lihat SQL Server connection pooling.

Pisahkan pengaturan koneksi dan perintah

Sebuah string koneksi mengontrol pembentukan koneksi dan perilaku sesi. Sebuah perintah mengendalikan satu operasi SQL.

Requirement	Mengonfigurasi pada
Waktu yang diberikan untuk membangun koneksi atau mendapatkannya dari pool	`Connect Timeout` opsi koneksi
Batas waktu eksekusi perintah bawaan	`Command Timeout` opsi koneksi, jika didukung oleh versi driver
Batas waktu untuk satu perintah	CommandTimeout
Pembatalan oleh penelepon	`CancellationToken` diteruskan ke API asinkron
Kebijakan coba ulang untuk membuka koneksi atau menjalankan perintah	Logika retry yang dapat dikonfigurasi pada `SqlConnection` atau `SqlCommand`

Jangan anggap timeout yang lebih lama sebagai logika percobaan ulang. Batas waktu tunggu membatasi satu kali menunggu. Upaya ulang memulai upaya lain dan harus memiliki batas yang jelas serta aman untuk dilakukan berulang kali.

Tinjau perilaku sensitif versi

Versi driver	Perubahan string koneksi
4.0	`Encrypt` defaultnya adalah `true`.
5.0	`Encrypt=Strict` dan `HostNameInCertificate` tersedia. `SqlConnectionStringBuilder.Encrypt` menggunakan `SqlConnectionEncryptOption`.
5.1	`ServerCertificate` dapat mencocokkan sertifikat server dengan sebuah file.
5.2	AccessTokenCallback tersedia untuk token yang disediakan aplikasi dan dapat diperbarui.
7.0	Autentikasi Microsoft Entra ID yang disediakan oleh driver dipindahkan ke `Microsoft.Data.SqlClient.Extensions.Azure`.
7.0.2	Driver inti dan paket pendampingnya menggunakan versi yang diselaraskan.

Gunakan versi driver stabil yang didukung dan baca catatan rilis sebelum pembaruan. Untuk versi saat ini, lihat siklus hidup dukungan driver SqlClient.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-21