Sdílet prostřednictvím

Úvod do namespace Microsoft.Data.SqlClient

  • Článek

Stáhnout ADO.NET

Obor názvů Microsoft.Data.SqlClient je v podstatě nová verze oboru názvů System.Data.SqlClient. Microsoft.Data.SqlClient obecně udržuje stejné rozhraní API a zpětnou kompatibilitu se System.Data.SqlClient. Migrace z System.Data.SqlClient na Microsoft.Data.SqlClient je pro většinu aplikací jednoduchá. Přidejte závislost NuGet na Microsoft.Data.SqlClient a aktualizujte odkazy a using příkazy do Microsoft.Data.SqlClient.

V méně používaných rozhraních API existuje několik rozdílů oproti System.Data.SqlClient, které můžou mít vliv na některé aplikace. Pro tyto rozdíly naleznete užitečný přehled pro adaptaci.

Referenční informace k rozhraní API

Podrobnosti rozhraní Microsoft.Data.SqlClient API najdete v prohlížeči rozhraní .NET API.

Poznámky k verzi pro Microsoft.Data.SqlClient 6.0

Zásadní změny ve verzi 6.0

  • Vyřazená podpora pro .NET Standard #2386
  • Vyřazená podpora pro .NET 6 č. 2927
  • Vyřazené odkazy na UWP (UAP). #2483
  • Zrušena podpora pro ladění na straně klienta pro SQL 2000 v rozhraní .NET Framework #2981, #2940

Nové funkce ve verzi 6.0

  • Přidání podpory pro datový typ JSON #2916, #2892, #2891, #2880, #2882, #2829, #2830
  • Přidání podpory pro .NET 9 č. 2946
  • Přidán typ Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic v rozhraní .NET. #2226
  • Byla přidána podpora pro DateOnly a TimeOnly do DataTable jako strukturovaného parametru. č. 2258
  • Přidání podpory pro SqlConnectionOverrides v OpenAsync() API č. 2433
  • Byla přidána lokalizace v češtině, polštině a turečtině č. 2987
  • Byl přidán objekt TokenCredential pro využití mezipaměti tokenů v ActiveDirectoryAuthenticationProvider. #2380
  • Přidání souboru readme do balíčku NuGet #2826
  • Povolili jsme auditování balíčků NuGet prostřednictvím zdroje auditu NuGet.org #3024
  • Přidání chybějící ukázky kódu SqlCommand_BeginExecuteReader #3009
  • Přidáno trasování oboru pro GenerateSspiClientContext. č. 2497, č. 2725

Podpora datových typů JSON

Podpora datových typů JSON je nyní dostupná v Microsoft.Data.SqlClient verze 6.0. Tato verze představuje SqlJson typ dostupný jako rozšíření pro System.Data.SqlDbTypes:

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

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

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

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

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

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

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

Datový typ JSON podporuje operace čtení, zápisu, streamování a hromadného kopírování.

Představujeme SqlClientDiagnostics

V oboru názvů Microsoft.Data.SqlClient.Diagnostics jsou k dispozici nové typy, které poskytují silně typovanou kolekci párů klíč-hodnota. Tyto typy je možné zachytit pomocí aplikací pro shromažďování diagnostických událostí vygenerovaných ovladačem. Tato verze zavádí následující typy:

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

Přidána podpora pro přepsání připojení v API OpenAsync()

Výchozí chování SqlConnection.OpenAsync() je možné přepsat, aby se zakázalo desetisekundové zpoždění a automatické opakování připojení aktivované přechodnými chybami.

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

Podpora cílové platformy 6.0

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

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: poznámky k verzi 6.0.

Poznámky k verzi pro Microsoft.Data.SqlClient 5.2

Nové funkce ve verzi 5.2

  • Přidána podpora SqlDiagnosticListener na standardu .NET. #1931
  • Byla přidána nová vlastnost RowsCopied64 do SqlBulkCopy. #2004Přečíst více
  • Přidání nového rozhraní API AccessTokenCallBack do SqlConnection. č. 1260Přečtěte si další
  • Přidání podpory pro možnost registru SuperSocketNetLib pro Šifrování v .NET ve Windows. #2047
  • Byla přidána podpora SqlBatch na platformě .NET 6+ #1825, #2223Přečtěte si více
  • Přidání podpory ověřování identit úloh #2159, č. 2264
  • Přidání podpory lokalizace v rozhraní .NET #2210
  • Byla přidána podpora pro gruzínské řazení #2194
  • Přidání podpory pro systémy Big Endian #2170
  • Přidání podpory rozhraní .NET 8 #2230
  • Přidána explicitní verze pro hlavní závislosti na verzi .NET: System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 a System.Diagnostics.DiagnosticSource 8.0.0 #2303
  • Byla přidána možnost generovat ladicí symboly v samostatném balíčkovém souboru #2137

Přidání nové vlastnosti RowsCopied64 do sqlBulkCopy

SqlBulkCopy má novou vlastnost RowsCopied64, která podporuje typy hodnot long.

Všimněte si, že stávající chování SqlBulkCopy.RowsCopied se nezmění. Pokud hodnota překročí int.MaxValue, RowsCopied může vrátit záporné číslo.

Příklad použití:

    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;
            }
        }
    }

Přidání nové vlastnosti AccessTokenCallBack do sqlConnection

SqlConnection podporuje ověřování TokenCredential zavedením nové vlastnosti AccessTokenCallBack jako delegáta Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>> pro vrácení federovaného přístupového tokenu ověřování.

