string koneksi untuk Microsoft.Data.SqlClient

Microsoft.Data.SqlClient string koneksi adalah daftar pasangan kunci-nilai keyword=value yang dipisahkan oleh titik koma. Teruskan ke SqlConnection atau SqlConnectionStringBuilder:

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

Sebuah string koneksi menjawab empat pertanyaan:

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

Artikel ini membahas pilihan-pilihan tersebut dan aturan yang digunakan driver untuk membaca teks. Untuk setiap kata kunci, sinonimnya, dan defaultnya, lihat Opsi Koneksi. Untuk membuat dan mengubah string koneksi dalam kode, lihat Connection string builders.

Pilih pola autentikasi

Gunakan pola yang sesuai dengan deployment. Ganti setiap placeholder, seperti <server>, dengan nilai Anda.

Environment Pattern Rangkaian koneksi
SQL Server di Windows dengan domain atau identitas lokal Windows Autentikasi terintegrasi Windows Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
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 default di Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
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
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>;Password=<password>;Encrypt=true

Autentikasi terintegrasi Windows terhubung menggunakan identitas proses. Untuk aplikasi desktop atau konsol, biasanya pengguna yang sudah masuk. Untuk aplikasi web atau layanan Windows, itu adalah application pool atau akun layanan. Impersonasi bisa mengubah identitas. Berikan izin login dan database pada identitas yang sebenarnya digunakan aplikasi Anda.

Ketiga bentuk autentikasi terintegrasi Windows ini setara:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Jika sebuah string mengatur Integrated Security=true dan juga mengatur User ID dan Password, driver menggunakan Windows authentication dan mengabaikan nama pengguna serta kata sandi.

Microsoft. Data.SqlClient 7.0 dan versi berikutnya membutuhkan paket versi yang cocok Microsoft.Data.SqlClient.Extensions.Azure untuk metode autentikasi Microsoft Entra ID yang disediakan driver. Anda tidak membutuhkan paket itu ketika kode aplikasi menyediakan token akses atau callback token akses.

Untuk nilai yang diterima Authentication , lihat opsi Autentikasi. Autentikasi juga memerlukan pengguna database, izin, dan konfigurasi identitas di server. Untuk langkah pengaturan, lihat autentikasi Microsoft Entra ID dan autentikasi SQL Server.

Tentukan server dan database

Server dan Database adalah nama kata kunci yang paling mudah dibaca. Pembuat menulisnya sebagai padanan kanoniknya, Data Source dan Initial Catalog. Keempat nama tersebut bekerja dalam sebuah string koneksi.

Atur Server ke salah satu bentuk berikut:

Form Example Gunakan
Nama host Server=sql.example.com Instance default di port 1433.
Nama host dan port Server=tcp:sql.example.com,1433 Port TCP tertentu. Pisahkan port dengan koma, bukan titik dua.
Instans bernama Server=sql.example.com\SALES Instans bernama. Driver meminta nomor port kepada layanan SQL Server Browser pada port UDP 1434.
Server lokal Server=(local) atau Server=. Instans bawaan pada komputer lokal.
LocalDB Server=(localdb)\MSSQLLocalDB SQL Server Express LocalDB di Windows. Koneksi tidak terenkripsi, bahkan dengan Encrypt=Mandatory, dan Encrypt=Strict gagal.
Pipa bernama Server=np:\\sql.example.com\pipe\sql\query Koneksi pipa bernama di Windows.

Gunakan tcp:, nama host yang sepenuhnya terkualifikasi, dan port eksplisit dalam produksi. Gunakan nama DNS yang sesuai dengan sertifikat server, bukan alamat IP, karena validasi sertifikat membandingkan nama server dalam string koneksi dengan nama-nama dalam sertifikat.

Saat Anda terhubung ke Azure SQL Database dengan autentikasi SQL dan nama pengguna dalam format user@servername, bagian servername harus cocok dengan server di Server.

Untuk pendengar grup ketersediaan atau instance klaster failover, juga tinjau Multi Subnet Failover di opsi Koneksi.

Konfigurasikan enkripsi dan validasi sertifikat

Kata kunci menerima Encrypt nilai-nilai berikut, tanpa membedakan huruf besar/kecil:

Nilai Nilai Builder Meaning
Strict Strict Menggunakan TDS 8.0. Mengenkripsi koneksi sebelum login dan selalu memvalidasi sertifikat server.
Mandatory, true, yes True Mengenkripsi koneksi. Ini adalah nilai default.
Optional, false, no False Mengenkripsi seluruh koneksi hanya ketika server membutuhkan enkripsi. Ketika server mendukung enkripsi tetapi tidak mewajibkannya, hanya paket login yang dienkripsi.

Gunakan Strict ketika server mendukung TDS 8.0 dan memiliki sertifikat yang dapat divalidasi oleh klien. Azure SQL Database dan SQL database di Microsoft Fabric mendukungnya. Koneksi LocalDB tidak terenkripsi, bahkan dengan Mandatory, dan Strict gagal.

