Pengantar namespace Microsoft.Data.SqlClient

  • Artikel

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 dapat memengaruhi beberapa aplikasi. Untuk perbedaan tersebut, lihat lembar cheat porting yang berguna.

Referensi API

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

Catatan rilis untuk Microsoft.Data.SqlClient 5.2

Fitur baru di 5.2

Menambahkan properti RowsCopied64 baru ke SqlBulkCopy

SqlBulkCopy memiliki properti RowsCopied64 baru yang mendukung long jenis nilai.

Perhatikan bahwa 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 Sql Koneksi ion

Sql Koneksi ion 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();
    using SqlConnection connection = new SqlConnection(connectionString);
    
    connection.AccessTokenCallback = async (authParams, cancellationToken) =>
    {
        var cred = new DefaultAzureCredential();
        string scope = authParams.Resource.EndsWith(defaultScopeSuffix) ? authParams.Resource : authParams.Resource + defaultScopeSuffix;
        AccessToken token = await cred.GetTokenAsync(new TokenRequestContext(new[] { 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 Platform Target

  • .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.

Memutus perubahan dalam 5.1

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

Fitur baru di 5.1

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

Sertifikat Server

Nilai ServerCertificate default pengaturan koneksi 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, Windows 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 Microsoft.Data.SqlClient 5.0

Memutus perubahan 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 layanan dan menggantinya 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

Keamanan TDS 8 ditingkatkan

Untuk menggunakan TDS 8, tentukan Encrypt=Strict di string koneksi. Mode ketat menonaktifkan TrustServerCertificate (selalu diperlakukan sebagai False dalam mode Ketat). HostNameInCertificate telah ditambahkan untuk membantu beberapa skenario mode ketat. TDS 8 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.

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 dapat digunakan untuk mengambil alih SPN server 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 Enumerator 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 adalah output pada konsol jika versi TLS kurang dari 1.2 digunakan untuk bernegosiasi dengan server. Peringatan ini dapat ditekan pada koneksi SQL sementara Encrypt = false dengan mengaktifkan sakelar AppContext berikut pada startup aplikasi:

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Dukungan platform Target 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 Microsoft.Data.SqlClient 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 forgo pengesahan enklave untuk VBS enklave. Ketika protokol ini diatur, properti URL pengesahan enklave bersifat opsional.

contoh string Koneksi ion:

//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 Microsoft.Data.SqlClient 4.0

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

Memutus perubahan dalam 4.0

  • Mengubah Encrypt properti string koneksi menjadi true secara default. #1210Baca selengkapnya
  • Driver sekarang memberikan SqlException penggantian AggregateException untuk mode autentikasi direktori aktif. #1213
  • Properti koneksi usang yang dihilangkan Asynchronous Processing dari .NET Framework. #1148
  • Sakelar pengaman dihapus Configurable Retry Logic . #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, ada kemungkinan koneksi yang tidak terenkripsi dibuat ketika Enkripsi diatur ke true atau enkripsi yang diperlukan server.

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 sakelar keamanan logika coba lagi yang dapat dikonfigurasi

Sakelar Konteks Aplikasi "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" tidak lagi diperlukan untuk menggunakan fitur logika coba lagi yang dapat dikonfigurasi. Fitur ini sekarang didukung dalam produksi. Perilaku default fitur terus menjadi kebijakan non-coba lagi, yang perlu diambil alih aplikasi klien untuk mengaktifkan percobaan ulang.

Dukungan instans bersama SqlLocalDb

Instans bersama SqlLocalDb sekarang didukung saat menggunakan SNI Terkelola.

  • 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 XmlReader, TextReader, Stream jenis

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 Target 4.0

  • .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 Microsoft.Data.SqlClient 3.0

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

Memutus perubahan 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 Terkelola yang Ditetapkan Pengguna#1010Baca selengkapnya
  • SqlDataReader sekarang mengembalikan DBNull nilai alih-alih kosong byte[]. Perilaku warisan dapat diaktifkan dengan mengatur AppContext switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Baca selengkapnya

Fitur baru di 3.0

Logika Coba Lagi 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 menerapkan penyedia SqlRetryLogicBaseProvider kelas dasar mereka sendiri, dan mendaftarkannya dengan/SqlConnectionSqlCommand .

Penghitung Peristiwa

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

Nama Nama tampilan Deskripsi
active-hard-connections Koneksi aktif aktual yang saat ini dibuat ke server Jumlah koneksi yang saat ini terbuka untuk server database.
hard-connects Laju koneksi aktual ke server Jumlah koneksi per detik yang dibuka ke server database.
hard-disconnects Tingkat pemutusan aktual dari server Jumlah pemutusan sambungan per detik yang dibuat ke server database.
active-soft-connects Koneksi aktif yang diambil dari kumpulan koneksi Jumlah koneksi yang sudah terbuka yang digunakan dari kumpulan koneksi.
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.
number-of-non-pooled-connections Jumlah koneksi yang tidak menggunakan pengumpulan koneksi Jumlah koneksi aktif yang tidak dikumpulkan.
jumlah koneksi terkumpul Jumlah koneksi yang dikelola oleh kumpulan koneksi Jumlah koneksi aktif yang mengelola infrastruktur pengumpulan koneksi.
number-of-active-connection-pool-groups Jumlah string koneksi unik aktif Jumlah grup kumpulan koneksi unik yang aktif. Penghitung ini didasarkan pada jumlah string koneksi unik yang ditemukan di AppDomain.
number-of-inactive-connection-pool-groups 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.
number-of-active-connection-pools Jumlah kumpulan koneksi aktif Jumlah total kumpulan koneksi.
number-of-inactive-connection-pools Jumlah kumpulan koneksi yang tidak aktif Jumlah kumpulan koneksi yang tidak aktif tanpa aktivitas terbaru dan menunggu untuk dibuang.
number-of-active-connections 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.
number-of-stasis-connections 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 direklamasi melalui pengumpulan sampah di mana 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:

  • Melanggar Perubahan
    Properti koneksi "Id Pengguna" sekarang memerlukan "Id Klien" alih-alih "Id Objek" untuk "Identitas Terkelola yang Ditetapkan Pengguna".
  • 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 SNI Asli.

Mengaktifkan perilaku null versi baris

SqlDataReaderDBNull mengembalikan nilai alih-alih kosongbyte[]. 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, Default Direktori Aktif. 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 meneruskan "DefaultAzureCredential" dari pustaka Azure Identity untuk memperoleh token akses. Mode ini mencoba menggunakan jenis kredensial ini untuk memperoleh token akses dalam urutan berikut:

  • EnvironmentCredential
    • Mengaktifkan autentikasi dengan ID Microsoft Entra menggunakan klien dan rahasia, atau nama pengguna dan kata sandi, detail yang dikonfigurasi dalam variabel lingkungan berikut: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Detail 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 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 master kustom

Microsoft.Data.SqlClient sekarang menawarkan lebih banyak kontrol di mana penyedia penyimpanan kunci master dapat diakses dalam aplikasi untuk mendukung aplikasi multi-penyewa dengan lebih baik dan penggunaan enkripsi/dekripsi kolom. 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 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 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 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 tingkat, pengecualian hanya dilemparkan yang berisi penyedia terdaftar dalam pendaftaran yang diperiksa.

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 mendapatkan performa. 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 IPAddressPreference koneksi baru diperkenalkan untuk menentukan preferensi keluarga alamat IP ke 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 yang diselesaikan terlebih dahulu. Jika tidak ada yang berhasil disambungkan, ia mencoba menyelesaikan alamat IPv6.

  • IPv6First

    • Driver menggunakan alamat IPv6 yang diselesaikan 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.

Dukungan Platform Target 3.0

  • .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 Microsoft.Data.SqlClient 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 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

Catatan

1 Sebelum Microsoft.Data.SqlClient versi v2.1, Always Encrypted hanya didukung di Windows. 2 Always Encrypted dengan enklave 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 ion:

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 mundur ketika jenis yang sesuai 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 Proses Server untuk aktif SqlConnection

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

public class SqlConnection
{
    // Returns the server process Id (SPID) of the active connection.
    public int ServerProcessId;
}

Melacak dukungan Pengelogan 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 di v2.0.0 dari NuGet Microsoft.Data.SqlClient.SNI.runtime 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 sumber dan diterbitkan ke Microsoft Symbols Server untuk pengalaman penelusuran kesalahan yang ditingkatkan tanpa perlu mengunduh kode sumber.

2.1 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 Microsoft.Data.SqlClient 2.0

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

Memutus perubahan dalam 2.0

  • Pengubah akses untuk antarmuka SqlColumnEncryptionEnclaveProvider penyedia enklave 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 kosong DataTable sebagai gantinya 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 peristiwa untuk aplikasi penelusuran kesalahan. 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 mengalihkan perilaku driver untuk menggunakan SNI terkelola di proyek .NET Core 2.1+ dan .NET Standard 2.0+ pada Windows, menghilangkan semua dependensi pada pustaka asli untuk pustaka Microsoft.Data.SqlClient.

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

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

Mengaktifkan perilaku pemotongan desimal

Driver membulatkan skala data desimal, secara default, seperti yang dilakukan oleh SQL Server. Untuk kompatibilitas mundur, 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 string koneksi yang ada berikut ini untuk menghindari kebingungan spasi di sekitar properti dengan lebih dari satu kata. Nama properti lama terus didukung untuk kompatibilitas mundur. Tetapi properti string koneksi baru sekarang disertakan saat mengambil string koneksi dari Sql Koneksi ionStringBuilder.

Properti string koneksi yang ada Sinonim Baru
ApplicationIntent Niat Aplikasi
Koneksi RetryCount jumlah coba lagi Koneksi
Koneksi RetryInterval Interval Coba Lagi Koneksi
PoolBlockingPeriod Periode Pemblokiran Kumpulan
MultipleActiveResultSets Beberapa Set Hasil Aktif
MultiSubnetFailover Failover Beberapa Subnet
TransparentNetworkIPResolution 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.

penimpaan terbuka Koneksi ion

Perilaku default Sql Koneksi ion. Open() dapat ditimpa 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;");
sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry);

Catatan

Perhatikan bahwa penimpaan ini hanya dapat diterapkan ke Sql Koneksi ion. Buka() dan bukan Sql Koneksi ion. OpenAsync().

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

Atur nama pengguna menggunakan properti ID Pengguna atau string koneksi UID:

"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.

Dukungan Platform Target 2.0

  • .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 Microsoft.Data.SqlClient 1.1.0

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

Fitur baru di 1.1

Always Encrypted dengan kantong 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:

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 Microsoft.Data.SqlClient 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 UTF-8 - Tersedia di Microsoft SQL Server 2019.

  • Autentikasi - Mode autentikasi Kata Sandi Direktori Aktif.

Klasifikasi data

Klasifikasi Data menghadirkan sekumpulan API baru yang mengekspos informasi Sensitivitas dan Klasifikasi Data baca-saja tentang objek yang diambil melalui SqlDataReader saat sumber yang mendasar mendukung fitur dan berisi metadata tentang 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.

Selalu dienkripsi 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.

Kembangkan menggunakan Always Encrypted dengan Penyedia Data .NET Framework

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.

Catatan

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 kehilangan 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)