Microsoft. Data.SqlClient untuk SQL Server

Mengunduh ADO.NET

Microsoft. Data.SqlClient adalah penyedia data .NET yang didukung untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, dan database SQL di Microsoft Fabric. Ini didistribusikan sebagai paket NuGet, berkembang secara independen dari runtime .NET, dan menggantikan System.Data.SqlClient untuk pengembangan baru. Gunakan untuk membuka koneksi, menjalankan perintah, memproses hasil, mengelola transaksi, memuat data secara massal, dan menggunakan fitur khusus SQL Server dari aplikasi .NET.

Pilih titik awal Anda

Garis besar produksi untuk Azure SQL

Gunakan cuplikan ini sebagai titik awal untuk jalur akses data Azure SQL yang berorientasi pada produksi. Ia membaca nama server dan database dari IConfiguration, sehingga nilai-nilai tersebut berasal dari penyedia konfigurasi apa pun yang dihubungkan host (appsettings.json, variabel lingkungan, Azure App Configuration, pengaturan yang didukung Key Vault, dan sebagainya). Konfigurasi ini menggabungkan Transport Layer Security (TLS), identitas terkelola, ketahanan koneksi idle, percobaan ulang koneksi awal melalui logika percobaan ulang yang dapat dikonfigurasi (CRL) dengan pencatatan terstruktur, percobaan ulang pada tingkat perintah untuk kesalahan sementara yang terjadi di tengah kueri, dan pemulihan grup failover yang cepat.

Untuk keamanan yang lebih tinggi dan mendukung konfigurasi lintas lingkungan, simpan informasi koneksi di luar kode Anda. Dalam produksi, simpan informasi koneksi di sistem konfigurasi aplikasi Anda, dan gunakan Azure Key Vault untuk nilai-nilai sensitif. Untuk informasi selengkapnya, lihat Melindungi informasi koneksi.

Cuplikan C# dalam artikel ini tidak menyertakan direktif using dan pembungkus kelas agar singkat.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Cuplikan ini menargetkan endpoint SQL Database Engine apa pun yang dikonfigurasi untuk autentikasi Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, database SQL di Microsoft Fabric, dan SQL Server 2022 dan versi selanjutnya di Azure Virtual Machines atau diaktifkan oleh Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict memilih enkripsi TDS 8.0. Itu membutuhkan Microsoft. Data.SqlClient 5.0 dan versi lebih baru serta server yang mendukung TDS 8.0 (SQL Server 2022 dan versi berikutnya, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric). Kembali ke SqlConnectionEncryptOption.Mandatory saat Anda terhubung ke server lama.

ConnectRetryCount dan ConnectRetryInterval Aktifkan ketahanan koneksi idle: Setelah Open() berhasil, driver secara transparan menghubungkan kembali koneksi idle yang terputus pada perintah berikutnya. Mereka tidak mengulangi Open() awal. Percobaan ulang koneksi awal berasal dari penyedia openRetry yang ditetapkan ke SqlConnection.RetryLogicProvider. Kedua fitur ini saling melengkapi.

Event Retrying pada setiap penyedia dijalankan sebelum setiap percobaan ulang dan membawa jumlah percobaan ulang, penundaan sebelum percobaan berikutnya, serta pengecualian yang telah diamati sejauh ini. Arahkan ke ILogger atau pipeline telemetri Anda agar siklus percobaan ulang tetap terlihat di lingkungan produksi.

Tetapkan MultiSubnetFailover = true kapan targetnya adalah Azure SQL Database, Azure SQL Managed Instance, database SQL di Microsoft Fabric, listener availability group, atau failover cluster instance. Ia memilih jalur kode koneksi paralel yang mencoba koneksi TCP ke semua alamat IP yang terselesaikan secara paralel dan menggunakan koneksi pertama yang berhasil, menghindari langkah berurutan per IP yang lambat yang dapat menghentikan koneksi tersebut. Pada target single-IP, pengaturannya aman. MultiSubnetFailover tidak didukung ketika Anda terhubung ke instance bernama, melalui protokol selain TCP, atau ke instance yang dikonfigurasi dengan lebih dari 64 alamat IP. Anda juga tidak dapat menggunakannya dengan pencerminan database, yang sudah tidak digunakan di semua versi SQL Server yang didukung. Gunakan grup ketersediaan AlwaysOn sebagai gantinya. Untuk informasi lebih lanjut, lihat Ketersediaan tinggi dan pemulihan bencana serta Menonaktifkan Resolusi IP Jaringan Transparan.