Příklad použití:

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

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

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

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

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

SqlBatch API

Příklad použití:

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 Podpora cílové platformy

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

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 5.2 poznámky k verzi.

Zásadní změny ve verzi 5.1

Nové funkce ve verzi 5.1

  • Přidána podpora pro DateOnly a TimeOnly, pro hodnotu SqlParameter a GetFieldValue. #1813
  • Přidání podpory protokolu TLS 1.3 pro .NET Core a SNI Native #1821
  • Bylo přidáno nastavení ServerCertificate pro Encrypt=Mandatory nebo Encrypt=Strict. č. 1822Přečtěte si další
  • Přidání podpory Windows Arm64 při cílení na rozhraní .NET Framework #1828

Certifikát serveru

Výchozí hodnota nastavení připojení ServerCertificate je prázdný řetězec. Pokud je Encrypt nastavena na Mandatory nebo Strict, lze ServerCertificate použít k určení cesty v systému souborů k souboru certifikátu, který se má shodovat s certifikátem TLS/SSL serveru. Zadaný certifikát musí přesně odpovídat, aby byl platný. Přijaté formáty certifikátů jsou PEM, DERa CER. Tady je příklad použití:

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

Podpora cílové platformy

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

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 5.1 poznámky k verzi.

Poznámky k verzi pro Microsoft.Data.SqlClient 5.0

Zásadní změny ve verzi 5.0

  • Vyřazená podpora rozhraní .NET Framework 4.6.1 č. 1574
  • Byla přidána závislost na balíček Microsoft.SqlServer.Server. Tato nová závislost může způsobit konflikty oborů názvů, pokud vaše aplikace odkazuje na tento obor názvů a stále obsahuje odkazy na balíčky (přímé nebo nepřímé) na System.Data.SqlClient z .NET Core.
  • Vyřazené třídy z oboru názvů Microsoft.Data.SqlClient.Server a nahrazené podporovanými typy z balíčku Microsoft.SqlServer.Server.č. 1585. Ovlivněné třídy a výčty jsou:
    • 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
    • (výčet) Microsoft.Data.SqlClient.Server.DataAccessKind –> Microsoft.SqlServer.Server.DataAccessKind
    • (enum) Microsoft.Data.SqlClient.Server.Format –> Microsoft.SqlServer.Server.Format
    • (výčet) Microsoft.Data.SqlClient.Server.SystemDataAccessKind –> Microsoft.SqlServer.Server.SystemDataAccessKind

Nové funkce ve verzi 5.0

  • Byla přidána podpora pro TDS8. Pokud chcete použít TDS 8, měli by uživatelé v připojovacím řetězci zadat Encrypt=Strict. č. 1608Další informace
  • Přidána podpora pro zadání SPN serveru a SPN serveru pro převzetí služeb při selhání v připojení. č. 1607Přečtěte si další
  • Přidání podpory aliasů při cílení na .NET Core ve Windows #1588Přečtěte si více
  • Byl přidán SqlDataSourceEnumerator. č. 1430, Další
  • Přidání nového přepínače AppContext pro potlačení nezabezpečených upozornění protokolu TLS č. 1457, Další

Rozšířené zabezpečení TDS 8

Pokud chcete použít TDS 8, v připojovacím řetězci zadejte Encrypt=Strict. Striktní režim zakáže TrustServerCertificate (vždy se považuje za False v přísném režimu). Přidali jsme hostNameInCertificate, aby pomohl některé scénáře striktního režimu. TDS 8 začíná a pokračuje ve veškeré komunikaci serveru uvnitř zabezpečeného šifrovaného připojení TLS.

Byly přidány nové hodnoty Šifrování, které objasňují chování šifrování připojení. Encrypt=Mandatory je ekvivalentní Encrypt=True a šifruje připojení během vyjednávání připojení TDS. Encrypt=Optional je ekvivalentní Encrypt=False a zašifruje připojení pouze v případě, že server klientovi řekne, že při vyjednávání připojení TDS se vyžaduje šifrování.

Další informace o šifrování připojení k serveru naleznete v tématu Šifrování a ověřování certifikátů.

HostNameInCertificate lze zadat v připojovacím řetězci při použití aliasů pro připojení k serveru, který má certifikát serveru s jiným názvem nebo jiným názvem subjektu než název používaný klientem k identifikaci serveru (například aliasy DNS). Příklad použití: HostNameInCertificate=MyDnsAliasName

SPN serveru

Při připojování v prostředí, které má jedinečnou topografii domény/lesa, můžete mít specifické požadavky na SPN serveru. Nastavení připojovacího řetězce pro ServerSPN/Server SPN a FailoverServerSPN/Failover Server SPN lze použít k přepsání automaticky generovaných hlavních názvů služeb serveru, které se využívají během integrovaného ověřování v prostředí domény.

Podpora aliasů SQL

Uživatelé mohou konfigurovat aliasy pomocí nástroje SQL Server Configuration Manager. Tyto aliasy jsou uložené v registru Systému Windows a jsou již podporovány při cílení na rozhraní .NET Framework. Tato verze přináší podporu aliasů při cílení na .NET nebo .NET Core ve Windows.

Podpora enumerátoru zdroje dat SQL

Poskytuje mechanismus pro výčet všech dostupných instancí SQL Serveru v rámci místní sítě.

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("============================");  
    }  
  }

Potlačení varování před nezabezpečeným TLS

