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, database SQL di Microsoft Fabric, dan Gudang di Microsoft Fabric. Ini didistribusikan sebagai paket NuGet, berkembang secara independen dari runtime .NET, dan menggantikan System.Data.SqlClient untuk pengembangan baru. Ini menyediakan koneksi, perintah, pemrosesan hasil, transaksi, salinan massal, dan fitur khusus SQL Server untuk 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. Ini membaca nama server dan database dari IConfiguration, sehingga nilainya berasal dari penyedia konfigurasi yang dihubungkan oleh host, seperti appsettings.json, variabel lingkungan, Azure App Configuration, dan pengaturan yang didukung Key Vault. Konfigurasi ini menggabungkan fitur-fitur berikut:

  • Keamanan Lapisan Transport (TLS).
  • Identitas yang dikelola
  • Ketahanan koneksi idle.
  • Percobaan ulang koneksi awal melalui logika retry yang dapat dikonfigurasi (CRL), dengan logging terstruktur.
  • Percobaan ulang tingkat perintah untuk kesalahan sementara yang terjadi di tengah kueri.
  • Pemulihan cepat grup failover.
  • Panggilan asinkron yang menerima token pembatalan.

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.

Cuplikan mengasumsikan sebuah proyek yang menargetkan .NET 8 atau versi yang lebih baru dan mereferensikan paket Microsoft.Data.SqlClient dan Microsoft.Data.SqlClient.Extensions.Azure versi 7.1.1. Host, seperti .NET Generic Host atau ASP.NET Core, menyediakan ILogger dan IConfiguration, dan konfigurasi memasok nama server di Sql:Server dan nama database di Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

Metode mengembalikan nama database yang dihubungkannya dan mencatatnya ke Connected to database <database>. Ketika percobaan ulang terjadi, ia juga mencatat satu peringatan per percobaan beserta exception yang memicunya.

Cara kerja setiap bagian dari cuplikan ini:

  • Target: Setiap endpoint SQL Database Engine 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. Diperlukan SQL Server 2022 dan versi yang lebih baru, Azure SQL Database, Azure SQL Managed Instance, atau database SQL di Microsoft Fabric. Gunakan SqlConnectionEncryptOption.Mandatory untuk server lama.
  • ActiveDirectoryManagedIdentity: Hanya berfungsi di tempat yang tersedia identitas terkelola, seperti Azure App Service, Azure Functions, atau mesin virtual Azure. Untuk pengembangan lokal, gunakan SqlAuthenticationMethod.ActiveDirectoryDefault, yang mencoba Azure CLI, autentikasi Visual Studio, dan sumber kredensial lainnya. Biarkan tetap di luar produksi karena menguji setiap sumber akan memperlambat koneksi. Untuk informasi lebih lanjut, lihat Gunakan autentikasi default.
  • MultiSubnetFailover = true: Mencoba koneksi TCP ke semua alamat IP yang terselesaikan secara paralel dan menggunakan koneksi pertama yang berhasil, menghindari langkah berurutan per IP yang lambat. Atur untuk Azure SQL Database, Azure SQL Managed Instance, database SQL di Microsoft Fabric, availability group listeners, dan failover cluster instances. Aman untuk target single-IP. Ini tidak didukung untuk instance bernama, protokol selain TCP, instance dengan lebih dari 64 alamat IP, atau pencerminan basis data yang tidak disarankan lagi. Gunakan grup ketersediaan AlwaysOn sebagai gantinya. Untuk informasi lebih lanjut, lihat Ketersediaan tinggi dan pemulihan bencana serta Menonaktifkan Resolusi IP Jaringan Transparan.
  • ConnectRetryCount = 3 dan ConnectRetryInterval = 10: Driver mencoba ulang kegagalan sementara yang memenuhi syarat selama Open(), dan menghubungkan kembali koneksi idle yang terputus pada perintah berikutnya. Jumlah defaultnya adalah 1. Tiga percobaan yang berjarak 10 detik dapat bertahan melewati konfigurasi ulang atau failover yang lebih lama. Driver hanya menaikkan 1 ke 2 ketika nama server berakhir di domain Azure SQL yang dikenal, seperti .database.windows.net, sehingga alias DNS kustom tetap bernilai 1.
  • openRetry: Ditugaskan ke SqlConnection.RetryLogicProvider, ini menambahkan backoff eksponensial sekitar Open(). Driver menghentikan percobaan internal saat ConnectTimeout habis, jadi skenario terburuk sebelum OpenAsync melempar error adalah lima percobaan hingga 30 detik masing-masing, ditambah backoff. Setiap upaya reconnect idle juga menjalankan kebijakan penuh openRetry, dan ketika kebijakan tersebut menghabiskan seluruh percobaan ulangnya, pemulihan idle berakhir.
  • Serverless auto-pause: Untuk Azure SQL Database serverless, tingkatkan ConnectTimeout hingga minimal 60 detik. Yang pertama Open() dapat gagal dengan kesalahan 40613 saat database dipulihkan, dan openRetry mencobanya kembali. Timeout sisi klien muncul sebagai error -2, yang tidak dicoba ulang, jadi setiap upaya koneksi harus bertahan lebih lama daripada proses melanjutkan kembali. Untuk informasi lebih lanjut, lihat Auto-pause dan auto-resume.
  • commandRetry: Terapkan pada SqlCommand.RetryLogicProvider hanya saat memutar ulang perintah aman: operasi baca, MERGE yang dilindungi oleh kunci natural, upsert melalui prosedur tersimpan, dan operasi idempoten lainnya. Sistem melewatkan percobaan ulang di dalam transaksi, sehingga kode aplikasi harus mencoba ulang transaksi multi-pernyataan. ExecuteReader dan ExecuteScalar hanya mencoba ulang jika kesalahan dikembalikan sebelum set hasil pertama dimulai. ExecuteNonQuery mencoba ulang seluruh panggilan.
  • Daftar kesalahan sementara: Pengaturan TransientErrors menggantikan daftar bawaan. Untuk memperluasnya, gunakan SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 dan versi lebih baru).
  • Retrying event: Retrying dipicu sebelum setiap percobaan ulang dengan jumlah percobaan ulang, penundaan berikutnya, dan pengecualian sejauh ini. Rutekannya ke ILogger atau pipeline telemetri Anda.
  • Pengecualian: Metode ini tidak menangkap pengecualian. Penyedia yang kelelahan melempar AggregateException dengan pengecualian dari setiap percobaan. Kesalahan non-transien menyebar sebagai eksepsi asli. Pemanggil mencatatnya sekali bersama konteks permintaan lainnya.
  • Pembatalan: CancellationToken menghentikan jeda tunggu penyedia di antara percobaan ulang. Itu tidak mengganggu penantian pengemudi ConnectRetryInterval dalam satu Open kali percobaan. Untuk informasi lebih lanjut, lihat Pemrograman asinkron.
  • Masa aktif provider: Cuplikan ini membuat provider percobaan ulang di setiap panggilan agar tetap mandiri. Dalam aplikasi, buat objek tersebut sekali dan gunakan kembali.

Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:

Pelajari tugas inti akses data

Setelah Anda terhubung, gunakan artikel-artikel berikut secara berurutan:

  1. Gunakan perintah untuk memilih bentuk hasil dan jalankan Transact-SQL (T-SQL).
  2. Konfigurasikan parameter agar sesuai dengan kontrak basis data.
  3. Ambil data dengan SqlDataReader untuk memproses baris dan beberapa hasil.
  4. Modifikasi data dengan prosedur tersimpan untuk menggunakan parameter output dan nilai kembali.
  5. Gunakan pemrograman asinkron dan pembatalan untuk menambahkan pembatalan penelepon dan timeout terbatas.
  6. Tangani kesalahan dan pesan sebelum Anda menambahkan percobaan ulang atau diagnostik produksi.

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.
  • 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.
  • Connection pooling: Aktif secara default. Pool V2 opt-in sedang dalam evaluasi.
  • 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.
  • Identitas aplikasi: Atur SqlConnection.RegisteredApplication untuk mengidentifikasi pustaka atau alat Anda untuk SQL Server (Microsoft.Data.SqlClient 7.1 dan versi lebih baru).

Get started

Artikel Deskripsi
Mulai dengan driver SqlClient Siapkan proyek, buat database, hubungkan, kueri, dan tambahkan ketahanan koneksi.
Instal, perbarui, dan sebarkan Microsoft. Data.SqlClient Instal paket NuGet, pilih rilis, perbarui driver, dan siapkan output deployment.
Siklus hidup dukungan Tinjau versi driver yang didukung dan tanggal dukungan.
Migrasi dari System.Data.SqlClient ke Microsoft. Data.SqlClient Perbarui referensi paket, namespace, konfigurasi, dan perilaku driver yang diubah.
Microsoft. Data.SqlClient namespace dan kompatibilitas Pahami bagaimana SqlClient mengimplementasikan ADO.NET dan kompatibilitasnya dengan System.Data.SqlClient, .NET, dan SQL Server.
Apa yang baru di Microsoft. Data.SqlClient Temukan rilis terbaru, perubahan peningkatan besar, dan catatan rilis upstream.

Mengonfigurasi dan menyambungkan

Artikel Deskripsi
Hubungkan ke sumber data Buka dan kelola koneksi, serta menanggapi perubahan status koneksi.
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.
Menangani kesalahan dan pesan Deteksi kesalahan dan terima pesan informasional.

Autentikasi dan amankan

Artikel Deskripsi
Praktik terbaik keamanan untuk Microsoft.Data.SqlClient 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
Eksekusi perintah Jalankan pernyataan SQL yang diparameterisasi dan prosedur tersimpan.
DataAdapters dan DataReaders Alirkan kumpulan hasil atau isi struktur data yang tidak terhubung.
Jalankan beberapa perintah dengan SqlBatch Kirim kumpulan perintah yang terurut dan memproses hasilnya.
Data stream Transfer nilai biner, teks, XML, dan JSON besar tanpa membuffer seluruh nilai.
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.
Beberapa Set Hasil Aktif (MARS) Sisipkan beberapa batch secara berselang-seling pada satu koneksi.

Jenis data

Artikel Deskripsi
Pemetaan tipe data SQL Server Petakan tipe SQL Server ke tipe .NET dan System.Data.SqlTypes
Data JSON Kirim dan mengambil tipe data SQL Server json.
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 peristiwa di SqlClient Pantau koneksi aktif, koneksi dalam pool, dan metrik driver lainnya.
Aktifkan pelacakan sumber peristiwa Rekam kejadian pengemudi secara rinci untuk diagnosis.
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.
Repositori GitHub Microsoft.Data.SqlClient Baca kode sumber driver, catatan rilis, dan sampel.
Contoh Microsoft.Data.SqlClient Jelajahi contoh C# untuk API driver.
Repositori GitHub runtime .NET Baca sumber untuk pustaka runtime .NET.

Meminta fitur

Untuk mengajukan permintaan fitur, buat issue di repositori GitHub Microsoft.Data.SqlClient.

Konten terkait

  • Terakhir diperbarui pada