Jika targetnya adalah Azure SQL Database serverless dengan auto-pause yang diaktifkan, tingkatkan ConnectTimeout menjadi setidaknya 60 detik. Database yang dijeda secara otomatis akan aktif kembali saat Open() pertama, dan Open() pertama tersebut dapat gagal dengan kesalahan 40613 saat database aktif kembali. Error 40613 ada di daftar error transien bawaan, jadi openRetry coba ulang. Timeout di sisi klien muncul sebagai kesalahan -2, yang tidak termasuk dalam daftar tersebut, jadi openRetry tidak akan dapat menyelamatkan Open() yang mengalami habis waktu di tengah proses resume. Upaya koneksi individu harus cukup lama untuk mencakup resume. Untuk informasi lebih lanjut, lihat Auto-pause dan auto-resume.

Percobaan ulang pada tingkat perintah adalah keputusan pemanggil, untuk setiap perintah. Lampirkan commandRetry ke SqlCommand.RetryLogicProvider hanya jika aman untuk memutar ulang perintah: operasi baca, MERGE yang dilindungi oleh kunci alami, upsert melalui prosedur tersimpan, dan operasi idempoten lainnya. Penyedia perintah bawaan tidak melakukan percobaan ulang ketika transaksi sedang aktif, sehingga transaksi multistatement harus dicoba ulang oleh kode aplikasi yang dapat membuka kembali transaksi tersebut. Pengaturan TransientErrors menggantikan daftar kesalahan bawaan driver; untuk memperluas baseline bawaan, gunakan SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 dan versi lebih baru).

Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:

Fitur utama

  • Dukungan .NET modern: Berjalan pada versi .NET dan .NET Framework saat ini. Untuk rincian per versi, lihat Siklus hidup Dukungan.
  • Terenkripsi secara default: Koneksi terenkripsi TLS dengan Encrypt=true sebagai default. Atur Encrypt=Strict untuk enkripsi TDS 8.0 di Microsoft. Data.SqlClient 5.0 dan versi lebih baru.
  • autentikasi Microsoft Entra ID: Koneksi tanpa kata sandi dengan identitas terkelola, perwakilan layanan, interaktif, terintegrasi, rantai kredensial default, dan alur token akses.
  • Kerberos dan NTLM: autentikasi Windows terintegrasi untuk Active Directory lokal dan skenario lama.
  • Always Encrypted: Enkripsi sisi klien untuk kolom sensitif, dengan enklave aman opsional untuk operasi di tempat.
  • Penyalinan massal: Penyisipan berthroughput tinggi dengan SqlBulkCopy.
  • Keandalan koneksi: Percobaan ulang koneksi bawaan (ConnectRetryCount dan ConnectRetryInterval) serta logika percobaan ulang opsional yang dapat dikonfigurasi untuk koneksi dan perintah.
  • Tipe data SQL Server kaya: datetimeoffset, sql_variant, JSON, vektor, spasial, XML, dan parameter bernilai tabel.
  • Diagnostik: Pelacakan sumber kejadian, penghitung diagnostik, statistik penyedia, dan panduan pemecahan masalah khusus.

Get started

Artikel Deskripsi
Mulai menggunakan driver SqlClient Siapkan proyek, buat database, hubungkan, kueri, dan tambahkan ketahanan koneksi.
Gambaran umum driver SqlClient Pelajari bagaimana Microsoft. Data.SqlClient masuk ke dalam ADO.NET.
Unduh Microsoft. Data.SqlClient Instal paket NuGet dan temukan rilis sumber.
Siklus hidup dukungan Tinjau versi driver yang didukung dan tanggal dukungan.
namespace Microsoft.Data.SqlClient Migrasi dari System.Data.SqlClient dan tinjau perbedaan namespace.

Mengonfigurasi dan menyambungkan