Upozornění zabezpečení je výstupem konzoly, pokud se k vyjednávání se serverem používá verze protokolu TLS menší než 1.2. Toto upozornění může být potlačeno při připojení SQL, pokud je Encrypt = false, povolením následujícího přepínače AppContext při spuštění aplikace.

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Podpora cílové platformy 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)

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 5.0 poznámky k verzi.

Poznámky k verzi pro Microsoft.Data.SqlClient 4.1

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: poznámky k verzi 4.1.

Nové funkce ve verzi 4.1

Zavedení protokolu pro ověření - None

V připojovacím řetězci je povolený nový protokol ověření identity s názvem None. Tento protokol umožňuje uživatelům obejít atestaci enklávy pro VBS enklávy. Při nastavení tohoto protokolu je vlastnost URL ověření identity enklávy volitelná.

Příklad připojovacího řetězce:

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

4.1 Podpora cílové platformy

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

Poznámky k verzi pro Microsoft.Data.SqlClient 4.0

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 4.0 poznámky k verzi.

Zásadní změny ve verzi 4.0

  • Byla změněna vlastnost připojovacího řetězce Encrypt tak, aby byla true ve výchozím nastavení. #1210Číst více
  • Ovladač nyní generuje SqlException, čímž nahrazuje AggregateException pro režimy ověřování služby Active Directory. #1213
  • Vyřazená zastaralá vlastnost připojení Asynchronous Processing z rozhraní .NET Framework. č. 1148
  • Odstraněn bezpečnostní spínač Configurable Retry Logic. č. 1254Další
  • Vyřazená podpora pro .NET Core 2.1 č. 1272
  • [.NET Framework] Výjimka se nevyvolá, pokud je v připojovacím řetězci při použití ověřování Active Directory Integrated zadáno ID uživatele #1359.

Nové funkce ve verzi 4.0

Zašifrovat výchozí hodnotu nastavenou na true

Výchozí hodnota nastavení připojení Encrypt byla změněna z false na true. S rostoucím využitím cloudových databází a nutností zajistit, aby tato připojení byla zabezpečená, je čas na tuto změnu narušující zpětnou kompatibilitu.

Zajištění selhání připojení v případě, že je vyžadováno šifrování

Ve scénářích, kdy byly zakázané nebo nedostupné klientské šifrovací knihovny, bylo možné provést nešifrovaná připojení, když byla funkce Encrypt nastavena na true nebo server vyžadoval šifrování.

Přepínač kontextu aplikace pro použití výchozích protokolů systému

Ovladač nepodporuje protokol TLS 1.3; proto byl ve výchozím nastavení odebrán ze seznamu podporovaných protokolů. Uživatelé můžou přepnout zpět na vynucení použití klientských protokolů operačního systému povolením následujícího přepínače kontextu aplikace:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Povolení optimalizované vazby parametrů

Microsoft.Data.SqlClient zavádí nové rozhraní API SqlCommand, EnableOptimizedParameterBinding ke zlepšení výkonu dotazů s velkým počtem parametrů. Tato vlastnost je ve výchozím nastavení zakázaná. Při nastavení na truese názvy parametrů při spuštění příkazu neodesílají do instance SQL Serveru.

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

Odebrání konfigurovatelného bezpečnostního přepínače logiky opakování

Již není potřeba používat přepínač kontextu aplikace "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" k tomu, aby byla použita konfigurovatelná logika opakování. Tato funkce je teď podporovaná v produkčním prostředí. Výchozí chování funkce je i nadále zásadou bez opakování, kterou klientské aplikace musí přepsat, aby bylo možné opakování povolit.

Podpora sdílených instancí SqlLocalDb

Sdílené instance SqlLocalDb se teď podporují při použití spravovaného SNI.

  • Možné scénáře:
    • (localdb)\. (připojení k výchozí instanci SqlLocalDb)
    • (localdb)\<named instance>
    • (localdb)\.\<shared instance name> (*nově přidaná podpora)

podpora GetFieldValueAsync<T> a GetFieldValue<T> pro typy XmlReader, TextReader, Stream

XmlReader, TextReader, Stream typy jsou nyní podporovány při použití GetFieldValueAsync<T> a GetFieldValue<T>.

Příklad použití:

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
                }
            }
        }
    }
}

4.0 Podpora cílové platformy

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

Poznámky k verzi pro Microsoft.Data.SqlClient 3.0

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 3.0 poznámky k verzi.

Zásadní změny ve verzi 3.0

  • Minimální podporovaná verze rozhraní .NET Framework byla zvýšena na verzi 4.6.1. Rozhraní .NET Framework v4.6.0 se už nepodporuje. #899
  • Vlastnost připojení User Id teď vyžaduje Client Id místo Object Id pro User-Assigned spravovanou identitu#1010Další informace
  • SqlDataReader nyní vrátí hodnotu DBNull místo prázdného byte[]. Dědičné chování lze povolit nastavením přepínače AppContext switch Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Přečtěte si více

Nové funkce ve verzi 3.0

Konfigurovatelná logika opakování

Tato nová funkce zavádí konfigurovatelnou podporu pro klientské aplikace, aby mohly znovu zkusit operaci při "přechodných" nebo "znovu proveditelných" chybách. Konfiguraci je možné provést prostřednictvím konfiguračních souborů kódu nebo aplikace a operaci opakování je možné použít k otevření připojení nebo spuštění příkazu. Tato funkce je ve výchozím nastavení zakázaná a aktuálně je ve verzi Preview. Aby bylo možné tuto podporu povolit, musí klientské aplikace zapnout následující bezpečnostní spínač:

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