Nilai Encrypt dan Trust Server Certificate digabungkan sebagai berikut:

Enkripsi Sertifikat Server Kepercayaan Result
Optional false Ketika server memerlukan enkripsi, seluruh koneksi dienkripsi, dan sertifikat server harus divalidasi. Jika tidak, koneksi akan gagal. Ketika server mendukung enkripsi tetapi tidak mewajibkannya, hanya paket login yang dienkripsi, dan driver tidak memvalidasi sertifikat server kecuali koneksi menggunakan AccessToken atau AccessTokenCallback. Ketika server tidak mendukung enkripsi, tidak ada yang terenkripsi.
Optional true Ketika server membutuhkan enkripsi, seluruh koneksi dienkripsi. Ketika server mendukung enkripsi tetapi tidak memerlukannya, hanya paket login yang terenkripsi. Driver tidak memvalidasi sertifikat server.
Mandatory false Enkripsi hanya terjadi ketika sertifikat server tervalidasi. Jika tidak, koneksi akan gagal.
Mandatory true Enkripsi selalu terjadi, tetapi driver tidak memvalidasi sertifikat server.
Strict Diabaikan Enkripsi selalu terjadi, dan sertifikat server harus divalidasi. Jika tidak, koneksi akan gagal.

Jangan atur Trust Server Certificate=true untuk memperbaiki kesalahan koneksi di produksi. Saluran tersebut dienkripsi, tetapi tidak mengonfirmasi identitas server. Batasi hal ini pada lingkungan pengembangan di mana sertifikat tepercaya tidak tersedia.

Jika nama server dalam Data Source tidak sesuai dengan sertifikat, atur Host Name In Certificate ke nama pada sertifikat. SqlClient hanya memeriksanya ketika nama server tidak cocok, dan tidak menyematkan sertifikat. Untuk menerima hanya satu sertifikat tertentu, atur Server Certificate ke jalur ke file PEM, DER, atau CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Untuk aturan validasi lengkap, lihat Enkripsi dan validasi sertifikat.

Gunakan pengumpulan koneksi

Pooling aktif secara bawaan. Saat Anda membuka koneksi SqlConnection, driver mengambil koneksi fisik dari pool yang sesuai dengan koneksi tersebut. Saat Anda menutup atau melepaskan koneksi, koneksi fisik kembali ke pool alih-alih ditutup. Pembukaan koneksi yang dipool melewati koneksi jaringan, TLS handshake, dan login.

Ikuti aturan berikut:

  • Buka koneksi tepat sebelum Anda membutuhkannya, dan lepaskan segera setelah selesai, dengan using atau await using. Koneksi yang tidak dilepas akan tetap dialokasikan, dan pool bisa habis.

  • Bangun string koneksi sekali saat startup dan gunakan kembali. Kunci pool mencakup teks tepat dari string koneksi, sehingga urutan kata kunci yang berbeda, sinonim, atau nilai per permintaan seperti ID permintaan atau nama pengguna akan membuat pool terpisah. Pembangun menulis satu bentuk kanonik. Untuk informasi lebih lanjut, lihat Pertahankan satu string koneksi kanonis.

  • Akan ada pool terpisah untuk setiap identitas Windows di bawah autentikasi terintegrasi, setiap instance SqlCredential, dan setiap nilai AccessToken. Gunakan metode yang disediakan Authentication oleh driver atau yang digunakan kembali AccessTokenCallback alih-alih menetapkan AccessToken pada setiap koneksi.

  • Cari koneksi yang belum dibuang sebelum memunculkan Max Pool Size, yang secara default menjadi 100. Ketika setiap koneksi dalam pool digunakan, Open menunggu hingga Connect Timeout lalu melempar InvalidOperationException:

    Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

  • Rencanakan kapasitas server untuk setiap pool. Setiap proses, atau setiap domain aplikasi di .NET Framework, memiliki poolnya sendiri. Jumlah koneksi ke server dapat mencapai Max Pool Size dikalikan dengan pool di setiap proses dan jumlah instance aplikasi.

  • Jangan menggunakan Pooling=false sebagai solusi sementara untuk mengatasi masalah pooling. Setiap kali dibuka kemudian melakukan login penuh.

Untuk menutup koneksi pooled yang terlalu lama diam, lihat Batasi waktu idle koneksi. Untuk kunci pool, penentuan ukuran, pembersihan, dan transaksi, 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 Kata kunci
Batas waktu default untuk perintah pada koneksi Command Timeout Kata kunci
Batas waktu untuk satu perintah CommandTimeout
Pembatalan oleh penelepon CancellationToken diteruskan ke metode asinkron
Kebijakan coba ulang untuk membuka koneksi atau menjalankan perintah Logika retry yang dapat dikonfigurasi pada SqlConnection atau SqlCommand

Timeout yang lebih lama bukanlah logika retry. Batas waktu tunggu membatasi satu kali menunggu. Percobaan ulang memulai percobaan lain, dan harus dibatasi serta aman untuk diulang.

Laporkan identitas aplikasi

