Pengantar Namespace Microsoft.Data.SqlClient

Mengunduh ADO.NET

Namespace Microsoft.Data.SqlClient pada dasarnya adalah versi baru dari namespace System.Data.SqlClient. Microsoft.Data.SqlClient umumnya mempertahankan API yang sama dan kompatibilitas mundur dengan System.Data.SqlClient. Untuk bermigrasi dari System.Data.SqlClient ke Microsoft.Data.SqlClient, untuk sebagian besar aplikasi, itu sederhana. Tambahkan dependensi NuGet pada Microsoft.Data.SqlClient dan perbarui referensi dan using pernyataan ke Microsoft.Data.SqlClient.

Ada beberapa perbedaan dalam API yang kurang digunakan dibandingkan dengan System.Data.SqlClient yang mungkin memengaruhi beberapa aplikasi. Untuk perbedaan tersebut, lihat lembar contekan porting yang berguna.

Referensi API

Detail API Microsoft.Data.SqlClient dapat ditemukan di Browser .NET API.

Catatan rilis untuk 7.0

Ini adalah rilis ketersediaan umum Microsoft.Data.SqlClient 7.0, tonggak utama untuk penyedia data .NET untuk SQL Server. Rilis ini mengatasi masalah yang paling banyak diupvote dalam sejarah repositori — yaitu dengan menghilangkan dependensi Azure dari paket inti — memperkenalkan autentikasi SSPI yang dapat diintegrasikan, meningkatkan perutean Azure, dan memberikan peningkatan performa baca asinkron.

Juga dirilis sebagai bagian dari tonggak pencapaian ini:

• Versi Microsoft.Data.SqlClient.Extensions.Abstractions 1.0.0 telah dirilis. Lihat catatan rilis.
• Microsoft.Data.SqlClient.Extensions.Azure 1.0.0 dirilis. Lihat catatan rilis.
• Microsoft.Data.SqlClient.Internal.Logging 1.0.0 dirilis. Lihat catatan rilis.
• Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider versi 7.0.0 telah dirilis. Lihat catatan rilis.

Perubahan yang mengganggu kompatibilitas di 7.0

Dependensi Azure dihapus dari paket inti

Apa yang Berubah:

• Paket inti Microsoft.Data.SqlClient tidak lagi bergantung pada Azure.Core, Azure.Identity, atau dependensi transitifnya (misalnya, Microsoft.Identity.Client, Microsoft.Web.WebView2). Fungsionalitas autentikasi Azure Active Directory / Entra ID (ActiveDirectoryAuthenticationProvider dan jenis terkait) telah diekstrak ke dalam paket baru Microsoft.Data.SqlClient.Extensions.Azure . (#1108, #3680, #3902, #3904, #3908, #3917, #3982, #3978, #3986)
• Dua paket tambahan diperkenalkan untuk mendukung pemisahan ini: Microsoft.Data.SqlClient.Extensions.Abstractions (jenis bersama antara driver inti dan ekstensi) dan Microsoft.Data.SqlClient.Internal.Logging (infrastruktur pelacakan ETW bersama).
  (#3626, #3628, #3967, #4038)

Manfaat Siapa:

• Semua pengguna mendapat manfaat dari paket inti yang jauh lebih ringan. Sebelumnya, rantai dependensi Azure menarik banyak assembly bahkan untuk aplikasi yang hanya membutuhkan konektivitas SQL Server dasar. Ini adalah masalah terbuka yang paling banyak mendapatkan suara di repositori.
• Pengguna yang tidak menggunakan autentikasi ID Entra tidak lagi membawa rakitan terkait Azure dalam output build mereka.
• Pengguna yang menggunakan autentikasi ID Entra sekarang dapat mengelola versi dependensi Azure secara independen dari driver inti.

Dampak:

• Aplikasi yang menggunakan autentikasi ID Entra (misalnya, ActiveDirectoryInteractive, , ActiveDirectoryDefault, ActiveDirectoryManagedIdentity, dll.) sekarang harus menginstal Microsoft.Data.SqlClient.Extensions.Azure paket NuGet secara terpisah:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure

• Tidak ada perubahan kode yang diperlukan selain menambahkan referensi paket.
• Jika metode autentikasi ID Entra digunakan tanpa paket Azure terinstal, driver sekarang menyediakan pesan kesalahan yang dapat ditindaklanjuti yang memandu pengguna untuk menginstal paket yang benar.

Perubahan yang merusak lainnya di 7.0

• Mengembalikan visibilitas publik enum interop internal (IoControlCodeAccess dan IoControlTransferType) yang secara tidak sengaja dibuat publik selama penggabungan proyek. (#3900)

Fitur Baru di 7.0

Autentikasi yang dapat dicolokkan dengan SspiContextProvider

Apa yang Berubah:

• Menambahkan properti publik SspiContextProvider pada SqlConnection, menyelesaikan pekerjaan ekstensibilitas SSPI dimulai pada 6.1.0. Aplikasi sekarang dapat menyediakan penyedia konteks SSPI kustom untuk autentikasi terintegrasi, memungkinkan negosiasi tiket Kerberos kustom dan skenario autentikasi nama pengguna/kata sandi NTLM. (#2253, #2494)

Manfaat Siapa:

• Pengguna yang melakukan autentikasi di domain yang tidak tepercaya, komputer yang tidak bergabung dengan domain, atau lingkungan lintas platform yang sulit untuk mengonfigurasi autentikasi terintegrasi.
• Pengguna yang beroperasi dalam kontainer yang membutuhkan negosiasi Kerberos manual tanpa menyebarkan sidecar atau mekanisme penyegaran tiket eksternal.
• Pengguna yang memerlukan autentikasi nama pengguna/kata sandi NTLM ke SQL Server, yang tidak disediakan driver secara asli.

Dampak:

• Aplikasi dapat mengatur kustom SspiContextProvider pada SqlConnection sebelum membuka koneksi:

var connection = new SqlConnection(connectionString);
connection.SspiContextProvider = new MyKerberosProvider();
connection.Open();

• Penyedia menangani pertukaran token autentikasi selama autentikasi terintegrasi. Perilaku autentikasi yang ada tidak berubah ketika tidak ada penyedia kustom yang diatur. Lihat SspiContextProvider_CustomProvider.cs untuk implementasi sampel.
• Catatan:SspiContextProvider adalah bagian dari kunci kumpulan koneksi. Pastikan implementasi mengembalikan identitas yang konsisten per sumber daya.

Performa baca asinkron: Multipleks paket (pratinjau)

Apa yang Berubah:

• Pengembangan berkelanjutan dalam multipleks paket dengan perbaikan bug dan peningkatan stabilitas sejak 6.1.0, serta sakelar konteks aplikasi baru untuk kontrol partisipasi. (#3534, #3537, #3605)

Manfaat Siapa:

• Aplikasi yang melakukan pembacaan asinkron besar (ExecuteReaderAsync dengan kumpulan hasil besar, skenario streaming, atau pengambilan data massal).

Dampak:

• Multipleks paket disediakan melalui dua sakelar fitur opsional:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

• Mengatur kedua sakelar ke false mengaktifkan jalur pemrosesan asinkron baru. Secara default, driver menggunakan perilaku yang ada (kompatibel).

Dukungan Perutean yang Ditingkatkan

Apa yang Berubah:

• Menambahkan dukungan untuk perutean yang ditingkatkan, fitur TDS yang memungkinkan server mengalihkan koneksi ke server tertentu dan database pada saat proses login. (#3641, #3969, #3970, #3973)

Manfaat Siapa:

• Pengguna yang terhubung ke lingkungan Azure yang menggunakan replika pembaca yang ditentukan dan penyeimbangan beban berbasis gateway.

Dampak:

• Penggunaan alur yang ditingkatkan dinegosiasikan secara otomatis saat login ketika server mendukungnya. Tidak diperlukan perubahan kode aplikasi.

Dukungan untuk .NET 10

Apa yang Berubah:

• Alur dan suite pengujian yang diperbarui untuk mengkompilasi driver menggunakan .NET 10 SDK. (#3686)

Manfaat Siapa:

• Pengembang menargetkan .NET 10 pada hari pertama.

Dampak:

• SqlClient 7.0 mengkompilasi dan menguji terhadap .NET 10, memastikan kompatibilitas.

Peristiwa diagnostik bertipe kuat pada .NET Framework

Apa yang Berubah:

• Diaktifkan SqlClientDiagnosticListener untuk SqlCommand pada .NET Framework, menutup kesenjangan kemampuan observasi yang sudah berlangsung lama di mana peristiwa diagnostik sebelumnya hanya dihasilkan pada .NET Core. (#3658)

• Membawa 15 kelas peristiwa diagnostik bertipe kuat dalam _namespace_ Microsoft.Data.SqlClient.Diagnostics — yang awalnya diperkenalkan untuk .NET Core di 6.0 — ke .NET Framework sebagai bagian dari penggabungan basis kode. Kedua platform sekarang menggunakan model kejadian dengan pengetikan tegas yang sama. Jenis mencakup perintah, koneksi, dan peristiwa siklus hidup transaksi:

  • SqlClientCommandBefore, SqlClientCommandAfter, SqlClientCommandError
  • SqlClientConnectionOpenBefore, SqlClientConnectionOpenAfter, SqlClientConnectionOpenError
  • SqlClientConnectionCloseBefore, SqlClientConnectionCloseAfter, SqlClientConnectionCloseError
  • SqlClientTransactionCommitBefore, SqlClientTransactionCommitAfter, SqlClientTransactionCommitError
  • SqlClientTransactionRollbackBefore, SqlClientTransactionRollbackAfter, SqlClientTransactionRollbackError

  (#3493)

Manfaat Siapa:

• Pengguna .NET Framework berlangganan SqlClientDiagnosticListener peristiwa untuk pengamatan, pelacakan terdistribusi, atau telemetri kustom. Pengguna ini sekarang memiliki paritas dengan .NET Core, mendapatkan IntelliSense, keamanan waktu kompilasi, dan menghilangkan kebutuhan untuk mengakses payload diagnostik melalui refleksi atau pencarian kamus.

Dampak:

• Pada .NET Framework, SqlCommand sekarang memancarkan peristiwa diagnostik yang sama yang sebelumnya hanya tersedia di .NET Core. Pelanggan berlangganan peristiwa DiagnosticListener (misalnya, Microsoft.Data.SqlClient.WriteCommandBefore) menerima objek dengan tipe yang kuat.

listener.Subscribe(new Observer<KeyValuePair<string, object?>>(kvp =>
{
    if (kvp.Value is SqlClientCommandBefore before)
    {
        Console.WriteLine($"Executing: {before.Command.CommandText}");
    }
}));

• Jenis mengimplementasikan IReadOnlyList<KeyValuePair<string, object>> untuk kompatibilitas mundur dengan kode yang mengiterasi properti secara generik.

Penambahan lain dalam 7.0

• Menambahkan SqlConfigurableRetryFactory.BaselineTransientErrors properti statis yang mengekspos daftar kode kesalahan sementara default sebagai ReadOnlyCollection<int>, sehingga lebih mudah untuk memperluas daftar default dengan kode kesalahan khusus aplikasi. (#3903)

• Menambahkan pengalihan konteks aplikasi Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault untuk mengatur MultiSubnetFailover=true secara global tanpa memodifikasi string koneksi. (#3841)

• Menambahkan pengalih konteks aplikasi Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner agar klien dapat mengabaikan informasi mitra failover yang disediakan server di Grup Ketersediaan Dasar. (#3625)

• Mengaktifkan Ekstensi Fitur Agen Pengguna (pilihan melalui Switch.Microsoft.Data.SqlClient.EnableUserAgent). (#3606)

Perubahan dalam 7.0

Penghentian SqlAuthenticationMethod.ActiveDirectoryPassword

Apa yang Berubah:

• SqlAuthenticationMethod.ActiveDirectoryPassword (alur ROPC) sekarang ditandai [Obsolete] dan akan menghasilkan peringatan kompilator. Ini selaras dengan langkah Microsoft menuju autentikasi multifaktor wajib. (#3671)

Manfaat Siapa:

• Tim bergerak menuju autentikasi yang lebih kuat, tanpa kata sandi, atau sesuai dengan MFA.

Dampak:

• Jika Anda menggunakan Authentication=Active Directory Password, migrasikan ke alternatif yang didukung:

Skenario	Autentikasi yang Direkomendasikan
Aplikasi interaktif / desktop	Active Directory Interactive
Layanan ke layanan	Active Directory Service Principal
Beban kerja yang dihosting di Azure	Active Directory Managed Identity
Lingkungan Pengembang / CI	Active Directory Default

• Lihat Menyambungkan ke Azure SQL dengan autentikasi Microsoft Entra untuk informasi selengkapnya.

Dukungan Platform Target 7.0

• .NET Framework 4.6.2+ (Windows x86, Windows x64, Windows ARM64)
• .NET 8.0+ (Windows x86, Windows x64, Windows ARM, Windows ARM64, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 7.0.

Catatan rilis untuk 6.1

Fitur baru di 6.1

Menambahkan dukungan jenis data vektor SQL Server khusus

Apa yang berubah:

• Komunikasi vektor yang dioptimalkan antara MDS dan SQL Server 2025 (17.x), menggunakan format biner kustom melalui protokol TDS (#3433, #3443).

• Mengurangi beban pemrosesan dibandingkan dengan dukungan vektor berbasis JSON yang ada.

• Dukungan awal untuk vektor floating point presisi tunggal 32-bit.

Siapa yang menguntungkan:

• Aplikasi yang memindahkan himpunan data vektor besar melihat peningkatan bermanfaat pada waktu pemrosesan dan persyaratan memori.
• API khusus vektor siap mendukung representasi numerik di masa depan dengan tampilan dan nuansa yang konsisten.

Efek:

• Mengurangi waktu transmisi dan pemrosesan untuk operasi vektor versus JSON menggunakan SQL Server 2025 (17.x):

  • Pembacaan: Peningkatan 50 kali
  • Menulis: Peningkatan 3,3 kali lipat
  • Salinan Massal: Peningkatan 19x
  • (Teramati dengan kolom vektor berukuran maksimum 1998, dan 10.000 rekaman untuk setiap operasi.)

• Peningkatan penggunaan memori disebabkan oleh penghapusan serialisasi/deserialisasi JSON dan kembung representasi string.

• Untuk kompatibilitas mundur dengan implementasi SQL Server Vector sebelumnya, aplikasi mungkin terus menggunakan string JSON untuk mengirim/menerima data vektor, meskipun mereka tidak melihat peningkatan performa apa pun yang dicatat sebelumnya.

Dukungan target .NET Standard 2.0 yang direvisi

Apa yang berubah:

• Dukungan untuk menargetkan .NET Standard 2.0 telah kembali (#3381)
• Dukungan sebelumnya telah dihapus dalam rilis 6.0, dengan komunitas menyuarakan kekhawatiran.

Siapa yang menguntungkan:

• Pustaka yang bergantung pada MDS mungkin dapat dengan mulus menargetkan salah satu kerangka kerja berikut:
  • .NET Standar 2.0
  • .NET Framework 4.6.2 ke atas
  • .NET 8.0
  • .NET 9.0
• Aplikasi harus terus menargetkan runtime.
  • Dukungan kerangka kerja target MDS .NET Standard 2.0 tidak menyertakan implementasi aktual, dan tidak dapat digunakan dengan runtime.
  • Proses build/publish aplikasi harus selalu memilih implementasi runtime MDS .NET/.NET Framework yang sesuai.
  • Tindakan kustom build/publish yang secara keliru mencoba menyebarkan DLL referensi .NET Standard 2.0 MDS pada saat runtime tidak didukung.

Efek:

• Pustaka yang menargetkan .NET Standard 2.0 tidak lagi menerima peringatan seperti:

  warning NU1701: Package 'Microsoft.Data.SqlClient 6.0.2' was restored using '.NETFramework,Version=v4.6.1, .NETFramework,Version=v4.6.2, .NETFramework,Version=v4.7, .NETFramework,Version=v4.7.1, .NETFramework,Version=v4.7.2, .NETFramework,Version=v4.8, .NETFramework,Version=v4.8.1' instead of the project target framework '.NETStandard,Version=v2.0'. This package may not be fully compatible with your project.
  

Penambahan lainnya

• Menambahkan dukungan untuk casing khusus dengan titik akhir Fabric. (#3084)

6.1 Dukungan platform target

• .NET Framework 4.6.2+ (Windows Arm64, Windows x86, Windows x64)
• .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 6.1.

Catatan rilis untuk 6.0

Memutus perubahan dalam 6.0

• Menjatuhkan dukungan untuk .NET Standard. #2386
• Menghentikan dukungan untuk .NET 6 #2927
• Telah menghapus referensi UWP (UAP). #2483
• Menghilangkan dukungan debugging sisi klien SQL 2000 untuk .NET Framework #2981, #2940

Fitur baru di 6.0

• Menambahkan dukungan untuk jenis data JSON #2916, #2892, #2891, #2880, #2882, #2829, #2830
• Menambahkan dukungan untuk .NET 9 #2946
• Menambahkan jenis Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic di .NET. #2226
• Menambahkan dukungan DateOnly dan TimeOnly ke DataTable sebagai parameter terstruktur. #2258
• Menambahkan dukungan untuk SqlConnectionOverrides di API OpenAsync() #2433
• Lokalisasi ditambahkan di Ceko, Polandia, dan Turki #2987
• Menambahkan objek TokenCredential untuk memanfaatkan caching token di ActiveDirectoryAuthenticationProvider. #2380
• Menambahkan readme ke paket NuGet #2826
• Mengaktifkan audit paket NuGet melalui sumber audit NuGet.org #3024
• Menambahkan sampel kode SqlCommand_BeginExecuteReader yang hilang #3009
• Menambahkan jejak cakupan untuk GenerateSspiClientContext. #2497, #2725

Dukungan jenis data JSON

Dukungan jenis data JSON sekarang tersedia di Microsoft.Data.SqlClient v6.0. Rilis ini memperkenalkan jenis SqlJson yang tersedia sebagai ekstensi untuk System.Data.SqlDbTypes:

using System;
using System.Data.SqlTypes;
using System.Text.Json;

namespace Microsoft.Data.SqlTypes
{
    /// <summary>
    /// Represents the Json data type in SQL Server.
    /// </summary>
    public class SqlJson : INullable
    {
        /// <summary>
        /// Parameterless constructor. Initializes a new instance of the SqlJson class which
        /// represents a null JSON value.
        /// </summary>
        public SqlJson() { }

        /// <summary>
        /// Takes a <see cref="string"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonString"></param>
        public SqlJson(string jsonString) { }

        /// <summary>
        /// Takes a <see cref="JsonDocument"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonDoc"></param>
        public SqlJson(JsonDocument jsonDoc) { }

        /// <inheritdoc/>
        public bool IsNull => throw null;

        /// <summary>
        /// Represents a null instance of the <see cref="SqlJson"/> type.
        /// </summary>
        public static SqlJson Null { get { throw null; } }

        /// <summary>
        /// Gets the string representation of the JSON content of this <see cref="SqlJson" /> instance.
        /// </summary>
        public string Value { get ; }
    }
}

Jenis data JSON mendukung operasi pembacaan, penulisan, streaming, dan penyalinan massal.

Memperkenalkan SqlClientDiagnostics

Jenis baru tersedia di namespace Microsoft.Data.SqlClient.Diagnostics yang menyediakan kumpulan pasangan kunci-nilai yang bertipe kuat. Jenis-jenis ini dapat ditangkap dengan menggunakan aplikasi untuk mengumpulkan peristiwa diagnostik yang dipancarkan oleh driver. Rilis ini memperkenalkan jenis berikut:

• SqlClientCommandBefore
• SqlClientCommandAfter
• SqlClientCommandError
• SqlClientConnectionOpenBefore
• SqlClientConnectionOpenAfter
• SqlClientConnectionOpenError
• SqlClientConnectionCloseBefore
• SqlClientConnectionCloseAfter
• SqlClientConnectionCloseError
• SqlClientTransactionCommitBefore
• SqlClientTransactionCommitAfter
• SqlClientTransactionCommitError
• SqlClientTransactionRollbackBefore
• SqlClientTransactionRollbackAfter
• SqlClientTransactionRollbackError

Menambahkan dukungan untuk Penggantian Koneksi di OPENAsync() API

Perilaku bawaan SqlConnection.OpenAsync() dapat diubah untuk menonaktifkan penundaan sepuluh detik dan percobaan ulang koneksi otomatis yang dipicu oleh kesalahan sementara.

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    await sqlConnection.OpenAsync(SqlConnectionOverrides.OpenWithoutRetry, cancellationToken);
}

Dukungan platform Target 6.0

• .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: 6.0 Catatan Rilis.

Catatan rilis untuk 5.2

Fitur baru di 5.2

• Menambahkan dukungan SqlDiagnosticListener pada .NET Standard. #1931
• Menambahkan properti RowsCopied64 baru ke SqlBulkCopy. #2004Baca selengkapnya
• Menambahkan API baru AccessTokenCallBack ke SqlConnection. #1260Baca selengkapnya
• Menambahkan dukungan untuk SuperSocketNetLib opsi registri untuk Enkripsi pada .NET di Windows. #2047
• Menambahkan SqlBatch dukungan pada .NET 6+ #1825, #2223Baca selengkapnya
• Menambahkan dukungan autentikasi Identitas Pekerjaan #2159, #2264
• Menambahkan dukungan Pelokalan pada .NET #2210
• Menambahkan dukungan untuk pengurutan abjad Georgian #2194
• Menambahkan dukungan untuk sistem Big Endian #2170
• Menambahkan dukungan .NET 8 #2230
• Menambahkan versi eksplisit untuk dependensi versi .NET utama pada System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0, dan System.Diagnostics.DiagnosticSource 8.0.0 #2303
• Menambahkan kemampuan untuk menghasilkan simbol debug dalam paket file terpisah #2137

Menambahkan properti RowsCopied64 baru ke SqlBulkCopy

SqlBulkCopy memiliki properti RowsCopied64 baru yang mendukung long jenis nilai.

Perilaku yang ada SqlBulkCopy.RowsCopied tidak berubah. Ketika nilai melebihi int.MaxValue, RowsCopied dapat mengembalikan angka negatif.

Contoh penggunaan:

    using (SqlConnection srcConn = new SqlConnection(srcConstr))
    using (SqlCommand srcCmd = new SqlCommand("select top 5 * from employees", srcConn))
    {
        srcConn.Open();
        using (DbDataReader reader = srcCmd.ExecuteReader())
        {
            using (SqlBulkCopy bulkcopy = new SqlBulkCopy(dstConn))
            {
                bulkcopy.DestinationTableName = dstTable;
                SqlBulkCopyColumnMappingCollection ColumnMappings = bulkcopy.ColumnMappings;

                ColumnMappings.Add("EmployeeID", "col1");
                ColumnMappings.Add("LastName", "col2");
                ColumnMappings.Add("FirstName", "col3");

                bulkcopy.WriteToServer(reader);
                long rowsCopied = bulkcopy.RowsCopied64;
            }
        }
    }

Menambahkan properti AccessTokenCallBack baru ke SqlConnection

SqlConnection mendukung TokenCredential autentikasi dengan memperkenalkan properti baru AccessTokenCallBack sebagai Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>> delegasi untuk mengembalikan token akses autentikasi gabungan.

Contoh penggunaan:

using Microsoft.Data.SqlClient;
using Azure.Identity;

const string defaultScopeSuffix = "/.default";
string connectionString = GetConnectionString();
DefaultAzureCredential credential = new();
using SqlConnection connection = new(connectionString);

connection.AccessTokenCallback = async (authParams, cancellationToken) =>
{
    string scope = authParams.Resource.EndsWith(defaultScopeSuffix)
        ? authParams.Resource
        : $"{authParams.Resource}{defaultScopeSuffix}";
    AccessToken token = await credential.GetTokenAsync(
        new TokenRequestContext([scope]),
        cancellationToken);

    return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
}

connection.Open();
Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
Console.WriteLine("State: {0}", connection.State);

SqlBatch API

Contoh penggunaan:

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        string str = "Data Source=(local);Initial Catalog=Northwind;"
        + "Integrated Security=SSPI;Encrypt=False";
        RunBatch(str);
    }

    static void RunBatch(string connString)
    {
        using var connection = new SqlConnection(connString);
        connection.Open();

        var batch = new SqlBatch(connection);

        const int count = 10;
        const string parameterName = "parameter";
        for (int i = 0; i < count; i++)
        {
            var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
            batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
            batch.BatchCommands.Add(batchCommand);
        }

        // Optionally Prepare
        batch.Prepare();

        var results = new List<int>(count);
        using (SqlDataReader reader = batch.ExecuteReader())
        {
            do
            {
                while (reader.Read())
                {
                    results.Add(reader.GetFieldValue<int>(0));
                }
            } while (reader.NextResult());
        }
        Console.WriteLine(string.Join(", ", results));
    }
}

5.2 Dukungan target platform

• .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 5.2.

Catatan rilis untuk 5.1

Perubahan yang memutus kompatibilitas dalam 5.1

• Menjatuhkan dukungan untuk .NET Core 3.1. #1704#1823

Fitur baru di 5.1

• Dukungan untuk DateOnly dan TimeOnly telah ditambahkan untuk nilai SqlParameter dan GetFieldValue. #1813
• Menambahkan dukungan untuk TLS 1.3 untuk .NET Core dan SNI Native. #1821
• Pengaturan ServerCertificate telah ditambahkan untuk Encrypt=Mandatory atau Encrypt=Strict. #1822Baca selengkapnya
• Menambahkan dukungan Windows Arm64 saat menargetkan .NET Framework. #1828

Sertifikat server

Nilai bawaan pengaturan koneksi ServerCertificate adalah string kosong. Ketika Encrypt diatur ke Mandatory atau Strict, ServerCertificate dapat digunakan untuk menentukan jalur pada sistem file ke file sertifikat untuk dicocokkan dengan sertifikat TLS/SSL server. Sertifikat yang ditentukan harus sama persis agar valid. Format sertifikat yang diterima adalah PEM, , DERdan CER. Berikut contoh penggunaannya:

"Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer"

5.1 Dukungan platform target

• .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Azure Resource Manager, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 5.1.

Catatan rilis untuk 5.0

Perubahan mendasar dalam 5.0

• Dukungan yang dihilangkan untuk .NET Framework 4.6.1 #1574
• Menambahkan dependensi pada paket Microsoft.SqlServer.Server . Dependensi baru ini dapat menyebabkan konflik namespace layanan jika aplikasi Anda mereferensikan namespace layanan tersebut dan masih memiliki referensi paket (langsung atau tidak langsung) ke System.Data.SqlClient dari .NET Core.
• Kelas yang dihilangkan dari Microsoft.Data.SqlClient.Server namespace dan digantikan dengan jenis yang didukung dari paket Microsoft.SqlServer.Server.#1585. Kelas dan enum yang terpengaruh adalah:
  • Microsoft.Data.SqlClient.Server.IBinarySerialize -> Microsoft.SqlServer.Server.IBinarySerialize
  • Microsoft.Data.SqlClient.Server.InvalidUdtException -> Microsoft.SqlServer.Server.InvalidUdtException
  • Microsoft.Data.SqlClient.Server.SqlFacetAttribute -> Microsoft.SqlServer.Server.SqlFacetAttribute
  • Microsoft.Data.SqlClient.Server.SqlFunctionAttribute -> Microsoft.SqlServer.Server.SqlFunctionAttribute
  • Microsoft.Data.SqlClient.Server.SqlMethodAttribute -> Microsoft.SqlServer.Server.SqlMethodAttribute
  • Microsoft.Data.SqlClient.Server.SqlUserDefinedAggregateAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute
  • Microsoft.Data.SqlClient.Server.SqlUserDefinedTypeAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute
  • (enum) Microsoft.Data.SqlClient.Server.DataAccessKind -> Microsoft.SqlServer.Server.DataAccessKind
  • (enum) Microsoft.Data.SqlClient.Server.Format -> Microsoft.SqlServer.Server.Format
  • (enum) Microsoft.Data.SqlClient.Server.SystemDataAccessKind -> Microsoft.SqlServer.Server.SystemDataAccessKind

Fitur baru di 5.0

• Menambahkan dukungan untuk TDS8. Untuk menggunakan TDS 8, pengguna harus menentukan Encrypt=Strict di string koneksi. #1608Baca selengkapnya
• Tambah dukungan untuk menentukan SPN Server dan SPN Server Failover pada koneksi. #1607Baca selengkapnya
• Menambahkan dukungan untuk alias saat menargetkan .NET Core di Windows. #1588Baca selengkapnya
• Menambah SqlDataSourceEnumerator. #1430, Baca selengkapnya
• Menambahkan sakelar AppContext baru untuk menekan peringatan TLS yang tidak aman. #1457, Baca selengkapnya

Keamanan TDS 8.0 tertingkat

Untuk menggunakan TDS 8.0, tentukan Encrypt=Strict dalam string koneksi. Mode ketat menonaktifkan TrustServerCertificate (selalu diperlakukan sebagai False dalam mode Ketat). HostNameInCertificate telah ditambahkan untuk membantu beberapa skenario "Strict mode". TDS 8.0 dimulai dan melanjutkan semua komunikasi server di dalam koneksi TLS yang aman dan terenkripsi.

Nilai Enkripsi Baru telah ditambahkan untuk mengklarifikasi perilaku enkripsi koneksi. Encrypt=Mandatory setara dengan Encrypt=True dan mengenkripsi koneksi selama negosiasi koneksi TDS. Encrypt=Optional setara dengan Encrypt=False dan hanya mengenkripsi koneksi jika server memberi tahu klien bahwa enkripsi diperlukan selama negosiasi koneksi TDS.

Untuk informasi selengkapnya tentang mengenkripsi koneksi ke server, lihat Enkripsi dan validasi sertifikat di Microsoft.Data.SqlClient.

HostNameInCertificatedapat ditentukan dalam string koneksi saat menggunakan alias untuk terhubung dengan enkripsi ke server yang memiliki sertifikat server dengan nama yang berbeda atau nama subjek alternatif daripada nama yang digunakan oleh klien untuk mengidentifikasi server (alias DNS, misalnya). Contoh penggunaan: HostNameInCertificate=MyDnsAliasName

Server SPN

Saat menyambungkan di lingkungan yang memiliki topografi domain/forest yang unik, Anda mungkin memiliki persyaratan khusus untuk SPN Server. Pengaturan string koneksi ServerSPN/Server SPN dan FailoverServerSPN/Failover Server SPN dapat digunakan untuk mengganti SPN server yang dihasilkan otomatis yang digunakan selama autentikasi terintegrasi di lingkungan domain

Dukungan untuk alias SQL

Pengguna dapat mengonfigurasi Alias dengan menggunakan Pengelola Konfigurasi SQL Server. Alias ini disimpan di registri Windows dan sudah didukung saat menargetkan .NET Framework. Rilis ini membawa dukungan untuk alias saat menargetkan .NET atau .NET Core di Windows.

Dukungan enumerasi sumber data SQL

Menyediakan mekanisme untuk menghitung semua instans SQL Server yang tersedia dalam jaringan lokal.

using Microsoft.Data.Sql;
static void Main()
  {
    // Retrieve the enumerator instance and then the data.
    SqlDataSourceEnumerator instance =
      SqlDataSourceEnumerator.Instance;
    System.Data.DataTable table = instance.GetDataSources();

    // Display the contents of the table.
    DisplayData(table);

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
  }

  private static void DisplayData(System.Data.DataTable table)
  {
    foreach (System.Data.DataRow row in table.Rows)
    {
      foreach (System.Data.DataColumn col in table.Columns)
      {
        Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
      }
      Console.WriteLine("============================");
    }
  }

Menekan peringatan TLS yang tidak aman

Peringatan keamanan akan ditampilkan di konsol jika versi TLS di bawah 1.2 digunakan untuk bernegosiasi dengan server. Peringatan ini dapat dihilangkan pada koneksi SQL sementara Encrypt = false dengan mengaktifkan pengaturan AppContext berikut pada startup aplikasi.

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Dukungan untuk platform target versi 5.0

• .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 5.0.

Catatan rilis untuk 4.1

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 4.1.

Fitur baru di 4.1

Memperkenalkan protokol pengesahan Tidak Ada

Protokol pengesahan baru yang disebut None diizinkan dalam string koneksi. Protokol ini memungkinkan pengguna untuk mengabaikan sertifikasi enklave untuk VBS enklave. Ketika protokol ini diatur, properti URL pengesahan enklave bersifat opsional.

Contoh string koneksi:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

4.1 Dukungan platform target

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis untuk 4.0

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 4.0.

Perubahan signifikan di versi 4.0

• Mengubah Encrypt properti string koneksi menjadi true secara default. #1210Baca selengkapnya
• Driver sekarang melemparkan SqlException menggantikan AggregateException untuk mode autentikasi direktori aktif. #1213
• Properti koneksi usang Asynchronous Processing dihilangkan dari .NET Framework. #1148
• Sakelar pengaman Configurable Retry Logic dilepas. #1254Baca selengkapnya
• Dukungan yang dihilangkan untuk .NET Core 2.1 #1272
• [.NET Framework] Pengecualian tidak dilemparkan jika ID Pengguna disediakan di string koneksi saat menggunakan Active Directory Integrated autentikasi #1359

Fitur baru di 4.0

Mengenkripsi nilai default yang diatur ke true

Nilai Encrypt default pengaturan koneksi telah diubah dari false ke true. Dengan meningkatnya penggunaan database cloud dan kebutuhan untuk memastikan koneksi tersebut aman, saatnya untuk perubahan yang melanggar kompatibilitas mundur ini.

Pastikan koneksi gagal saat enkripsi diperlukan

Dalam skenario di mana pustaka enkripsi klien dinonaktifkan atau tidak tersedia, koneksi tidak terenkripsi dapat terjadi ketika Encrypt diatur ke true atau server memerlukan enkripsi.

Sakelar Konteks Aplikasi untuk menggunakan protokol default Sistem

TLS 1.3 tidak didukung oleh driver; oleh karena itu, protokol tersebut telah dihapus dari daftar protokol yang didukung secara default. Pengguna dapat beralih kembali untuk memaksa penggunaan protokol klien Sistem Operasi, dengan mengaktifkan sakelar Konteks Aplikasi berikut:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Mengaktifkan pengikatan parameter yang dioptimalkan

Microsoft.Data.SqlClient memperkenalkan API baru SqlCommand , EnableOptimizedParameterBinding untuk meningkatkan performa kueri dengan sejumlah besar parameter. Properti ini dinonaktifkan secara default. Saat diatur ke true, nama parameter tidak dikirim ke instans SQL Server saat perintah dijalankan.

public class SqlCommand
{
    public bool EnableOptimizedParameterBinding { get; set; }
}

Menghapus tombol keamanan mekanisme ulang terkonfigurasi

Sakelar Konteks Aplikasi "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" tidak lagi diperlukan untuk menggunakan logika pengulangan yang dapat dikonfigurasi. Fitur ini sekarang didukung dalam produksi. Perilaku default fitur tetap menjadi kebijakan tanpa percobaan ulang, yang perlu digantikan oleh aplikasi klien untuk memungkinkan percobaan ulang.

Dukungan instans bersama SqlLocalDb

Instans berbagi SqlLocalDb sekarang didukung saat menggunakan Managed SNI.

• Skenario yang mungkin:
  • (localdb)\. (menyambungkan ke instans default SqlLocalDb)
  • (localdb)\<named instance>
  • (localdb)\.\<shared instance name> (*dukungan yang baru ditambahkan)

GetFieldValueAsync<T> dan GetFieldValue<T> dukungan untuk jenis XmlReader, TextReader, Stream

XmlReader, TextReader, Stream jenis sekarang didukung saat menggunakan GetFieldValueAsync<T> dan GetFieldValue<T>.

Contoh penggunaan:

using (SqlConnection connection = new SqlConnection(connectionString))
{
    using (SqlCommand command = new SqlCommand(query, connection))
    {
        connection.Open();
        using (SqlDataReader reader = await command.ExecuteReaderAsync())
        {
            if (await reader.ReadAsync())
            {
                using (Stream stream = await reader.GetFieldValueAsync<Stream>(1))
                {
                    // Continue to read from stream
                }
            }
        }
    }
}

Dukungan Platform 4.0 Target

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis untuk 3.1

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 3.1.

Fitur baru di 3.1

Memperkenalkan Protokol Pengesahan 'None'

Protokol pengesahan baru yang disebut None akan diizinkan dalam string koneksi. Protokol ini akan memungkinkan pengguna untuk mengabaikan pengesahan enklave bagi VBS enklave. Ketika protokol ini diatur, properti URL pengesahan enklave bersifat opsional.

Contoh string koneksi:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

Dukungan Platform Target

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)

Catatan rilis untuk 3.0

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 3.0.

Perubahan yang mengganggu dalam 3.0

• Versi .NET Framework minimum yang didukung telah ditingkatkan ke v4.6.1. .NET Framework v4.6.0 tidak lagi didukung. #899
• User Idproperti koneksi sekarang memerlukan Client Id alih-alih Object Id untuk Identitas Terelola yang Ditugaskan Pengguna#1010Baca selengkapnya
• SqlDataReader sekarang mengembalikan DBNull sebuah nilai alih-alih byte[] kosong. Perilaku warisan dapat diaktifkan dengan mengatur AppContextswitch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Baca selengkapnya.

Fitur baru di 3.0

Logika ulang yang dapat dikonfigurasi

Fitur baru ini memperkenalkan dukungan yang dapat dikonfigurasi untuk aplikasi klien untuk mencoba kembali kesalahan "sementara" atau "dapat dicoba kembali". Konfigurasi dapat dilakukan melalui file konfigurasi kode atau aplikasi dan operasi coba lagi dapat diterapkan untuk membuka koneksi atau menjalankan perintah. Fitur ini dinonaktifkan secara default dan saat ini dalam pratinjau. Untuk mengaktifkan dukungan ini, aplikasi klien harus mengaktifkan sakelar keamanan berikut:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);

Setelah pengalihan .NET AppContext diaktifkan, kebijakan logika coba lagi dapat didefinisikan untuk SqlConnection dan SqlCommand secara independen, atau bersama-sama menggunakan berbagai opsi kustomisasi.

API publik baru diperkenalkan di SqlConnection dan SqlCommand untuk mendaftarkan implementasi kustom SqlRetryLogicBaseProvider :

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Contoh Penggunaan API dapat ditemukan di sini:

using Microsoft.Data.SqlClient;

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.
class RetryLogicSample
{
    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1)
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report the execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not a good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open the general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is being created and other services are going to connect to it.
            RetryConnection(provider);
        }
        catch
        {
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void RetryConnection(SqlRetryLogicBaseProvider provider)
    {
        // Change this if you already have a database with the same name in your database.
        string dbName = "Invalid_DB_Open";

        // Create a connection to an invalid database.
        using var cnn = new SqlConnection(string.Format(CnnStringFormat, dbName));
        // 3. Assign the `provider` to the connection
        cnn.RetryLogicProvider = provider;
        Console.WriteLine($"Connecting to the [{dbName}] ...");
        // Manually execute the following command in SSMS to create the invalid database while the SqlConnection is attempting to connect to it.
        // >> CREATE DATABASE Invalid_DB_Open;
        Console.WriteLine($"Manually, run the 'CREATE DATABASE {dbName};' in the SQL Server before exceeding the {provider.RetryLogic.NumberOfTries} attempts.");
        // the connection tries to connect to the database 5 times
        Console.WriteLine("The first attempt, before getting into the retry logic.");
        cnn.Open();
        Console.WriteLine($"Connected to the [{dbName}] successfully.");

        cnn.Close();

        // Drop it after test
        ExecuteCommand(s_generalConnection, string.Format(DropDatabaseFormat, dbName));
        Console.WriteLine($"The [{dbName}] is removed.");
    }
}

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.

    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";
    private const string CreateDatabaseFormat = "CREATE DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1),
            AuthorizedSqlCondition = null,
            // error number 3702 : Cannot drop database "xxx" because it is currently in use.
            TransientErrors = new int[] {3702}
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open a general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is creating and other services are going to connect to it.
            RetryCommand(provider);
        }
        catch
        {
            s_generalConnection.Close();
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
        s_generalConnection.Close();
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void FindActiveSessions(SqlConnection cnn, string dbName)
    {
        using var cmd = cnn.CreateCommand();
        cmd.CommandText = "DECLARE @query NVARCHAR(max) = '';" + Environment.NewLine +
            $"SELECT @query = @query + 'KILL ' + CAST(spid as varchar(50)) + ';' FROM sys.sysprocesses WHERE dbid = DB_ID('{dbName}')" + Environment.NewLine +
            "SELECT @query AS Active_sessions;";
        var reader = cmd.ExecuteReader();
        if (reader.Read())
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.Write($">> Execute the '{reader.GetString(0)}' command in SQL Server to unblock the running task.");
            Console.ResetColor();
        }
        reader.Close();
    }

var RetryLogicOption = new SqlRetryLogicOption()
{
    NumberOfTries = 5,
    // Declare the error number 102 as a transient error to apply the retry logic when it occurs.
    TransientErrors = new int[] { 102 },
    // When a SqlCommand executes out of a transaction, 
    // the retry logic will apply if it contains a 'select' keyword.
    AuthorizedSqlCondition = x => string.IsNullOrEmpty(x)
            || Regex.IsMatch(x, @"\b(SELECT)\b", RegexOptions.IgnoreCase),
    DeltaTime = TimeSpan.FromSeconds(1),
    MaxTimeInterval = TimeSpan.FromSeconds(60),
    MinTimeInterval = TimeSpan.FromSeconds(3)
};

Bagian konfigurasi baru juga telah diperkenalkan untuk melakukan pendaftaran yang sama dari file konfigurasi, tanpa harus memodifikasi kode yang ada:

<section name="SqlConfigurableRetryLogicConnection"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>

<section name="SqlConfigurableRetryLogicCommand"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

Berikut adalah contoh sederhana menggunakan bagian konfigurasi baru dalam file konfigurasi:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="SqlConfigurableRetryLogicConnection"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
    <section name="SqlConfigurableRetryLogicCommand"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

    <section name="AppContextSwitchOverrides"
             type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>
  </configSections>

  <!--Enable safety switch in .NET Core-->
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

  <!--Retry method for SqlConnection-->
  <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" numberOfTries ="3" deltaTime ="00:00:10" maxTime ="00:00:30"
                                    transientErrors="40615" />

  <!--Retry method for SqlCommand containing SELECT queries-->
  <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" numberOfTries ="5" deltaTime ="00:00:10" maxTime ="00:01:10"
                                    authorizedSqlCondition="\b(SELECT)\b" transientErrors="102, 4060, 0"/>
</configuration>

Atau, aplikasi dapat mengimplementasikan penyedia kelas dasar SqlRetryLogicBaseProvider mereka sendiri, dan mendaftarkannya dengan SqlConnection/SqlCommand.

Penghitung peristiwa

Penghitung berikut sekarang tersedia untuk aplikasi yang menargetkan .NET Core 3.1+ dan .NET Standard 2.1+:

Nama	Nama tampilan	Deskripsi
koneksi keras aktif	Koneksi aktif aktual yang saat ini dibuat ke server	Jumlah koneksi yang saat ini terbuka untuk server database.
sambungan keras	Laju koneksi aktual ke server	Jumlah koneksi per detik yang dibuka ke server database.
pemutusan keras	Tingkat pemutusan aktual dari server	Jumlah pemutusan sambungan per detik yang dibuat ke server database.
koneksi-lunak-aktif	Koneksi aktif yang diambil dari kumpulan koneksi	Jumlah koneksi yang digunakan dari kumpulan koneksi yang sudah terbuka.
soft-connects	Laju koneksi yang diambil dari kumpulan koneksi	Jumlah koneksi per detik yang digunakan dari kumpulan koneksi.
pemutusan sambungan sementara	Laju koneksi yang dikembalikan ke kumpulan koneksi	Jumlah koneksi per detik yang dikembalikan ke kumpulan koneksi.
jumlah-koneksi-tidak-tergabung	Jumlah koneksi yang tidak menggunakan pengumpulan koneksi	Jumlah koneksi aktif yang tidak dikumpulkan.
jumlah koneksi dalam pool	Jumlah koneksi yang dikelola oleh kumpulan koneksi	Infrastruktur pembagian koneksi mengelola jumlah koneksi aktif.
jumlah-grup-aktif-kumpulan-koneksi	Jumlah string koneksi unik aktif	Jumlah grup kumpulan koneksi unik yang aktif. Penghitung ini didasarkan pada jumlah string koneksi unik yang ditemukan di AppDomain.
jumlah-kelompok-kolam-koneksi-yang-tidak-aktif	Jumlah string koneksi unik yang menunggu pemangkasan	Jumlah grup kumpulan koneksi unik yang ditandai untuk pemangkasan. Penghitung ini didasarkan pada jumlah string koneksi unik yang ditemukan di AppDomain.
jumlah-kolam-koneksi-aktif	Jumlah kumpulan koneksi aktif	Jumlah total kumpulan koneksi.
jumlah-kolam-koneksi-tidak-aktif	Jumlah kumpulan koneksi yang tidak aktif	Jumlah kumpulan koneksi yang tidak aktif yang tidak menunjukkan aktivitas baru dan menunggu penghapusan.
jumlah-koneksi-aktif	Jumlah koneksi aktif	Jumlah koneksi aktif yang saat ini digunakan.
jumlah koneksi bebas	Jumlah koneksi siap di kumpulan koneksi	Jumlah koneksi terbuka yang tersedia untuk digunakan dalam kumpulan koneksi.
jumlah-koneksi-stasis	Jumlah koneksi yang saat ini menunggu untuk siap	Jumlah koneksi yang saat ini menunggu penyelesaian tindakan dan yang tidak tersedia untuk digunakan oleh aplikasi.
jumlah koneksi yang diklaim kembali	Jumlah koneksi yang diklaim kembali dari GC	Jumlah koneksi yang diperoleh kembali melalui pengumpulan sampah ketika Close atau Dispose tidak dipanggil oleh aplikasi. Catatan Tidak secara eksplisit menutup atau membuang koneksi menyakiti performa.

Penghitung ini dapat digunakan dengan alat CLI global .NET Core: dotnet-counters dan dotnet-trace di Windows atau Linux dan PerfView di Windows, menggunakan Microsoft.Data.SqlClient.EventSource sebagai nama penyedia. Untuk informasi selengkapnya, lihat Mengambil nilai penghitung peristiwa.

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p
PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect

Pengenalan dependensi Azure Identity

Microsoft.Data.SqlClient sekarang bergantung pada pustaka Azure.Identity untuk memperoleh token untuk mode autentikasi "Identitas Terkelola Direktori Aktif/MSI" dan "Perwakilan Layanan Direktori Aktif". Perubahan ini membawa perubahan berikut ke area permukaan publik:

• Perubahan yang merusak kompatibilitas

  Properti koneksi "ID Pengguna" sekarang memerlukan "ID Klien" sebagai pengganti "ID Objek" untuk "User-Assigned Identitas Terkelola".

• API Publik

  Properti publik baca-saja baru: SqlAuthenticationParameters.ConnectionTimeout

• Dependensi

  Azure.Identity v1.3.0

Peningkatan pelacakan peristiwa di SNI.dll

Microsoft.Data.SqlClient.SNI (Dependensi .NET Framework) dan Microsoft.Data.SqlClient.SNI.runtime (Dependensi .NET Core/Standard) telah diperbarui ke v3.0.0-preview1.21104.2. Pelacakan peristiwa di SNI.dll tidak lagi diaktifkan melalui aplikasi klien. Berlangganan sesi ke penyedia Microsoft.Data.SqlClient.EventSource melalui alat seperti xperf atau perfview sudah cukup. Untuk informasi selengkapnya, lihat Dukungan pelacakan peristiwa di Native SNI.

Mengaktifkan perilaku null pada versi baris

SqlDataReader mengembalikan nilai DBNull alih-alih nilai byte[] yang kosong. Untuk mengaktifkan perilaku warisan, Anda harus mengaktifkan pengalihan AppContext berikut pada startup aplikasi: "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"

Dukungan autentikasi default Microsoft Entra

Catatan

Meskipun MICROSOFT Entra ID adalah nama baru untuk Azure Active Directory (Azure AD), untuk mencegah mengganggu lingkungan yang ada, Azure AD masih tetap berada di beberapa elemen yang dikodekan secara permanen seperti bidang UI, penyedia koneksi, kode kesalahan, dan cmdlet. Dalam artikel ini, dua nama tersebut dapat dipertukarkan.

PR ini memperkenalkan metode Autentikasi SQL baru, Active Directory Default. Mode autentikasi ini memperluas kemungkinan autentikasi pengguna dengan MICROSOFT Entra ID, memperluas solusi masuk ke lingkungan klien, Visual Studio Code, Visual Studio, Azure CLI, dll.

Dengan mode autentikasi ini, driver memperoleh token dengan menggunakan "DefaultAzureCredential" dari pustaka Azure Identity untuk mendapatkan token akses. Mode ini mencoba menggunakan jenis kredensial ini untuk memperoleh token akses dalam urutan berikut:

• EnvironmentCredential
  • Mengaktifkan autentikasi dengan ID Microsoft Entra menggunakan detail klien dan rahasia, atau nama pengguna dan kata sandi, yang dikonfigurasi dalam variabel lingkungan berikut: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Informasi selengkapnya)
• ManagedIdentityCredential
  • Mencoba autentikasi dengan ID Microsoft Entra menggunakan identitas terkelola yang telah ditetapkan ke lingkungan penyebaran. "ID Klien" dari "identitas terkelola yang ditetapkan pengguna" dibaca dari atribut properti koneksi "ID Pengguna".
• SharedTokenCacheCredential
  • Mengautentikasi menggunakan token di cache lokal yang dibagikan antara aplikasi Microsoft.
• VisualStudioCredential
  • Mengaktifkan autentikasi dengan MICROSOFT Entra ID menggunakan data dari Visual Studio
• VisualStudioCodeCredential
  • Mengaktifkan autentikasi dengan MICROSOFT Entra ID menggunakan data dari Visual Studio Code.
• AzureCliCredential
  • Mengaktifkan autentikasi dengan MICROSOFT Entra ID menggunakan Azure CLI untuk mendapatkan token akses.

InteractiveBrowserCredential dinonaktifkan dalam implementasi driver "Active Directory Default", dan "Active Directory Interactive" adalah satu-satunya opsi yang tersedia untuk memperoleh token menggunakan autentikasi MFA/Interaktif.

Opsi penyesuaian lebih lanjut saat ini tidak tersedia.

Penyempurnaan pendaftaran penyedia penyimpanan kunci induk khusus

Microsoft.Data.SqlClient sekarang menawarkan lebih banyak kontrol atas aksesibilitas penyedia penyimpanan kunci utama dalam aplikasi, sehingga lebih mendukung aplikasi multitenan dan penggunaan enkripsi/dekripsi kolom mereka. API berikut diperkenalkan untuk memungkinkan pendaftaran penyedia penyimpanan kunci master kustom pada instans SqlConnection dan SqlCommand:

public class SqlConnection
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}
public class SqlCommand
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnCommand(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}

API statis pada SqlConnection, SqlConnection.RegisterColumnEncryptionKeyStoreProviders, yang digunakan untuk mendaftarkan penyedia penyimpanan kunci master kustom secara global, terus didukung. Cache kunci enkripsi kolom yang dikelola secara global hanya berlaku untuk penyedia yang terdaftar secara global.

Prioritas pendaftaran penyedia penyimpanan kunci master untuk kolom

Penyedia penyimpanan kunci master kolom bawaan yang tersedia untuk Windows Certificate Store, CNG Store, dan CSP telah terdaftar sebelumnya. Tidak ada penyedia yang harus terdaftar pada koneksi atau instans perintah jika salah satu penyedia penyimpanan kunci master kolom bawaan diperlukan.

Penyedia penyimpanan kunci master kustom dapat didaftarkan dengan driver pada tiga lapisan yang berbeda. Tingkat global seperti keadaannya saat ini. Pendaftaran tingkat per koneksi dan per perintah baru awalnya kosong dan dapat diatur lebih dari sekali.

Prioritas dari tiga pendaftaran adalah sebagai berikut:

• Pendaftaran per perintah diperiksa jika tidak kosong.
• Jika pendaftaran per perintah kosong, pendaftaran per koneksi diperiksa jika tidak kosong.
• Jika pendaftaran per koneksi kosong, pendaftaran global akan diperiksa.

Setelah penyedia sistem penyimpanan kunci ditemukan pada tingkat pendaftaran, driver tidak kembali ke pendaftaran lain untuk mencari penyedia. Jika penyedia terdaftar tetapi penyedia yang tepat tidak ditemukan pada suatu level, pengecualian akan dibangkitkan yang hanya berisi penyedia terdaftar yang telah diperiksa dalam pendaftaran.

Prioritas cache kunci enkripsi kolom

Driver tidak menyimpan kunci enkripsi kolom (CEK) untuk penyedia penyimpanan kunci kustom yang terdaftar menggunakan API tingkat instans baru. Penyedia penyimpanan kunci perlu menerapkan cache mereka sendiri untuk meningkatkan kinerja. Driver menonaktifkan cache lokal kunci enkripsi kolom yang diterapkan oleh penyedia penyimpanan kunci kustom jika instans penyedia penyimpanan kunci terdaftar di driver di tingkat global.

API baru juga telah diperkenalkan pada SqlColumnEncryptionKeyStoreProvider kelas dasar untuk mengatur waktu cache untuk hidup:

public abstract class SqlColumnEncryptionKeyStoreProvider
{
    // The default value of Column Encryption Key Cache Time to Live is 0.
    // Provider's local cache is disabled for globally registered providers.
    // Custom key store provider implementation must include column encryption key cache to provide caching support to locally registered providers.
    public virtual TimeSpan? ColumnEncryptionKeyCacheTtl { get; set; } = new TimeSpan(0);
}

Preferensi alamat IP

Properti koneksi baru IPAddressPreference diperkenalkan untuk menentukan preferensi keluarga alamat IP untuk driver saat membuat koneksi TCP. Jika Transparent Network IP Resolution (dalam .NET Framework) atau Multi Subnet Failover diatur ke true, pengaturan ini tidak berpengaruh. Ada tiga nilai yang diterima untuk properti ini:

• IPv4First

  • Ini adalah nilai default. Driver menggunakan alamat IPv4 terkonversi terlebih dahulu. Jika tidak ada dari mereka yang berhasil terhubung, ia mencoba menggunakan alamat IPv6 yang telah di-resolve.

• IPv6First

  • Driver menggunakan alamat IPv6 yang telah diteresolusikan terlebih dahulu. Jika tidak ada yang berhasil disambungkan, ia mencoba menyelesaikan alamat IPv4.

• UsePlatformDefault

  • Driver mencoba alamat IP dalam urutan yang diterima dari respons resolusi DNS.

3.0 Dukungan platform target

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis untuk 2.1

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 2.1.

Fitur baru di 2.1

Dukungan lintas platform untuk Always Encrypted

Microsoft.Data.SqlClient v2.1 memperluas dukungan untuk Always Encrypted pada platform berikut:

Dukungan Always Encrypted	Mendukung Always Encrypted dengan Secure Enclave	Kerangka kerja target	Versi: Microsoft.Data.SqlClient	Sistem operasi
Ya	Ya	.NET Framework 4.6+	1.1.0+	Windows
Ya	Ya	.NET Core 2.1+	2.1.0+1	Windows, Linux, macOS
Ya	No2	.NET Standar 2.0	2.1.0+	Windows, Linux, macOS
Ya	Ya	.NET Standar 2.1+	2.1.0+	Windows, Linux, macOS

¹ Sebelum Microsoft.Data.SqlClient versi v2.1, Always Encrypted hanya didukung di Windows.
² Always Encrypted dengan enklave yang aman tidak didukung pada .NET Standard 2.0.

Autentikasi Alur Kode Perangkat Microsoft Entra

Microsoft.Data.SqlClient v2.1 menyediakan dukungan untuk autentikasi "Aliran Kode Perangkat" dengan MSAL.NET. Dokumentasi referensi: Alur Pemberian Otorisasi Perangkat OAuth2.0

Contoh string koneksi:

Server=<server>.database.windows.net; Authentication=Active Directory Device Code Flow; Database=Northwind;Encrypt=True

API berikut memungkinkan penyesuaian mekanisme panggilan balik Aliran Kode Perangkat:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetDeviceCodeFlowCallback(Func<DeviceCodeResult, Task> deviceCodeFlowCallbackMethod)
}

Autentikasi identitas terkelola Microsoft Entra

Microsoft.Data.SqlClient v2.1 memperkenalkan dukungan untuk autentikasi Microsoft Entra menggunakan identitas terkelola.

Kata kunci mode autentikasi berikut didukung:

• Identitas Terkelola Direktori Aktif
• Active Directory MSI (untuk kompatibilitas driver SQL lintas MS)

Contoh string koneksi:

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; Initial Catalog={db};"

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

Penyempurnaan autentikasi Microsoft Entra Interactive

Microsoft.Data.SqlClient v2.1 menambahkan API berikut untuk menyesuaikan pengalaman autentikasi Microsoft Entra Interactive :

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

SqlClientAuthenticationProviders bagian konfigurasi

Microsoft.Data.SqlClient v2.1 memperkenalkan bagian konfigurasi baru, SqlClientAuthenticationProviders (kloning SqlAuthenticationProvidersdari yang ada ). Bagian konfigurasi yang ada, SqlAuthenticationProviders, masih didukung untuk kompatibilitas ke belakang ketika jenis yang tepat ditentukan.

Bagian baru memungkinkan file konfigurasi aplikasi berisi bagian SqlAuthenticationProviders untuk System.Data.SqlClient dan bagian SqlClientAuthenticationProviders untuk Microsoft.Data.SqlClient.

Autentikasi Microsoft Entra menggunakan ID klien aplikasi

Microsoft.Data.SqlClient v2.1 memperkenalkan dukungan untuk meneruskan ID klien aplikasi yang ditentukan pengguna ke Microsoft Authentication Library. ID Klien Aplikasi digunakan saat mengautentikasi dengan ID Microsoft Entra.

API baru berikut diperkenalkan:

1. Konstruktor baru telah diperkenalkan di ActiveDirectoryAuthenticationProvider:

   Berlaku untuk: Semua Platform .NET (.NET Framework, .NET Core, dan .NET Standard)

   public ActiveDirectoryAuthenticationProvider(string applicationClientId)
   

   Penggunaan:

   string APP_CLIENT_ID = "<GUID>";
   SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID);
   SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider);
   
   using (SqlConnection sqlConnection = new SqlConnection("<connection_string>"))
   {
       sqlConnection.Open();
   }
   

2. Properti konfigurasi baru telah diperkenalkan di bawah SqlAuthenticationProviderConfigurationSection dan SqlClientAuthenticationProviderConfigurationSection:

   Berlaku untuk: .NET Framework dan .NET Core

   internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
   {
       ...
       [ConfigurationProperty("applicationClientId", IsRequired = false)]
       public string ApplicationClientId => this["applicationClientId"] as string;
   }
   
   // Inheritance
   internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
   { ... }
   

   Penggunaan:

   <configuration>
       <configSections>
           <section name="SqlClientAuthenticationProviders"
                            type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
       </configSections>
       <SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
   </configuration>
   
   <!--or-->
   
   <configuration>
       <configSections>
           <section name="SqlAuthenticationProviders"
                            type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
       </configSections>
       <SqlAuthenticationProviders applicationClientId ="<GUID>" />
   </configuration>
   

Dukungan Klasifikasi Data v2

Microsoft.Data.SqlClient v2.1 memperkenalkan dukungan untuk informasi "Peringkat Sensitivitas" Klasifikasi Data. API baru berikut ini sekarang tersedia:

public class SensitivityClassification
{
    public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
    public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

ID Sesi dari SqlConnection yang aktif

Microsoft.Data.SqlClient v2.1 memperkenalkan properti baru SqlConnection , ServerProcessId, pada koneksi aktif.

public class SqlConnection
{
    // Returns the session ID (SPID) of the active connection.
    public int ServerProcessId;
}

Dukungan pencatatan log di SNI asli

Microsoft.Data.SqlClient v2.1 memperluas implementasi yang ada SqlClientEventSource untuk mengaktifkan pelacakan peristiwa di SNI.dll. Peristiwa harus diambil menggunakan alat seperti Xperf.

Pelacakan dapat diaktifkan dengan mengirim perintah ke SqlClientEventSource seperti yang diilustrasikan:

// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);

// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);

// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);

Properti string koneksi "Batas Waktu Perintah"

Microsoft.Data.SqlClient v2.1 memperkenalkan properti string koneksi "Batas Waktu Perintah" untuk mengambil alih default 30 detik. Batas waktu untuk perintah individual dapat ditimpa menggunakan CommandTimeout properti pada SqlCommand.

Contoh string koneksi:

"Server={serverURL}; Initial Catalog={db}; Encrypt=True; Integrated Security=true; Command Timeout=60"

Penghapusan simbol dari SNI asli

Dengan Microsoft.Data.SqlClient v2.1, kami telah menghapus simbol yang diperkenalkan pada v2.0.0 dari Microsoft.Data.SqlClient.SNI.runtime NuGet, dimulai dengan v2.1.1. Simbol publik sekarang diterbitkan ke Microsoft Symbols Server untuk alat seperti BinSkim yang memerlukan akses ke simbol publik.

Penautan sumber simbol Microsoft.Data.SqlClient

Dimulai dengan Microsoft.Data.SqlClient v2.1, simbol Microsoft.Data.SqlClient ditautkan ke sumber dan diterbitkan ke Server Simbol Microsoft untuk pengalaman debugging yang lebih baik tanpa perlu mengunduh ulang kode sumber.

2.1 Dukungan untuk platform target

• .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis untuk 2.0

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 2.0.

Perubahan besar pada versi 2.0

• Pengubah akses antarmuka penyedia enklave SqlColumnEncryptionEnclaveProvider telah diubah dari public ke internal.
• Konstanta SqlClientMetaDataCollectionNames di kelas telah diperbarui untuk mencerminkan perubahan di SQL Server.
• Driver sekarang melakukan validasi Sertifikat Server ketika SQL Server target memberlakukan enkripsi TLS, yang merupakan default untuk koneksi Azure.
• SqlDataReader.GetSchemaTable() sekarang mengembalikan DataTable kosong alih-alih null.
• Driver sekarang melakukan pembulatan skala desimal agar sesuai dengan perilaku SQL Server. Untuk kompatibilitas mundur, perilaku pemotongan sebelumnya dapat diaktifkan menggunakan sakelar AppContext.
• Untuk aplikasi .NET Framework yang menggunakan Microsoft.Data.SqlClient, file SNI.dll yang sebelumnya diunduh ke bin\x64 folder dan bin\x86 sekarang diberi nama Microsoft.Data.SqlClient.SNI.x64.dll dan Microsoft.Data.SqlClient.SNI.x86.dll dan diunduh ke bin direktori.
• Sinonim properti string koneksi baru menggantikan properti lama saat mengambil string koneksi dari SqlConnectionStringBuilder untuk konsistensi. Baca Selengkapnya

Fitur baru di 2.0

Fitur baru berikut telah diperkenalkan di Microsoft.Data.SqlClient 2.0.

Ketahanan kegagalan DNS

Driver sekarang menyimpan alamat IP dari setiap koneksi yang berhasil ke titik akhir SQL Server yang mendukung fitur tersebut. Jika kegagalan resolusi DNS terjadi selama upaya koneksi, driver mencoba membuat koneksi menggunakan alamat IP yang di-cache untuk server tersebut, jika ada.

Pelacakan EventSource

Rilis ini memperkenalkan dukungan untuk menangkap log jejak acara untuk aplikasi debugging. Untuk menangkap peristiwa ini, aplikasi klien harus mendengarkan peristiwa dari implementasi EventSource SqlClient:

Microsoft.Data.SqlClient.EventSource

Untuk informasi selengkapnya, lihat cara Mengaktifkan pelacakan peristiwa di SqlClient.

Mengaktifkan jaringan terkelola pada Windows

Sakelar AppContext baru, "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", memungkinkan penggunaan implementasi SNI terkelola di Windows untuk tujuan pengujian dan debugging. Sakelar ini mengubah perilaku driver untuk menggunakan SNI terkelola dalam proyek .NET Core 2.1+ dan .NET Standard 2.0+ pada Windows, menghilangkan semua dependensi terhadap pustaka asli dalam pustaka Microsoft.Data.SqlClient.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Lihat Sakelar AppContext di SqlClient untuk daftar lengkap sakelar yang tersedia pada driver.

Mengaktifkan perilaku pemotongan desimal

Driver membulatkan skala data desimal, secara default, seperti yang dilakukan oleh SQL Server. Untuk kompatibilitas ke belakang, Anda dapat mengatur sakelar AppContext "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" ke true.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Sinonim properti string koneksi baru

Sinonim baru telah ditambahkan untuk properti connection string yang ada berikut ini guna menghindari kebingungan terkait spasi pada properti yang terdiri dari lebih dari satu kata. Nama properti lama tetap didukung untuk kompatibilitas ke belakang. Tetapi properti string koneksi baru sekarang disertakan saat mengambil string koneksi dari SqlConnectionStringBuilder.

Properti string koneksi yang ada	Sinonim baru
ApplicationIntent	Niat Aplikasi
ConnectRetryCount	Jumlah Percobaan Ulang Koneksi
ConnectRetryInterval	Sambungkan Interval Coba Lagi
PeriodePemblokiranPool	Periode Pemblokiran Pool
MultipleActiveResultSets (beberapa set hasil aktif)	Beberapa Set Hasil Aktif
MultiSubnetFailover	Failover Beberapa Subnet
Resolusi IP Jaringan Transparan	Resolusi IP Jaringan Transparan
TrustServerCertificate	Sertifikat Server Kepercayaan

Properti SqlBulkCopy RowsCopied

Properti RowsCopied menyediakan akses baca-saja ke jumlah baris yang telah diproses dalam operasi penyalinan massal yang sedang berlangsung. Nilai ini mungkin belum tentu sama dengan jumlah akhir baris yang ditambahkan ke tabel tujuan.

Pengalihan buka koneksi

Perilaku default SqlConnection.Open() dapat diubah untuk menonaktifkan penundaan sepuluh detik dan percobaan ulang koneksi otomatis yang dipicu oleh kesalahan sementara (transient errors).

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry);
}

Catatan

Penimpaan ini dapat diterapkan ke SqlConnection.OpenAsync() mulai dari Microsoft.Data.SqlClient v6.0.0.

Dukungan nama pengguna untuk mode Interaktif Direktori Aktif

Nama pengguna dapat ditentukan dalam string koneksi saat menggunakan mode autentikasi Microsoft Entra Interactive untuk .NET Framework dan .NET Core

Setel nama pengguna menggunakan properti User ID atau UID string koneksi:

"Server=<server name>; Database=<db name>; Authentication=Active Directory Interactive; User Id=<username>;Encrypt=True;"

Petunjuk pesanan untuk SqlBulkCopy

Petunjuk pesanan dapat disediakan untuk meningkatkan performa untuk operasi penyalinan massal pada tabel dengan indeks berkluster. Untuk informasi selengkapnya, lihat bagian operasi salin massal.

Perubahan dependensi SNI

Microsoft.Data.SqlClient (.NET Core dan .NET Standard) di Windows sekarang bergantung pada Microsoft.Data.SqlClient.SNI.runtime, menggantikan dependensi sebelumnya pada runtime.native.System.Data.SqlClient.SNI. Dependensi baru menambahkan dukungan untuk platform ARM bersama dengan platform arm64, x64, dan x86 yang sudah didukung di Windows.

2.0 Dukungan platform target

• .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Catatan rilis untuk 1.1

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 1.1.

Fitur baru di 1.1

Always Encrypted dengan enklave aman

Always Encrypted tersedia mulai dari Microsoft SQL Server 2016. Enklave aman tersedia mulai dari Microsoft SQL Server 2019. Untuk menggunakan fitur enklave, string koneksi harus menyertakan protokol pengesahan dan URL pengesahan yang diperlukan. Contohnya:

"Attestation Protocol=HGS;Enclave Attestation Url=<attestation_url_for_HGS>"

Untuk informasi selengkapnya, lihat:

• Menggunakan Always Encrypted dengan Penyedia Data Microsoft .NET untuk SQL Server
• Tutorial: Mengembangkan aplikasi .NET menggunakan Always Encrypted dengan enklave aman

1.1 Dukungan platform target

• .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)

Catatan rilis untuk 1.0

Rilis awal untuk namespace Microsoft.Data.SqlClient menawarkan lebih banyak fungsionalitas melalui namespace System.Data.SqlClient yang ada.

Catatan rilis lengkap, termasuk dependensi, tersedia di Repositori GitHub: Catatan Rilis 1.0.

Fitur baru di 1.0

Fitur baru melalui .NET Framework 4.7.2 System.Data.SqlClient

• Klasifikasi Data - Tersedia di Azure SQL Database dan Microsoft SQL Server 2019.

• Dukungan UTF-8 - Tersedia di Microsoft SQL Server 2019.

Fitur baru melalui .NET Core 2.2 System.Data.SqlClient

• Klasifikasi Data - Tersedia di Azure SQL Database dan Microsoft SQL Server 2019.

• Dukungan untuk UTF-8 - Tersedia di Microsoft SQL Server 2019.

• Autentikasi - Mode autentikasi sandi Active Directory.

Klasifikasi data

Klasifikasi Data menghadirkan API baru yang mengekspos informasi hanya-baca tentang Sensitivitas dan Klasifikasi Data pada objek yang diperoleh melalui SqlDataReader ketika sumber yang mendukung fitur ini menyediakan metadata mengenai sensitivitas dan klasifikasi data. Lihat aplikasi sampel di Penemuan dan Klasifikasi Data di SqlClient.

public class SqlDataReader
{
    public Microsoft.Data.SqlClient.DataClassification.SensitivityClassification SensitivityClassification
}

namespace Microsoft.Data.SqlClient.DataClassification
{
    public class ColumnSensitivity
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.SensitivityProperty> SensitivityProperties
    }
    public class InformationType
    {
        public string Id
        public string Name
    }
    public class Label
    {
        public string Id
        public string Name
    }
    public class SensitivityClassification
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.ColumnSensitivity> ColumnSensitivities
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.InformationType> InformationTypes
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.Label> Labels
    }
    public class SensitivityProperty
    {
        public Microsoft.Data.SqlClient.DataClassification.InformationType InformationType
        public Microsoft.Data.SqlClient.DataClassification.Label Label
    }
}

Dukungan UTF-8

Dukungan UTF-8 tidak memerlukan perubahan kode aplikasi apa pun. Perubahan SqlClient ini mengoptimalkan komunikasi server klien ketika server mendukung UTF-8 dan kolase kolom yang mendasar adalah UTF-8. Lihat bagian UTF-8 di bawah Apa yang baru di SQL Server 2019.

Always Encrypted dengan enklave aman

Secara umum, dokumentasi yang ada yang menggunakan System.Data.SqlClient pada .NET Framework dan penyedia penyimpanan kunci master kolom bawaan sekarang harus bekerja dengan .NET Core juga.

• Menggunakan Always Encrypted dengan Penyedia Data .NET Framework untuk SQL Server
• Always Encrypted: Melindungi data sensitif dan menyimpan kunci enkripsi di penyimpanan sertifikat Windows

Autentikasi

Mode autentikasi yang berbeda dapat ditentukan dengan menggunakan opsi Autentikasi string koneksi. Untuk informasi selengkapnya, lihat dokumentasi untuk SqlAuthenticationMethod.

Penyedia penyimpanan kunci kustom, seperti penyedia Azure Key Vault, perlu diperbarui untuk mendukung Microsoft.Data.SqlClient. Demikian pula, penyedia enklave juga perlu diperbarui untuk mendukung Microsoft.Data.SqlClient.

Always Encrypted hanya didukung terhadap target .NET Framework dan .NET Core. Ini tidak didukung terhadap .NET Standard karena .NET Standard tidak memiliki dependensi enkripsi tertentu.

1.0 Dukungan platform-target

• .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)