Po povolení přepínače .NET AppContext je možné definovat zásady logiky opakování pro SqlConnection a SqlCommand nezávisle nebo společně pomocí různých možností přizpůsobení.

Nová veřejná rozhraní API se zavádějí v SqlConnection a SqlCommand pro registraci vlastní implementace SqlRetryLogicBaseProvider:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Příklady použití rozhraní API najdete tady:

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)
};

Byly zavedeny také nové oddíly konfigurace, které umožňují stejnou registraci z konfiguračních souborů, aniž by bylo nutné upravovat stávající kód:

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

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

Tady je jednoduchý příklad použití nových konfiguračních oddílů v konfiguračních souborech:

<?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>

Alternativně mohou aplikace implementovat poskytovatele základní třídy SqlRetryLogicBaseProvider a zaregistrovat jej v SqlConnection/SqlCommand.

Počítadla událostí

Pro aplikace, které cílí na .NET Core 3.1 nebo novější a .NET Standard 2.1+, jsou nyní k dispozici následující čítače:

Jméno Zobrazovaný název Popis
aktivních pevných připojení Skutečná aktivní připojení aktuálně vytvořená k serverům Počet aktuálně otevřených připojení k databázovým serverům.
natvrdo připojuje Skutečná rychlost připojení k serverům Počet připojení za sekundu, která se otevírají k databázovým serverům.
pevné odpojení Skutečná rychlost odpojení od serverů Počet odpojení za sekundu od databázových serverů.
typu aktivní-soft-připojení Připojení načtená z fondu aktivních připojení Počet již otevřených připojení spotřebovaných z fondu připojení.
měkké připojení Rychlost připojení načtených z fondu připojení Počet připojení za sekundu spotřebovaný z fondu připojení.
měkké odpojení Rychlost připojení vrácených do fondu připojení Počet připojení vrácených za sekundu do fondu připojení.
počet nepřidělených do fondu připojení Počet připojení, která nepoužívají sdružování připojení Počet aktivních připojení, která nejsou sdružována.
počet sdružených připojení Počet připojení spravovaných fondem připojení Počet aktivních připojení spravovaných infrastrukturou sdružování připojení.
počet aktivních skupin fondu připojení Počet aktivních jedinečných připojovacích řetězců Počet aktivních, jedinečných skupin fondu připojení. Tento čítač je založen na počtu jedinečných připojovacích řetězců nalezených v doméně AppDomain.
počet skupin neaktivních připojovacích poolů Počet jedinečných připojovacích řetězců čekajících na odstranění Počet jedinečných skupin fondu připojení označených k vyřazení. Tento čítač je založen na počtu jedinečných připojovacích řetězců nalezených v doméně AppDomain.
počet fondů aktivních připojení Počet aktivních připojení Celkový počet spojovacích poolů.
počet neaktivních fondů připojení Počet neaktivních připojovacích fondů Počet neaktivních fondů připojení, které neměly nedávnou aktivitu a čekají na odstranění.
počet aktivních připojení Počet aktivních připojení Počet aktuálně platných aktivních připojení.
počet bezplatných připojení Počet připravených připojení ve fondu připojení Počet volných připojení dostupných pro použití ve fondech připojení.
počet připojení ke stasis Počet připojení, která aktuálně čekají na připravenost Počet připojení, která aktuálně čekají na dokončení akce a které nejsou k dispozici pro použití aplikací.
počet uvolněných připojení Počet uvolněných připojení z GC Počet připojení uvolněných prostřednictvím mechanismu uvolňování paměti, aniž by je aplikace zavolala pomocí Close nebo Dispose. Poznámka Nezavírání nebo neukončování připojení má negativní vliv na výkon.

Tyto čítače lze použít s globálními nástroji rozhraní příkazového řádku .NET Core: dotnet-counters a dotnet-trace v systémech Windows nebo Linux a v systému Windows s PerfView pomocí Microsoft.Data.SqlClient.EventSource jako názvu zprostředkovatele. Další informace najdete v tématu Načtení hodnot čítačů událostí.

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

Úvod do závislosti na identitě Azure

Microsoft.Data.SqlClient teď závisí na knihovně Azure.Identity k získání tokenů pro režimy ověřování Active Directory Managed Identity/MSI a Active Directory Service Principal. Tato změna přináší do veřejné plochy následující změny:

  • zásadní změna
    Vlastnost připojení "ID uživatele" teď vyžaduje "ID klienta" místo "ID objektu" pro "User-Assigned spravovanou identitu".
  • veřejné rozhraní API
    Nová veřejná vlastnost pouze pro čtení: SqlAuthenticationParameters.ConnectionTimeout
  • Závislost
    Azure.Identity v1.3.0

Vylepšení trasování událostí v SNI.dll

verze Microsoft.Data.SqlClient.SNI (závislost rozhraní .NET Framework) a Microsoft.Data.SqlClient.SNI.runtime (závislost .NET Core/Standard) byly aktualizovány na v3.0.0-preview1.21104.2. Trasování událostí v SNI.dll už není povolené prostřednictvím klientské aplikace. Přihlášení relace k poskytovateli Microsoft.Data.SqlClient.EventSource prostřednictvím nástrojů, jako jsou xperf nebo perfview, je dostatečné. Další informace naleznete v tématu Podpora trasování událostí v Native SNI .

Povolení chování verze řádku s hodnotou null

