Pengantar namespace Microsoft.Data.SqlClient
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 dukungan
SqlDiagnosticListener
pada .NET Standard. #1931 - Menambahkan properti
RowsCopied64
baru keSqlBulkCopy
. #2004 Baca selengkapnya - Menambahkan API baru
AccessTokenCallBack
keSqlConnection
. #1260 Baca selengkapnya - Menambahkan dukungan untuk
SuperSocketNetLib
opsi registri untuk Enkripsi pada .NET di Windows. #2047 - Menambahkan
SqlBatch
dukungan pada .NET 6+ #1825, #2223 Baca selengkapnya - Menambahkan dukungan autentikasi Identitas Beban Kerja #2159, #2264
- Menambahkan dukungan Pelokalan pada .NET #2210
- Menambahkan dukungan untuk kolaborasi 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 penelusuran kesalahan dalam file paket terpisah #2137
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 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 cred.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 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
Fitur baru di 5.1
- Menambahkan dukungan untuk
DateOnly
danTimeOnly
untukSqlParameter
nilai danGetFieldValue
. #1813 - Menambahkan dukungan untuk TLS 1.3 untuk .NET Core dan SNI Native. #1821
- Menambahkan
ServerCertificate
pengaturan untukEncrypt=Mandatory
atauEncrypt=Strict
. #1822 Baca 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
, , DER
dan 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
- Menambahkan dukungan untuk
TDS8
. Untuk menggunakan TDS 8, pengguna harus menentukan Encrypt=Strict di string koneksi. #1608 Baca selengkapnya - Menambahkan dukungan untuk menentukan SPN Server dan SPN Server Failover pada koneksi. #1607 Baca selengkapnya
- Menambahkan dukungan untuk alias saat menargetkan .NET Core di Windows. #1588 Baca selengkapnya
- Menambahkan SqlDataSourceEnumerator. #1430, Baca selengkapnya
- Menambahkan sakelar AppContext baru untuk menekan peringatan TLS yang tidak aman. #1457, Baca selengkapnya
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.
HostNameInCertificate
dapat 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:
//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 menjaditrue
secara default. #1210 Baca selengkapnya - Driver sekarang memberikan
SqlException
penggantianAggregateException
untuk mode autentikasi direktori aktif. #1213 - Properti koneksi usang yang dihilangkan
Asynchronous Processing
dari .NET Framework. #1148 - Sakelar pengaman dihapus
Configurable Retry Logic
. #1254 Baca 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 Id
properti koneksi sekarang memerlukanClient Id
alih-alihObject Id
untuk Identitas Terkelola yang Ditetapkan Pengguna #1010 Baca selengkapnyaSqlDataReader
sekarang mengembalikanDBNull
nilai alih-alih kosongbyte[]
. Perilaku warisan dapat diaktifkan dengan mengaturAppContext
switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior #998 Baca 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/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 |
---|---|---|
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
SqlDataReader
DBNull
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:
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 SqlAuthenticationProviders
dari 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:
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(); }
Properti konfigurasi baru telah diperkenalkan di bawah
SqlAuthenticationProviderConfigurationSection
danSqlClientAuthenticationProviderConfigurationSection
:
[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 daripublic
keinternal
. - 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 kosongDataTable
sebagai gantinyanull
.- 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 danbin\x86
sekarang diberi namaMicrosoft.Data.SqlClient.SNI.x64.dll
danMicrosoft.Data.SqlClient.SNI.x86.dll
dan diunduh kebin
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 SqlConnectionStringBuilder.
Properti string koneksi yang ada | Sinonim Baru |
---|---|
ApplicationIntent | Niat Aplikasi |
ConnectRetryCount | Hubungkan Jumlah Coba Lagi |
ConnectRetryInterval | Sambungkan Interval Coba Lagi |
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.
Pengalihan buka koneksi
Perilaku default SqlConnection.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 SqlConnection.Open() dan bukan SqlConnection.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:
- Dukungan SqlClient untuk Always Encrypted
- 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 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
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)