Artikel Deskripsi
Hubungkan ke sumber data Buka dan kelola koneksi ke SQL Server dan Azure SQL.
String koneksi Konfigurasikan server, basis data, autentikasi, enkripsi, dan perilaku koneksi.
Enkripsi dan validasi sertifikat Konfigurasikan koneksi terenkripsi dan validasi sertifikat server.
Pooling koneksi SQL Server Gunakan kembali koneksi fisik secara efisien.
Peristiwa koneksi Tanggapi status koneksi dan pesan informasi.

Autentikasi dan amankan

Artikel Deskripsi
Keamanan SQL Server Tinjau panduan autentikasi, otorisasi, dan keamanan aplikasi.
Autentikasi Microsoft Entra Terhubung dengan alur identitas terkelola, prinsipal layanan, kata sandi, dan interaktif.
Lindungi informasi koneksi Jaga agar kredensial dan pengaturan koneksi tidak masuk ke kode aplikasi.
Selalu Terenkripsi Lindungi nilai kolom sensitif dari sistem basis data.
Selalu Terenkripsi dengan enklave yang aman Jalankan beragam operasi pada data terenkripsi dengan enklave aman.

Ambil dan perbarui data

Artikel Deskripsi
Perintah dan parameter Jalankan pernyataan SQL yang diparameterisasi dan prosedur tersimpan.
DataAdapters dan DataReaders Alirkan kumpulan hasil atau isi struktur data yang tidak terhubung.
Transaksi dan konkurensi Gunakan transaksi lokal dan terdistribusi serta kontrol konkurensi.
Ambil informasi skema basis data Temukan koleksi skema dan pembatasan.
Operasi penyalinan massal Muat set data besar secara efisien dengan SqlBulkCopy.
Parameter bernilai tabel Kirim beberapa baris ke pernyataan atau prosedur tersimpan yang diparameterkan.
Pemrograman asinkron Gunakan operasi koneksi, perintah, dan data asinkron.
Beberapa Set Hasil Aktif (MARS) Sisipkan beberapa batch secara berselang-seling pada satu koneksi.

Jenis data

Artikel Deskripsi
Pemetaan tipe data ADO.NET Petakan tipe Common Language Runtime (CLR) umum ke dalam tipe penyedia dan SQL Server.
Tipe data SQL Server Bekerja dengan nilai dan tipe System.Data.SqlTypes khusus SQL Server.
Data JSON Kirim dan ambil tipe data SQL Serverjson.
Data vektor Kirim dan ambil nilai vektor.
Data XML Baca, tulis, dan parameterisasi nilai XML.
Data biner dan bernilai besar Alirkan dan perbarui data biner, FILESTREAM, dan data bernilai besar.

Keandalan dan diagnostik

Artikel Deskripsi
Logika coba lagi yang dapat dikonfigurasi Coba ulang kegagalan koneksi sementara dan perintah dengan kebijakan terbatas.
Ketersediaan tinggi dan pemulihan bencana Terhubung ke pendengar grup ketersediaan dan mitra failover.
Penghitung diagnostik Pantau koneksi aktif, koneksi dalam pool, dan metrik driver lainnya.
Aktifkan pelacakan sumber peristiwa Rekam kejadian pengemudi secara rinci untuk diagnosis.
Pelacakan data Lacak operasi ADO.NET dan akses data.
Panduan pemecahan masalah SqlClient Mendiagnosis masalah umum koneksi dan driver.
Notifikasi kueri Terima notifikasi saat hasil kueri berubah.

fitur SQL Server

Artikel Deskripsi
Fitur SQL Server dan ADO.NET Jelajahi fitur khusus SQL Server yang tersedia melalui SqlClient.
LocalDB Sambungkan ke instance SQL Server Express LocalDB.
Penemuan dan Klasifikasi Data Baca metadata klasifikasi sensitivitas dari kumpulan hasil.

Referensi dan sumber daya

Artikel Deskripsi
Referensi API Microsoft.Data.SqlClient Telusuri referensi API .NET untuk driver.
Pengalihan AppContext Konfigurasikan perilaku kompatibilitas dan keamanan.
Temukan informasi tambahan SqlClient Temukan kode sumber, dukungan, dan sumber daya komunitas.

Konten terkait

  • Last updated on