SqlDataReader místo prázdného byte[]vrátí hodnotu DBNull . Chcete-li povolit starší verzi chování, je nutné povolit následující přepínač AppContext při spuštění aplikace: "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"

Podpora výchozího ověřování Microsoft Entra

Poznámka

I když je Microsoft Entra ID novým názvem proAzure Active Directory (Azure AD), Azure AD stále zůstává v některých pevně zakódovaných prvcích, jako jsou pole uživatelského rozhraní, zprostředkovatelé připojení, kódy chyb a příkazy Cmdlet, aby nedošlo k narušení existujících prostředí. V tomto článku jsou tyto dva názvy zaměnitelné.

Tento pull request zavádí novou metodu ověřování SQL, Active Directory Default. Tento režim ověřování rozšiřuje možnosti ověřování uživatelů pomocí Microsoft Entra ID, rozšiřuje řešení přihlášení do klientského prostředí, editoru Visual Studio Code, sady Visual Studio, Azure CLI atd.

V tomto režimu ověřování získá ovladač token předánímDefaultAzureCredentialz knihovny Azure Identity pro získání přístupového tokenu. Tento režim se pokusí použít tyto typy přihlašovacích údajů k získání přístupového tokenu v následujícím pořadí:

  • Environmentální přihlašovací údaj
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí klientského ID a tajného klíče nebo uživatelského jména a hesla, údaje nakonfigurované v následujících proměnných prostředí: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Další podrobnosti)
  • OprávněníSpravovanéIdentity
    • Pokusí se ověřit pomocí Microsoft Entra ID prostřednictvím spravované identity, která byla přiřazena k prostředí pro nasazení. ID klienta spravované identity přiřazené uživatelem se načte z vlastnosti připojení "ID uživatele".
  • SharedTokenCacheCredential
    • Ověřuje se pomocí tokenů v místní mezipaměti sdílené mezi aplikacemi Microsoftu.
  • VisualStudioCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí dat ze sady Visual Studio.
  • VisualStudioCodeCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí dat z editoru Visual Studio Code.
  • AzureCliCredential
    • Umožňuje ověřování pomocí ID Microsoft Entra pomocí Azure CLI k získání přístupového tokenu.

InteractiveBrowserCredential je zakázána v implementaci ovladače "Active Directory Default" a "Active Directory Interactive" je jediná možnost, která je k dispozici k získání tokenu pomocí vícefaktorového ověřování nebo interaktivního ověřování.

V tuto chvíli nejsou k dispozici další možnosti přizpůsobení.

Vylepšení registrace poskytovatele úložiště hlavních klíčů na míru

Microsoft.Data.SqlClient teď nabízí větší kontrolu nad tím, kde jsou poskytovatelé hlavního úložiště klíčů přístupní v aplikaci, aby lépe podporovaly víceklientských aplikací a jejich použití šifrování a dešifrování sloupců. Zavádíme následující rozhraní API, která umožňují registraci vlastních poskytovatelů hlavního úložiště klíčů v instancích SqlConnection a SqlCommand:

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

Statické rozhraní API na SqlConnection, SqlConnection.RegisterColumnEncryptionKeyStoreProviders, používané k registraci poskytovatelů úložišť hlavních klíčů na míru globálně, je nadále podporováno. Mezipaměť šifrovacích klíčů sloupce, která je udržována globálně, se vztahuje pouze na globálně registrované poskytovatele.

Registrace poskytovatele úložiště klíčů pro hlavní sloupec má přednost.

Předdefinované zprostředkovatele úložiště klíčů hlavního sloupce, které jsou k dispozici pro Windows Certificate Store, CNG Store a CSP, jsou předregistrované. Pokud je potřeba použít některého z předdefinovaných zprostředkovatelů úložiště hlavního klíče pro sloupce, neměli by být na připojení nebo u instancí příkazů registrováni žádní zprostředkovatelé.

Poskytovatelé úložiště hlavních klíčů mohou být zaregistrováni u ovladače ve třech různých vrstvách. Globální úroveň je taková, jaká aktuálně je. Nové registrace na úrovni připojení a jednotlivých příkazů jsou zpočátku prázdné a lze je nastavit více než jednou.

Přednosti těchto tří registrací jsou následující:

  • Registrace pro jednotlivé příkazy je zkontrolována, pokud není prázdná.
  • Pokud je registrace pro jednotlivé příkazy prázdná, zkontroluje se, jestli registrace připojení není prázdná.
  • Pokud je registrace podle připojení prázdná, zkontroluje se globální registrace.

Jakmile je jakýkoli poskytovatel úložiště klíčů nalezen na úrovni registrace, ovladač NE přechází zpět k ostatním registracím, aby hledal poskytovatele. Pokud jsou poskytovatelé zaregistrovaní, ale správný poskytovatel se nenajde na úrovni, vyvolá se výjimka obsahující pouze registrované poskytovatele v kontrolované registraci.

Priorita mezipaměti sloupcového šifrovacího klíče

Ovladač neukládá do mezipaměti šifrovací klíče sloupců (CEKs) pro poskytovatele vlastního úložiště klíčů, kteří jsou zaregistrováni pomocí nových rozhraní API na úrovni instance. Aby poskytovatelé úložiště klíčů mohli dosáhnout výkonu, musí implementovat vlastní mezipaměť. Ovladač zakáže místní mezipaměť šifrovacích klíčů sloupců implementovaných vlastními poskytovateli úložiště klíčů, pokud je instance zprostředkovatele úložiště klíčů zaregistrovaná v ovladači na globální úrovni.