Application Name mengatur nama yang dilapor APP_NAME()oleh server. Gunakan satu nama stabil untuk setiap workload yang diterapkan. Kerangka kerja dan alat yang membuka koneksi untuk sebuah aplikasi juga dapat melaporkan dirinya sendiri melalui properti RegisteredApplication, yang tidak memiliki kata kunci string koneksi. Untuk informasi lebih lanjut, lihat Laporkan identitas aplikasi.

Buat string koneksi dengan aman

Gunakan SqlConnectionStringBuilder saat kode menambah atau mengubah nilai. Jangan gabungkan teks yang tidak dipercaya ke dalam string koneksi, karena titik koma dalam teks tersebut dapat menambah atau mengganti kata kunci. Pembuat memvalidasi nilai, memetakan sinonim ke kata kunci kanonik, dan mengutip setiap nilai agar nilai tersebut tidak dapat ditambahkan kata kunci. Sebagai contoh, lihat Connection string builders.

Simpan informasi koneksi di luar kode

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

Ikuti aturan berikut:

  • Jangan menyimpan kata sandi, rahasia klien, token akses, atau string koneksi produksi.
  • Pilih metode autentikasi yang tidak memerlukan kata sandi di 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, sebagai default, sehingga koneksi yang dibuka tidak menampilkan kata sandi melalui ConnectionString propertinya.

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

Aturan parsing

Pengemudi menerapkan aturan berikut:

  • Kata kunci tidak membedakan huruf besar/kecil. DATABASE, Database, dan database adalah kata kunci yang sama.
  • Banyak kata kunci memiliki sinonim. Server dan Data Source atur nilai yang sama. Artikel opsi Koneksi mencantumkan sinonim untuk setiap kata kunci.
  • Ketika kata kunci muncul lebih dari sekali, nilai terakhir yang menang. Sinonim dihitung sebagai kata kunci yang sama.
  • Driver mengabaikan spasi di sekitar kata kunci dan di sekitar nilai yang tidak dikutip.
  • Titik koma di belakang bersifat opsional.
  • Kata kunci yang tidak dikenali oleh driver akan melemparkan ArgumentException dengan pesan Keyword not supported.

Nilai dapat peka terhadap huruf besar-kecil, tergantung pada kata kunci. Kata sandi bersifat sensitif huruf besar/kecil. Encrypt=STRICT dan Encrypt=strict sama.

Program ini menunjukkan bagaimana builder menormalkan kata kunci, menyelesaikan duplikat, dan mengutip karakter khusus. Tab .NET Framework menggunakan C# 7.3. Untuk membuat proyek yang menjalankan sampel, lihat Buat proyek.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

Outputnya adalah:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

Baris pertama menunjukkan setiap sinonim digantikan oleh kata kunci kanoniknya: timeout oleh Connect Timeout, User ID oleh uid, Initial Catalog oleh DATABASE, dan Data Source oleh server.

Nilai kutipan

Lampirkan nilai dengan tanda kutip ganda (") atau tanda kutip tunggal (') ketika nilai tersebut berisi titik koma, dimulai atau diakhiri dengan spasi, atau dimulai atau diakhiri dengan tanda kutip. Di dalam nilai yang dikutip, tulis tanda kutip yang mengapitnya dua kali.

Nilai Bentuk string koneksi
a;b Password="a;b"
abc' Password="abc'"
say "hi" Password='say "hi"'
a;b'c"d Password="a;b'c""d"

Aturan mengutip mudah salah paham. Tetapkan nilai melalui SqlConnectionStringBuilder properti dan biarkan pembangun memberikan penawaran. Untuk informasi lebih lanjut, lihat Membangun string koneksi dengan aman.

Tentukan nilai Boolean

Kata kunci yang mengambil nilai Boolean menerima true, false, yes, dan no, tanpa membedakan huruf besar/kecil. Integrated Security juga menerima sspi, yang berarti true. Builder menulis True atau False.

Gunakan kata kunci dari driver lain

Microsoft.Data.SqlClient tidak menerima kata kunci ODBC atau OLE DB seperti Driver dan Provider. Hapus kata kunci ini saat Anda memindahkan string koneksi dari driver lain. System.Data.SqlClientstring koneksi bekerja di Microsoft.Data.SqlClient, dengan perbedaan berikut:

  • Encryptdefault ke Mandatory dalam Microsoft. Data.SqlClient. Server dengan sertifikat yang tidak tepercaya gagal validasi sertifikat. Instal sertifikat tepercaya pada server.
  • Di .NET, Network Library, Connection Reset, dan Transparent Network IP Resolution tidak didukung. Buang semuanya.
  • Context Connection=true tidak didukung.
  • Asynchronous Processing bukan kata kunci yang didukung dan melempar ArgumentException. Lepaskan. Metode asinkron bekerja tanpa hal tersebut.
  • Type System Version=SQL Server 2000 tidak didukung. Membuat koneksi memunculkan ArgumentException. Gunakan Latest, SQL Server 2012, SQL Server 2008, atau SQL Server 2005.

Konten terkait

  • Terakhir diperbarui pada