Bylo také zavedeno nové rozhraní API v základní třídě SqlColumnEncryptionKeyStoreProvider pro nastavení doby životnosti cache:

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);
}

Předvolba IP adres

Při vytváření připojení TCP se zavádí nová vlastnost připojení IPAddressPreference, která ovladači určí předvolbu rodiny IP adres. Pokud je Transparent Network IP Resolution (v rozhraní .NET Framework) nebo Multi Subnet Failover nastavená na true, toto nastavení nemá žádný vliv. Pro tuto vlastnost existují tři přijaté hodnoty:

  • IPv4First

    • Tato hodnota je výchozí. Ovladač nejprve používá vyřešené adresy IPv4. Pokud se k žádnému z nich nelze úspěšně připojit, pokusí se vyřešit adresy IPv6.

  • IPv6First

    • Ovladač nejprve používá vyřešené adresy IPv6. Pokud se k žádné z nich nelze připojit, zkusí se připojit k vyřešeným adresám IPv4.

  • UsePlatformDefault

    • Ovladač zkouší IP adresy v pořadí, v jakém byly přijaty z odpovědi překladu DNS.

3.0 Podpora cílové platformy

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

Poznámky k verzi pro Microsoft.Data.SqlClient 2.1

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 2.1 poznámky k verzi.

Nové funkce ve verzi 2.1

Podpora více platforem pro Always Encrypted

Microsoft.Data.SqlClient v2.1 rozšiřuje podporu funkce Always Encrypted na následujících platformách:

Podpora funkce Always Encrypted Podpora funkce Always Encrypted pomocí zabezpečené enklávy Cílový rámec Verze Microsoft.Data.SqlClient Operační systém
Ano Ano .NET Framework 4.6 nebo novější 1.1.0+ Windows
Ano Ano .NET Core 2.1 nebo novější 2.1.0+1 Windows, Linux, macOS
Ano Bez2 .NET Standard 2.0 2.1.0+ Windows, Linux, macOS
Ano Ano .NET Standard 2.1+ 2.1.0+ Windows, Linux, macOS

Poznámka

1 Před verzí Microsoft.Data.SqlClient verze 2.1 se funkce Always Encrypted podporuje pouze ve Windows.

2 Funkce Always Encrypted se zabezpečenými enklávy se v .NET Standard 2.0 nepodporuje.

Ověřování toku kódu zařízení Microsoft Entra

Microsoft.Data.SqlClient v2.1 poskytuje podporu ověřování toku kódu zařízení pomocí MSAL.NET. Referenční dokumentace: tok udělení oprávnění zařízení OAuth2.0

Příklad připojovacího řetězce:

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

Následující rozhraní API umožňuje přizpůsobení mechanismu zpětného volání toku kódu zařízení:

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

Ověřování identit spravovaných službou Microsoft Entra

Microsoft.Data.SqlClient v2.1 zavádí podporu ověřování Microsoft Entra pomocí spravovaných identit.

Podporují se následující klíčová slova režimu ověřování:

  • Spravovaná identita služby Active Directory
  • Active Directory MSI (pro kompatibilitu ovladačů mezi MS SQL)

Příklady připojovacího řetězce:

// 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};"

Interaktivní vylepšení ověřování Microsoft Entra

Microsoft.Data.SqlClient v2.1 přidává následující rozhraní API pro přizpůsobení prostředí microsoft Entra Interactive ověřování:

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 oddíl konfigurace

Microsoft.Data.SqlClient v2.1 zavádí nový oddíl konfigurace, SqlClientAuthenticationProviders (klon existujícího SqlAuthenticationProviders). Stávající oddíl konfigurace, SqlAuthenticationProviders, je stále podporován pro zpětnou kompatibilitu, pokud je definován příslušný typ.

Nová část umožňuje konfiguračním souborům aplikace obsahovat oddíl SqlAuthenticationProviders pro System.Data.SqlClient a oddíl SqlClientAuthenticationProviders pro Microsoft.Data.SqlClient.

Ověřování Microsoft Entra pomocí ID klienta aplikace

Microsoft.Data.SqlClient v2.1 zavádí podporu předávání ID klienta aplikace definované uživatelem do knihovny Microsoft Authentication Library. ID klienta aplikace se používá při ověřování pomocí Microsoft Entra ID.

Zavádí se následující nová rozhraní API:

  1. Nový konstruktor byl zaveden v ActiveDirectoryAuthenticationProvider:
    [platí pro všechny platformy .NET (.NET Framework, .NET Core a .NET Standard)]

    public ActiveDirectoryAuthenticationProvider(string applicationClientId)

    Použití:

    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. Nová vlastnost konfigurace byla zavedena v rámci SqlAuthenticationProviderConfigurationSection a SqlClientAuthenticationProviderConfigurationSection:
    [platí pro rozhraní .NET Framework a .NET Core]

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

// Inheritance
internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
{ ... }

    Použití

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

Podpora klasifikace dat v2

Microsoft.Data.SqlClient v2.1 zavádí podporu pro informace klasifikace dat "Rank citlivosti". Nyní jsou k dispozici následující nová rozhraní API:

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 procesu serveru pro aktivní SqlConnection

Microsoft.Data.SqlClient v2.1 zavádí novou vlastnost SqlConnection, ServerProcessId, v aktivním připojení.

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

Podpora trasovacího protokolování v nativním SNI

Microsoft.Data.SqlClient v2.1 rozšiřuje stávající implementaci SqlClientEventSource, aby bylo možné trasování událostí v SNI.dll. Události musí být zachyceny pomocí nástroje, jako je Xperf.

Trasování je možné povolit odesláním příkazu do SqlClientEventSource, jak je znázorněno na obrázku:

// 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);

Vlastnost řetězce připojení "Command Timeout"

Microsoft.Data.SqlClient v2.1 zavádí vlastnost připojovacího řetězce "Časový limit příkazu", která umožňuje přepsat výchozí hodnotu 30 sekund. Časový limit jednotlivých příkazů lze přepsat pomocí vlastnosti CommandTimeout v sqlCommand.

Příklady připojovacího řetězce:

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

Odebrání symbolů z nativního SNI

S Microsoft.Data.SqlClient v2.1 jsme odebrali symboly zavedené v v2.0.0 z Microsoft.Data.SqlClient.SNI.runtime NuGet počínaje v2.1.1. Veřejné symboly se teď publikují na Microsoft Symbols Serveru pro nástroje, jako je BinSkim, které vyžadují přístup k veřejným symbolům.

Source-Linking symbolů Microsoft.Data.SqlClient

Počínaje verzí Microsoft.Data.SqlClient v2.1 jsou symboly Microsoft.Data.SqlClient zdrojově propojené a publikované na serveru Microsoft Symbols pro vylepšené ladění bez nutnosti stahovat zdrojový kód.

2.1 Podpora cílových platforem

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

Poznámky k verzi pro Microsoft.Data.SqlClient 2.0

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 2.0 poznámky k verzi.

Zásadní změny ve verzi 2.0

  • Modifikátor přístupu pro rozhraní zprostředkovatele enklávy SqlColumnEncryptionEnclaveProvider byl změněn z public na internal.
  • Konstanty ve třídě SqlClientMetaDataCollectionNames byly aktualizovány tak, aby odrážely změny v SQL Serveru.
  • Ovladač teď provádí ověření certifikátu serveru, když cílový SQL Server vynucuje šifrování TLS, což je výchozí nastavení pro připojení Azure.
  • SqlDataReader.GetSchemaTable() nyní místo nullvrátí prázdný DataTable .
  • Ovladač teď provádí zaokrouhlování desetinných míst tak, aby odpovídalo chování SQL Serveru. Kvůli zpětné kompatibilitě je možné předchozí chování zkrácení povolit pomocí přepínače AppContext.
  • Pro aplikace rozhraní .NET Framework, které využívají Microsoft.Data.SqlClient, se soubory SNI.dll dříve stažené do bin\x64 a složek bin\x86 nazývají Microsoft.Data.SqlClient.SNI.x64.dll a Microsoft.Data.SqlClient.SNI.x86.dll a stáhnou se do adresáře bin.
  • Nová synonyma vlastností připojovacího řetězce nahrazují staré vlastnosti při načítání připojovacího řetězce z SqlConnectionStringBuilder pro konzistenci. Přečtěte si více

Nové funkce ve verzi 2.0

V Microsoft.Data.SqlClient 2.0 byly zavedeny následující nové funkce.

Odolnost proti selhání DNS

Ovladač teď ukládá IP adresy z každého úspěšného připojení ke koncovému bodu SQL Serveru, který tuto funkci podporuje. Pokud během pokusu o připojení dojde k selhání překladu DNS, ovladač se pokusí navázat připojení pomocí IP adresy uložené v mezipaměti pro tento server, pokud existuje.

Trasování zdroje událostí

Tato verze představuje podporu zachycení záznamů trasování událostí pro ladění aplikací. Aby se tyto události zachytily, klientské aplikace musí naslouchat událostem z implementace EventSource sqlClient:

Microsoft.Data.SqlClient.EventSource

Další informace naleznete v tématu Povolení trasování událostí v SqlClient.

Povolení spravovaných sítí ve Windows

Nový přepínač AppContext, "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", umožňuje používat spravovanou implementaci SNI ve Windows pro účely testování a ladění. Tento přepínač přepíná chování ovladače tak, aby používal spravovaný SNI v projektech .NET Core 2.1+ a .NET Standard 2.0+ ve Windows a eliminuje všechny závislosti na nativních knihovnách pro knihovnu Microsoft.Data.SqlClient.

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

Úplný seznam dostupných přepínačů v ovladači najdete v tématu Přepínače AppContext v sqlClient.

Povolení zkracování desetinných míst

Ovladač ve výchozím nastavení zaokrouhluje měřítko desetinných dat stejně jako SQL Server. Pro zpětnou kompatibilitu můžete nastavit přepínač AppContext "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" na true.

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

Nová synonyma vlastností připojovacího řetězce

Byla přidána nová synonyma pro následující existující vlastnosti připojovacího řetězce, aby nedocházelo k nejasnostem mezi vlastnostmi s více než jedním slovem. Staré názvy vlastností jsou nadále podporovány kvůli zpětné kompatibilitě. Nové vlastnosti připojovacího řetězce jsou nyní zahrnuty při načítání připojovacího řetězce z SqlConnectionStringBuilder.

Stávající vlastnost připojovacího řetězce Nové synonymum
Záměr aplikace Záměr aplikace
ConnectRetryCount Počet opakování připojení
ConnectRetryInterval Interval opakovaného připojení
Období blokování bazénu Období blokování bazénu
MultipleActiveResultSets Více aktivních sad výsledků
MultiSubnetFailover Převzetí služeb při selhání s více podsítěmi
Transparentní síťové IP rozlišení Transparentní řešení IP adres v síti
TrustServerCertificate Důvěřovat certifikátu serveru

SqlBulkCopy RowsCopied – vlastnost

Vlastnost RowsCopied poskytuje přístup jen pro čtení k počtu řádků, které byly zpracovány v probíhající operaci hromadného kopírování. Tato hodnota nemusí být nutně rovna poslednímu počtu řádků přidaných do cílové tabulky.

Přepsání otevřených připojení

Výchozí chování sqlConnection.Open() je možné přepsat, aby se zakázalo desetisekundové zpoždění a automatické opakování připojení aktivované přechodnými chybami.

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

Poznámka

Toto přepsání lze použít pro SqlConnection.OpenAsync(), počínaje verzí Microsoft.Data.SqlClient 6.0.0.

Podpora uživatelského jména pro interaktivní režim Active Directory

Uživatelské jméno lze zadat v připojovacím řetězci při použití režimu ověřování Microsoft Entra Interactive pro rozhraní .NET Framework i .NET Core.

Nastavte uživatelské jméno pomocí vlastnosti řetězce připojení ID uživatele nebo UID .

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

Rady objednávek pro SqlBulkCopy

Nápovědu k objednávce je možné poskytnout ke zlepšení výkonu operací hromadného kopírování v tabulkách s clusterovanými indexy. Další informace naleznete v sekci Operace hromadného kopírování.

Změny závislostí SNI

Microsoft.Data.SqlClient (.NET Core a .NET Standard) ve Windows je nyní závislý na Microsoft.Data.SqlClient.SNI.runtime, nahrazuje předchozí závislost na runtime.native.System.Data.SqlClient.SNI. Nová závislost přidává podporu pro platformu ARM spolu s již podporovanými platformami Arm64, x64 a x86 ve Windows.

2.0 Podpora cílové platformy

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

Poznámky k verzi pro Microsoft.Data.SqlClient 1.1.0

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 1.1 poznámky k verzi.

Nové funkce ve verzi 1.1

Always Encrypted se zabezpečenou enklávou

Funkce Always Encrypted je dostupná od Microsoft SQL Serveru 2016. Zabezpečené enklávy jsou dostupné od Microsoft SQL Serveru 2019. Pokud chcete použít funkci enklávy, připojovací řetězce by měly obsahovat požadovaný protokol ověření identity a adresu URL ověření identity. Například:

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

Další informace najdete tady:

1.1 Podpora cílových platforem

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

Poznámky k verzi pro Microsoft.Data.SqlClient 1.0

Počáteční verze oboru názvů Microsoft.Data.SqlClient nabízí více funkcí oproti existujícímu oboru názvů System.Data.SqlClient.

Úplné poznámky k verzi, včetně závislostí, jsou k dispozici v úložišti GitHub: 1.0 poznámky k verzi.

Nové funkce ve verzi 1.0

Nové funkce přes rozhraní .NET Framework 4.7.2 System.Data.SqlClient

  • Klasifikace dat – K dispozici v Azure SQL Database a Microsoft SQL Server 2019.

  • podpora UTF-8 – k dispozici v Microsoft SQL Serveru 2019.

Nové funkce přes .NET Core 2.2 System.Data.SqlClient

  • klasifikace dat – k dispozici ve službě Azure SQL Database a Microsoft SQL Server 2019.

  • podpora UTF-8 – k dispozici v Microsoft SQL Serveru 2019.

  • Ověřování – režim ověřování pomocí hesla ve službě Active Directory.

Klasifikace dat

Klasifikace dat přináší novou sadu rozhraní API, která poskytují informace o citlivosti a klasifikaci dat ve formátu pouze pro čtení o objektech načtených pomocí SqlDataReader, pokud podkladový zdroj tuto funkci podporuje a obsahuje metadata o citlivosti a klasifikaci dat. Podívejte se na ukázkovou aplikaci v Zjišťování a klasifikaci dat ve SqlClientu.

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
    }
}

Podpora UTF-8

Podpora UTF-8 nevyžaduje žádné změny kódu aplikace. Tyto změny SqlClient optimalizují komunikaci mezi klientem a serverem, když server podporuje UTF-8 a základní kolace sloupců je UTF-8. Viz část UTF-8 v části Co je nového v SQL Serveru 2019.

Vždy šifrováno se zabezpečenými enklávami

Obecně platí, že stávající dokumentace, která používá System.Data.SqlClient v rozhraní .NET Framework a integrované poskytovatele úložišť hlavního klíče sloupců, by nyní měla fungovat i s .NET Core.

Vývoj pomocí Always Encrypted s poskytovatelem dat rozhraní .NET Framework

Always Encrypted: Ochrana citlivých dat a uložení šifrovacích klíčů v úložišti certifikátů Windows

Autentizace

Různé režimy ověřování je možné zadat pomocí možnosti Ověřování připojovacího řetězce. Další informace naleznete v dokumentaci k sqlAuthenticationMethod.

Poznámka

Vlastní zprostředkovatelé úložiště klíčů, jako je poskytovatel služby Azure Key Vault, budou muset být aktualizováni, aby podporovali Microsoft.Data.SqlClient. Poskytovatelé enklávy budou muset podobně také aktualizovat podporu pro Microsoft.Data.SqlClient. Funkce Always Encrypted se podporuje pouze u cílů rozhraní .NET Framework a .NET Core. Nepodporuje se pro .NET Standard, protože v .NET Standard chybí určité šifrovací závislosti.

1.0 Podpora cílové platformy

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