Dela via

Introduktion till namnområdet Microsoft.Data.SqlClient

  • Artikel

Ladda ned ADO.NET

Namnområdet Microsoft.Data.SqlClient är i princip en ny version av namnområdet System.Data.SqlClient. Microsoft.Data.SqlClient upprätthåller vanligtvis samma API och bakåtkompatibilitet med System.Data.SqlClient. För de flesta program är det enkelt att migrera från System.Data.SqlClient till Microsoft.Data.SqlClient. Lägg till ett NuGet-beroende för Microsoft.Data.SqlClient och uppdatera referenser och using-instruktioner till Microsoft.Data.SqlClient.

Det finns några skillnader i mindre använda API:er jämfört med System.Data.SqlClient som kan påverka vissa program. För dessa skillnader, se det användbara portning fuskark.

API-referens

Informationen om API:et Microsoft.Data.SqlClient finns i .NET API Browser.

Viktig information för Microsoft.Data.SqlClient 6.0

Brytande ändringar i 6.0

  • Stöd för .NET Standard har tagits bort. #2386
  • Stöd för .NET 6 har släppts #2927
  • Referenser till UWP (UAP) har tagits bort. #2483
  • Borttaget SQL 2000-stöd för felsökning på klientsidan för .NET Framework #2981, #2940

Nya funktioner i 6.0

  • Stöd har lagts till för JSON-datatypen #2916, #2892, #2891, #2880, #2882, #2829, #2830
  • Stöd har lagts till för .NET 9 #2946
  • Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic typ har lagts till i .NET. #2226
  • Stöd för DateOnly och TimeOnly har lagts till i DataTable som en strukturerad parameter. #2258
  • Stöd har lagts till för SqlConnectionOverrides i OpenAsync() API #2433
  • Lade till lokalisering i tjeckiska, polska och turkiska #2987
  • Lade till TokenCredential objekt för att dra nytta av cachelagring av token i ActiveDirectoryAuthenticationProvider. #2380
  • Readme har lagts till i NuGet-paketet #2826
  • Aktiverat NuGet-paketgranskning via NuGet.org granskningskälla #3024
  • Lagt till saknat kodexempel SqlCommand_BeginExecuteReader #3009
  • Omfångsspårning har lagts till för GenerateSspiClientContext. #2497, #2725

Stöd för JSON-datatyp

Stöd för JSON-datatyp är nu tillgängligt i Microsoft.Data.SqlClient v6.0. Den här versionen introducerar den SqlJson typ som är tillgänglig som ett tillägg till 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 ; }
    }
}

JSON-datatypen stöder läs-, skriv-, strömnings- och masskopieringsåtgärder.

Introduktion till SqlClientDiagnostics

Nya typer är tillgängliga i Microsoft.Data.SqlClient.Diagnostics namnrymd som tillhandahåller en starkt typad samling nyckel-värdepar. Dessa typer kan samlas in genom att använda program för insamling av diagnostikhändelser som genereras av drivrutinen. Den här versionen introducerar följande typer:

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

Stöd har lagts till för åsidosättningar av anslutningar i OpenAsync() API

Standardbeteendet för SqlConnection.OpenAsync() kan åsidosättas för att inaktivera fördröjningen på tio sekunder och automatiska anslutningsförsök som utlöses av tillfälliga fel.

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

6.0 Stöd för målplattform

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

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-förrådet: 6.0 Versionsanteckningar.

Viktig information för Microsoft.Data.SqlClient 5.2

Nya funktioner i 5.2

  • Stöd för SqlDiagnosticListener har lagts till på .NET Standard. #1931
  • Den nya egenskapen RowsCopied64 har lagts till i SqlBulkCopy. #2004Läs mer
  • Lade till ett nytt AccessTokenCallBack API i SqlConnection. #1260Läs mer
  • Stöd har lagts till för SuperSocketNetLib registeralternativet för Kryptera på .NET i Windows. #2047
  • Stöd för SqlBatch har lagts till på .NET 6+ #1825, #2223Läs mer
  • Stöd för autentisering med workload identity har lagts till #2159, #2264
  • Stöd för lokalisering har lagts till på .NET #2210
  • Stöd har lagts till för georgisk sortering #2194
  • Stöd har lagts till för Big Endian-system #2170
  • .NET 8-stöd har lagts till #2230
  • En explicit version har lagts till för huvudsakliga .NET-versionsberoenden på System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 och System.Diagnostics.DiagnosticSource 8.0.0 #2303
  • Möjligheten att generera felsökningssymboler har lagts till i en separat paketfil #2137

Ny egenskap RowsCopied64 har lagts till i SqlBulkCopy

SqlBulkCopy har en ny egenskap RowsCopied64 som stöder long värdetyper.

Observera att det befintliga SqlBulkCopy.RowsCopied beteendet är oförändrat. När värdet överskrider int.MaxValuekan RowsCopied returnera ett negativt tal.

Exempel på användning:

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

Ny egenskap AccessTokenCallBack har lagts till i SqlConnection

SqlConnection stöder TokenCredential-autentisering genom att införa en ny AccessTokenCallBack-egenskap som en Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>>-delegat för att returnera en federerad autentiseringsåtkomsttoken.

Exempel på användning:

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

Exempel på användning:

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 Stöd för målplattform

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

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-repositoryt: 5.2 Versionsanteckningar.

Bakåtkompatibilitetsproblem i 5.1

  • Stöd för .NET Core 3.1 har tagits bort. #1704#1823

Nya funktioner i 5.1

  • Stöd har lagts till för DateOnly och TimeOnly för SqlParameter-värde och GetFieldValue. #1813
  • Stöd har lagts till för TLS 1.3 för .NET Core och SNI Native. #1821
  • Inställningen ServerCertificate har lagts till för Encrypt=Mandatory eller Encrypt=Strict. #1822Läs mer
  • Stöd för Windows Arm64 har lagts till när du riktar in dig på .NET Framework. #1828

Servercertifikat

Standardvärdet för inställningen ServerCertificate anslutning är en tom sträng. När Encrypt är inställt på Mandatory eller Strictkan ServerCertificate användas för att ange en sökväg i filsystemet till en certifikatfil som matchar serverns TLS/SSL-certifikat. Det angivna certifikatet måste vara en exakt matchning för att vara giltigt. De godkända certifikatformaten är PEM, DERoch CER. Här är ett användningsexempel:

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

5.1 Stöd för målplattform

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

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-förvaret: 5.1 Versionsanteckningar.

Viktig information för Microsoft.Data.SqlClient 5.0

Icke-bakåtkompatibla ändringar i 5.0

  • Slopat stöd för .NET Framework 4.6.1 #1574
  • Lade till ett beroende av Microsoft.SqlServer.Server--paketet. Det här nya beroendet kan orsaka namnområdeskonflikter om ditt program refererar till det namnområdet och fortfarande har paketreferenser (direkt eller indirekt) till System.Data.SqlClient från .NET Core.
  • Borttagna klasser från Microsoft.Data.SqlClient.Server-namnområdet och ersatte dem med typer som stöds från Microsoft.SqlServer.Server-paketet.#1585. De berörda klasserna och uppräkningarna är:
    • 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
    • (uppräkning) Microsoft.Data.SqlClient.Server.DataAccessKind –> Microsoft.SqlServer.Server.DataAccessKind
    • (uppräkning) Microsoft.Data.SqlClient.Server.Format –> Microsoft.SqlServer.Server.Format
    • (uppräkning) Microsoft.Data.SqlClient.Server.SystemDataAccessKind –> Microsoft.SqlServer.Server.SystemDataAccessKind

Nya funktioner i 5.0

  • Stöd har lagts till för TDS8. Om du vill använda TDS 8 ska användarna ange Encrypt=Strict i anslutningssträngen. #1608Läs mer
  • Stöd har lagts till för att ange SERVER SPN och SPN för redundansserver på anslutningen. #1607Läs mer
  • Stöd har lagts till för alias när du riktar in dig på .NET Core i Windows. #1588Läs mer
  • SqlDataSourceEnumerator har lagts till. #1430Läs mer
  • Lade till en ny AppContext-växel för att förhindra osäkra TLS-varningar. #1457, Läs mer

Förbättrad säkerhet för TDS 8

Om du vill använda TDS 8 anger du Encrypt=Strict i anslutningssträngen. Strikt läge inaktiverar TrustServerCertificate (behandlas alltid som Falskt i strikt läge). HostNameInCertificate har lagts till för att hjälpa vissa scenarier med strikt läge. TDS 8 börjar och fortsätter all serverkommunikation i en säker, krypterad TLS-anslutning.

Nya Krypteringsvärden har lagts till för att förtydliga beteendet för anslutningskryptering. Encrypt=Mandatory motsvarar Encrypt=True och krypterar anslutningar under TDS-anslutningsförhandlingen. Encrypt=Optional motsvarar Encrypt=False och krypterar bara anslutningen om servern meddelar klienten att kryptering krävs under TDS-anslutningsförhandlingen.

Mer information om hur du krypterar anslutningar till servern finns i Kryptering och certifikatverifiering.

HostNameInCertificate kan anges i anslutningssträngen när du använder alias för att ansluta med kryptering till en server som har ett servercertifikat med ett annat namn eller ett annat ämnesnamn än det namn som används av klienten för att identifiera servern (till exempel DNS-alias). Exempel på användning: HostNameInCertificate=MyDnsAliasName

Server SPN

När du ansluter i en miljö som har en unik domän-/skogstopografi kan du ha specifika krav för server-SPN. Anslutningssträngsinställningarna ServerSPN/Server SPN och FailoverServerSPN/Failover Server SPN kan användas för att åsidosätta de automatiskt genererade server-SPN:er som används vid integrerad autentisering i en domänmiljö

Stöd för SQL-alias

Användare kan konfigurera alias med hjälp av SQL Server Configuration Manager. Dessa alias lagras i Windows-registret och stöds redan när du riktar in dig på .NET Framework. Den här versionen ger stöd för alias när du riktar in dig på .NET eller .NET Core i Windows.

Stöd för SQL Data Source Enumerator

Tillhandahåller en mekanism för att räkna upp alla tillgängliga instanser av SQL Server i det lokala nätverket.

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

Ignorera osäkra TLS-varningar

En säkerhetsvarning skrivs ut på konsolen när TLS-versionen som används för att förhandla med servern är mindre än 1.2. Den här varningen kan undertryckas vid SQL-anslutning när Encrypt = false är aktiverad genom att slå på följande AppContext-inställning vid programstart:

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

5.0 Stöd för målplattform

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

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-repositoriet: 5.0 Versionsanteckningar.

Viktig information för Microsoft.Data.SqlClient 4.1

Fullständig versionsinformation, inklusive beroenden, är tillgänglig i GitHub-förvaret: 4.1 Versionsinformation.

Nya funktioner i 4.1

Lägg till Attestation Protocol None

Ett nytt attesteringsprotokoll med namnet None tillåts i anslutningssträngen. Med det här protokollet kan användare avstå från enklavattestering för VBS enklaver. När det här protokollet har angetts är egenskapen för enklavattesterings-URL valfri.

Exempel på anslutningssträng:

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

4.1 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 4.0

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-repositoryt: 4.0 Versionsanteckningar.

Ändringar som bryter bakåtkompatibilitet i 4.0

  • Ändrade standardinställningen för Encrypt-anslutningssträngens egenskap till att vara true. #1210Läs mer
  • Drivrutinen genererar nu SqlException, vilket ersätter AggregateException, för Active Directory-autentiseringslägen. #1213
  • Föråldrad Asynchronous Processing anslutningsegenskap från .NET Framework har tagits bort. #1148
  • Borttagen Configurable Retry Logic säkerhetsbrytare. #1254Läs mer
  • Avslutat stöd för .NET Core 2.1 #1272
  • [.NET Framework] Undantag utlöses inte om ett användar-ID anges i anslutningssträngen när du använder Active Directory Integrated autentisering #1359

Nya funktioner i 4.0

Kryptera standardvärdet inställt på true

Standardvärdet för anslutningsinställningen Encrypt har ändrats från false till true. Med den växande användningen av molndatabaser och behovet av att säkerställa att anslutningarna är säkra är det dags för den här bakåtkompatibilitetsbrytande ändringen.

Se till att anslutningar misslyckas när kryptering krävs

I scenarier då klientkrypteringsbibliotek var inaktiverade eller otillgängliga, var det möjligt att göra okrypterade anslutningar när Encrypt var inställt på sant eller när servern krävde kryptering.

Appkontextväxel för användning av standardprotokoll för system

TLS 1.3 stöds inte av drivrutinen. Därför har den tagits bort från listan med protokoll som stöds som standard. Användare kan växla tillbaka till tvingad användning av operativsystemets klientprotokoll genom att aktivera följande appkontextväxel:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Aktivera optimerad parameterbindning

Microsoft.Data.SqlClient introducerar ett nytt SqlCommand API, EnableOptimizedParameterBinding för att förbättra prestanda för frågor med ett stort antal parametrar. Den här egenskapen är inaktiverad som standard. När det är inställt på trueskickas inte parameternamn till SQL Server-instansen när kommandot körs.

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

Ta bort konfigurerbar återförsökslogiksäkerhetsbrytare

Appkontextväxeln "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" krävs inte längre för att använda den konfigurerbara omprövningslogikfunktionen. Funktionen stöds nu i produktion. Standardbeteendet för funktionen fortsätter att vara en icke-återförsöksprincip, som klientprogram måste åsidosätta för att aktivera återförsök.

Stöd för delad SqlLocalDb-instans

Delade SqlLocalDb-instanser stöds nu när hanterade SNI används.

  • Möjliga scenarier:
    • (localdb)\. (ansluter till standardinstansen av SqlLocalDb)
    • (localdb)\<named instance>
    • (localdb)\.\<shared instance name> (*nyligen tillagd support)

GetFieldValueAsync<T> och GetFieldValue<T> stöd för XmlReader, TextReader, Stream typer

XmlReader, TextReader, Stream typer stöds nu när du använder GetFieldValueAsync<T> och GetFieldValue<T>.

Exempel på användning:

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 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 3.0

Fullständiga versionanteckningar, inklusive beroenden, är tillgängliga i GitHub-lagringsplatsen: 3.0 Versionanteckningar.

Icke-bakåtkompatibla ändringar i 3.0

  • Den lägsta .NET Framework-versionen som stöds har ökats till v4.6.1. .NET Framework v4.6.0 stöds inte längre. #899
  • User Id anslutningsegenskapen kräver nu Client Id i stället för Object Id för User-Assigned hanterad identitet#1010Läs mer
  • SqlDataReader returnerar nu ett DBNull-värde i stället för ett tomt byte[]. Äldre beteende kan aktiveras genom att ställa in AppContext brytare Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Läs mer

Nya funktioner i 3.0

Konfigurerbar logik för återförsök

Den här nya funktionen introducerar konfigurerbart stöd för klientprogram för att försöka igen vid "tillfälliga" eller "återförsöksbara" fel. Konfigurationen kan utföras via kod- eller appkonfigurationsfiler och omförsöksåtgärder kan tillämpas på att öppna en anslutning eller köra ett kommando. Den här funktionen är inaktiverad som standard och är för närvarande i förhandsversion. Om du vill aktivera det här stödet måste klientprogram aktivera följande säkerhetsväxel:

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

När .NET AppContext-växeln har aktiverats kan en logikprincip för återförsök definieras för SqlConnection och SqlCommand oberoende av varandra eller tillsammans med hjälp av olika anpassningsalternativ.

Nya offentliga API:er introduceras i SqlConnection och SqlCommand för registrering av en anpassad SqlRetryLogicBaseProvider implementering:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Exempel på API-användning finns här:

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

Nya konfigurationsavsnitt har också introducerats för att göra samma registrering från konfigurationsfiler, utan att behöva ändra befintlig kod:

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

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

Här är ett enkelt exempel på hur du använder de nya konfigurationsavsnitten i konfigurationsfiler:

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

Alternativt kan program implementera sin egen leverantör av basklassen SqlRetryLogicBaseProvider och registrera den med SqlConnection/SqlCommand.

Händelseräknare

Följande räknare är nu tillgängliga för program som riktar sig till .NET Core 3.1+ och .NET Standard 2.1+:

Namn Visningsnamn Beskrivning
aktiva hårdanslutningar Faktiska aktiva anslutningar som för närvarande görs till servrar Antalet anslutningar som för närvarande är öppna för databasservrar.
hårdanslutningar Faktisk anslutningshastighet till servrar Antalet anslutningar per sekund som öppnas för databasservrar.
hårda frånkopplingar Faktisk frånkopplingshastighet från servrar Antalet frånkopplingar per sekund som görs till databasservrar.
aktiv-mjuk-ansluter Aktiva anslutningar som hämtats från anslutningspoolen Antalet redan öppna anslutningar som används från anslutningspoolen.
mjukansluter Frekvens för anslutningar som hämtats från anslutningspoolen Antalet anslutningar per sekund som förbrukas från anslutningspoolen.
mjuk-frånkoppling Frekvens för anslutningar som returneras till anslutningspoolen Antalet anslutningar per sekund som returneras till anslutningspoolen.
antal icke-poolade förbindelser Antal anslutningar som inte använder anslutningspooler Antalet aktiva anslutningar som inte är poolade.
antal poolanslutningar Antal anslutningar som hanteras av anslutningspoolen Antalet aktiva anslutningar som hanterade infrastrukturen för anslutningspooler.
antal-aktiva-anslutningspoolgrupper Antal aktiva unika anslutningssträngar Antalet aktiva, unika anslutningspoolgrupper. Den här räknaren baseras på antalet unika anslutningssträngar som finns i AppDomain.
antal inaktiva anslutningspoolgrupper Antal unika anslutningssträngar som väntar på beskärning Antalet unika anslutningspoolgrupper som har markerats för beskärning. Den här räknaren baseras på antalet unika anslutningssträngar som finns i AppDomain.
antal aktiva anslutningspooler Antal aktiva anslutningspooler Det totala antalet anslutningspooler.
antal inaktiva anslutningspooler Antal inaktiva anslutningspooler Antalet inaktiva anslutningspooler utan någon nylig aktivitet som väntar på att tas bort.
antal aktiva anslutningar Antal aktiva anslutningar Antalet aktiva anslutningar som för närvarande används.
antal kostnadsfria anslutningar Antal färdiga anslutningar i anslutningspoolen Antalet öppna anslutningar som är tillgängliga för användning i anslutningspoolerna.
antal stasisanslutningar Antal anslutningar som väntar på att vara klara Antalet anslutningar som väntar på att slutföra en åtgärd och som inte är tillgängliga för användning av programmet.
antal återvunna anslutningar Antal återställda anslutningar från GC Antalet anslutningar som återvinns via garbage collection utan att applikationen anropade Close eller Dispose. Observera Att inte uttryckligen stänga eller ta bort anslutningar skadar prestandan.

Dessa räknare kan användas med globala CLI-verktyg för .NET Core: dotnet-counters och dotnet-trace i Windows eller Linux och PerfView i Windows, med Microsoft.Data.SqlClient.EventSource som providernamn. Mer information finns i Hämta värden för händelseräknare.

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

En introduktion till Azure Identity-beroenden

Microsoft.Data.SqlClient nu är beroende av Azure.Identity-biblioteket för att hämta token för autentiseringslägena "Active Directory Managed Identity/MSI" och "Active Directory Service Principal". Den här ändringen medför följande ändringar i den offentliga ytan:

  • kritisk ändring
    Anslutningsegenskapen "Användar-ID" kräver nu "Klient-ID" i stället för "Objekt-ID" för "User-Assigned hanterad identitet".
  • API offentligt
    Ny skrivskyddad offentlig egenskap: SqlAuthenticationParameters.ConnectionTimeout
  • Beroende
    Azure.Identity v1.3.0

Förbättringar av händelsespårning i SNI.dll

Microsoft.Data.SqlClient.SNI (.NET Framework-beroende) och Microsoft.Data.SqlClient.SNI.runtime-versioner (.NET Core/Standard-beroende) har uppdaterats till v3.0.0-preview1.21104.2. Händelsespårning i SNI.dll aktiveras inte längre via ett klientprogram. Det räcker att prenumerera en session på Microsoft.Data.SqlClient.EventSource-providern via verktyg som xperf eller perfview. För mer information, se Händelsespårningsstöd i Native SNI.

Aktivera nullbeteende för radversion

SqlDataReader returnerar ett DBNull-värde i stället för ett tomt byte[]. Om du vill aktivera det äldre beteendet måste du aktivera följande AppContext-växel vid programstart: "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"

Standardstöd för Microsoft Entra-autentisering

Not

Även om Microsoft Entra ID är det nya namnet för Azure Active Directory (Azure AD), för att undvika störningar i befintliga miljöer, kvarstår Azure AD fortfarande i vissa hårdkodade element som gränssnittsfält, anslutningsleverantörer, felkoder och cmdletar. I den här artikeln är de två namnen utbytbara.

Den här PR:n introducerar en ny SQL-autentiseringsmetod Active Directory Standardläge. Det här autentiseringsläget ökar möjligheterna för användarautentisering med Microsoft Entra-ID, utökar inloggningslösningar till klientmiljön, Visual Studio Code, Visual Studio, Azure CLI osv.

Med det här autentiseringsläget hämtar drivrutinen en token genom att skicka "DefaultAzureCredential" från Azure Identity-biblioteket för att hämta en åtkomsttoken. Det här läget försöker använda dessa typer av autentiseringsuppgifter för att hämta en åtkomsttoken i följande ordning:

  • EnvironmentCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av klient och hemlighet, användarnamn och lösenord, information som konfigurerats i följande miljövariabler: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Mer information)
  • HanteradIdentitetsautentisering
    • Försöker autentisering med Microsoft Entra-ID med hjälp av en hanterad identitet som har tilldelats distributionsmiljön. "Klient-ID" för en "användartilldelad hanterad identitet" läse från anslutningsegenskapen "Användar-ID".
  • SharedTokenCacheCredential
    • Autentiserar med hjälp av token i den lokala cachen som delas mellan Microsoft-program.
  • VisualStudioCredential
    • Aktiverar autentisering med Microsoft Entra-ID med data från Visual Studio
  • VisualStudioCodeCredential
    • Aktiverar autentisering med Microsoft Entra-ID med hjälp av data från Visual Studio Code.
  • AzureCliCredential
    • Aktiverar autentisering med Microsoft Entra-ID med Hjälp av Azure CLI för att hämta en åtkomsttoken.

InteractiveBrowserCredential är inaktiverat i drivrutinsimplementeringen av "Active Directory Default" och "Active Directory Interactive" är det enda alternativet som är tillgängligt för att hämta en token med hjälp av MFA/interaktiv autentisering.

Ytterligare anpassningsalternativ är inte tillgängliga för tillfället.

Förbättringar av registrering för anpassad huvudnyckellagerleverantör

Microsoft.Data.SqlClient ger nu mer kontroll över var huvudnyckellagringsleverantörer är tillgängliga i ett program för bättre stöd för program med flera klienter och deras användning av kolumnkryptering/dekryptering. Följande API:er introduceras för att tillåta registrering av anpassade huvudnyckellagringsproviders på instanser av SqlConnection och SqlCommand:

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

Det statiska API:et på SqlConnection, SqlConnection.RegisterColumnEncryptionKeyStoreProviders, som används för att registrera anpassade huvudnyckellagringsleverantörer globalt, fortsätter att stödjas. Cacheminnet för kolumnkrypteringsnyckeln som underhålls globalt gäller endast för globalt registrerade leverantörer.

Registreringsprioritet för leverantör av kolumnhuvudnyckellagringstjänster

De inbyggda huvudnyckellagringsprovidrar för kolumner som är tillgängliga för Windows Certificate Store, CNG Store och CSP är förregistrerade. Inga leverantörer ska registreras på anslutnings- eller kommandoinstanser om någon av de inbyggda kolumnhuvudnyckellagringsleverantörerna behövs.

Anpassade huvudnyckellagringsleverantörer kan registreras med drivrutinen i tre olika lager. Den globala nivån är som den är för närvarande. De nya registreringarna per anslutning och per kommandonivå är tomma från början och kan anges mer än en gång.

Prioriteterna för de tre registreringarna är följande:

  • Registreringen per kommando kontrolleras om den inte är tom.
  • Om registreringen per kommando är tom, kontrolleras registreringen per anslutning, om den inte är tom.
  • Om registreringen per anslutning är tom kontrolleras den globala registreringen.

När någon nyckellagerprovider hittas på registreringsnivå drivrutinen INTE återgå till de andra registreringarna för att söka efter en provider. Om leverantörer är registrerade men rätt leverantör inte hittas på en viss nivå genereras ett undantag som endast innehåller de registrerade leverantörerna i den kontrollerade registreringen.

Prioritet för kolumnkrypteringsnyckelcache

Drivrutinen cachelagrar inte kolumnkrypteringsnycklar (CEK:er) för anpassade nyckellagringsproviders som registrerats med hjälp av de nya API:erna på instansnivå. Nyckellagringsleverantörer måste implementera sin egen cache för att förbättra prestandan. Drivrutinen inaktiverar den lokala cachen för kolumnkrypteringsnycklar som implementeras av leverantörer av anpassade nyckellager om nyckellagringsproviderinstansen är registrerad i drivrutinen på global nivå.

Ett nytt API har också introducerats i den SqlColumnEncryptionKeyStoreProvider basklassen för att ange cachetiden till live:

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

IP-adresspreferens

En ny anslutningsegenskap IPAddressPreference introduceras för att specificera inställningen för IP-adressfamiljen till drivrutinen när TCP-anslutningar upprättas. Om Transparent Network IP Resolution (i .NET Framework) eller Multi Subnet Failover är inställt på truehar den här inställningen ingen effekt. Det finns tre godkända värden för den här egenskapen:

  • IPv4First

    • Det här värdet är standardvärdet. Drivrutinen använder lösta IPv4-adresser först. Om ingen av dem kan anslutas till framgångsrikt, försöker den lösa IPv6-adresser.

  • IPv6First

    • Drivrutinen använder lösta IPv6-adresser först. Om ingen av dem kan anslutas framgångsrikt, försöker den använda lösta IPv4-adresser.

  • UsePlatformDefault

    • Drivrutinen försöker IP-adresser i den ordning som tas emot från DNS-upplösningssvaret.

3.0 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 2.1

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängligt i GitHub-förvaret: 2.1 Versionsanteckningar.

Nya funktioner i 2.1

Plattformsoberoende stöd för Always Encrypted

Microsoft.Data.SqlClient v2.1 utökar stödet för Always Encrypted på följande plattformar:

Stöd för Always Encrypted Stöd för "Always Encrypted" med "Secure Enclave" Målramverk Microsoft.Data.SqlClient-version Operativsystem
Ja Ja .NET Framework 4.6+ 1.1.0+ Windows
Ja Ja .NET Core 2.1+ 2.1.0+1 Windows, Linux, macOS
Ja Ingen2 .NET Standard 2.0 2.1.0+ Windows, Linux, macOS
Ja Ja .NET Standard 2.1+ 2.1.0+ Windows, Linux, macOS

Notera

1 Innan Microsoft.Data.SqlClient version v2.1 stöds Always Encrypted endast i Windows.

2 Always Encrypted med säkra enklaver stöds inte på .NET Standard 2.0.

Autentisering med Microsoft Entra Device Code Flow

Microsoft.Data.SqlClient v2.1 har stöd för "Device Code Flow"-autentisering med MSAL.NET. Referensdokumentation: OAuth2.0 Flöde för beviljande av enhetsauktorisering

Exempel på anslutningssträng:

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

Följande API möjliggör anpassning av återanropsmekanismen för enhetskodflöde:

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

Microsoft Entra-hanterad identitetsautentisering

Microsoft.Data.SqlClient v2.1 introducerar stöd för Microsoft Entra-autentisering med hjälp av hanterade identiteter.

Följande nyckelord för autentiseringsläge stöds:

  • Hanterad Active Directory-identitet
  • Active Directory MSI (för kompatibilitet mellan MS SQL-drivrutiner)

Exempel på anslutningssträngar:

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

Förbättringar av interaktiv autentisering i Microsoft Entra

Microsoft.Data.SqlClient v2.1 lägger till följande API:er för att anpassa Microsoft Entra Interactive autentiseringsupplevelse:

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 konfigurationsavsnitt

Microsoft.Data.SqlClient v2.1 introducerar ett nytt konfigurationsavsnitt, SqlClientAuthenticationProviders (en klon av den befintliga SqlAuthenticationProviders). Det befintliga konfigurationsavsnittet, SqlAuthenticationProviders, stöds fortfarande för bakåtkompatibilitet när lämplig typ har definierats.

Det nya avsnittet tillåter att programkonfigurationsfiler innehåller både ett SqlAuthenticationProviders-avsnitt för System.Data.SqlClient och ett SqlClientAuthenticationProviders-avsnitt för Microsoft.Data.SqlClient.

Microsoft Entra-autentisering med ett programklient-ID

Microsoft.Data.SqlClient v2.1 introducerar stöd för att skicka ett användardefinierat programklient-ID till Microsoft Authentication Library. Programklient-ID används när du autentiserar med Microsoft Entra-ID.

Följande nya API:er introduceras:

  1. En ny konstruktor har introducerats i ActiveDirectoryAuthenticationProvider:
    [Gäller för alla .NET-plattformar (.NET Framework, .NET Core och .NET Standard)]

    public ActiveDirectoryAuthenticationProvider(string applicationClientId)

    Användning:

    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. En ny konfigurationsegenskap har introducerats under SqlAuthenticationProviderConfigurationSection och SqlClientAuthenticationProviderConfigurationSection:
    [Gäller för .NET Framework och .NET Core]

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

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

    Användning:

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

Stöd för dataklassificering v2

Microsoft.Data.SqlClient v2.1 introducerar stöd för dataklassificeringens "Känslighetsrankning"-information. Följande nya API:er är nu tillgängliga:

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
}

Serverprocess-ID för en aktiv SqlConnection

Microsoft.Data.SqlClient v2.1 introducerar en ny SqlConnection-egenskap, ServerProcessId, på en aktiv anslutning.

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

Stöd för spårningsloggning i Native SNI

Microsoft.Data.SqlClient v2.1 utökar den befintliga SqlClientEventSource implementeringen för att aktivera händelsespårning i SNI.dll. Händelser måste registreras med hjälp av ett verktyg som Xperf.

Spårning kan aktiveras genom att skicka ett kommando till SqlClientEventSource enligt följande:

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

"Anslutningssträngegenskapen 'Kommandotimeout'"

Microsoft.Data.SqlClient v2.1 introducerar anslutningssträngen "Command Timeout" för att åsidosätta standardvärdet på 30 sekunder. Tidsgränsen för enskilda kommandon kan åsidosättas med egenskapen CommandTimeout på SqlCommand.

Exempel på anslutningssträngar:

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

Borttagning av symboler från inbyggt SNI

Med Microsoft.Data.SqlClient v2.1 har vi tagit bort symbolerna som introducerades i v2.0.0 från Microsoft.Data.SqlClient.SNI.runtime NuGet från och med v2.1.1. De offentliga symbolerna publiceras nu till Microsoft Symbols Server för verktyg som BinSkim som kräver åtkomst till offentliga symboler.

Source-Linking av Microsoft.Data.SqlClient-symboler

Från och med Microsoft.Data.SqlClient v2.1 är Microsoft.Data.SqlClient-symboler källlänkade och publicerade till Microsoft Symbols Server för en förbättrad felsökningsupplevelse utan att behöva ladda ned källkod.

2.1 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 2.0

Fullständiga utgivningsanteckningar, inklusive beroenden, finns på GitHub-lagringsplatsen: 2.0 Utgivningsanteckningar.

Större ändringar i 2.0

  • Åtkomstmodifieraren för enklaverns providergränssnitt SqlColumnEncryptionEnclaveProvider har ändrats från public till internal.
  • Konstanter i klassen SqlClientMetaDataCollectionNames har uppdaterats för att återspegla ändringar i SQL Server.
  • Drivrutinen utför nu verifiering av servercertifikat när SQL Server-målet tillämpar TLS-kryptering, vilket är standardvärdet för Azure-anslutningar.
  • SqlDataReader.GetSchemaTable() returnerar nu en tom DataTable i stället null.
  • Drivrutinen utför nu avrundning till decimaler för att matcha SQL Server-beteendet. För bakåtkompatibilitet kan det tidigare beteendet för trunkering aktiveras med hjälp av en AppContext-inställning.
  • För .NET Framework-program som använder Microsoft.Data.SqlClientnamnges nu de SNI.dll filer som tidigare laddats ned till mapparna bin\x64 och bin\x86Microsoft.Data.SqlClient.SNI.x64.dll och Microsoft.Data.SqlClient.SNI.x86.dll och hämtas till katalogen bin.
  • Nya synonymer för egenskapen anslutningssträng ersätter gamla egenskaper när anslutningssträngen hämtas från SqlConnectionStringBuilder för konsekvens. Läs mer

Nya funktioner i 2.0

Följande nya funktioner har introducerats i Microsoft.Data.SqlClient 2.0.

Motståndskraft mot DNS-fel

Drivrutinen cachelagrar nu IP-adresser från varje lyckad anslutning till en SQL Server-slutpunkt som stöder funktionen. Om ett DNS-matchningsfel inträffar under ett anslutningsförsök försöker drivrutinen upprätta en anslutning med hjälp av en cachelagrad IP-adress för servern, om det finns någon.

EventSource-spårning

Den här versionen introducerar stöd för insamling av händelsespårningsloggar för felsökningsprogram. För att samla in dessa händelser måste klientprogram lyssna efter händelser från SqlClients EventSource-implementering:

Microsoft.Data.SqlClient.EventSource

Mer information finns i Aktivera händelsespårning i SqlClient.

Aktivera hanterat nätverk i Windows

En ny AppContext-växel, "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", möjliggör användning av en hanterad SNI-implementering i Windows för testning och felsökning. Den här växeln växlar drivrutinsbeteendet för att använda ett hanterat SNI i .NET Core 2.1+ och .NET Standard 2.0+-projekt i Windows, vilket eliminerar alla beroenden för interna bibliotek för Microsoft.Data.SqlClient-biblioteket.

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

Se AppContext-växlar i SqlClient för en fullständig lista över tillgängliga växlar i drivrutinen.

Aktivera beteende för decimalt trunkering

Drivrutinen avrundar decimaldataskalan som standardinställning, på samma sätt som SQL Server gör. För bakåtkompatibilitet kan du ställa in AppContext-växeln "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" till sant.

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

Synonymer för ny anslutningssträngsegenskap

Nya synonymer har lagts till för följande befintliga egenskaper för anslutningssträngar för att undvika avståndsförvirring kring egenskaper med mer än ett ord. Gamla egenskapsnamn stöds fortfarande för bakåtkompatibilitet. Men de nya egenskaperna för anslutningssträngen ingår nu när anslutningssträngen hämtas från SqlConnectionStringBuilder.

Befintlig egenskap för anslutningssträng Ny synonym
ApplicationIntent Program avsikt
AnslutÅterförsökAntal Antal återförsök för anslutning
Anslutningsåterförsöksintervall Anslut återförsöksintervall
spärrperiod för pool Poolens blockeringsperiod
MultipleActiveResultSets Flera aktiva resultatuppsättningar
MultiSubnetFailover Felövergång för flera undernät
Transparent nätverks-IP-upplösning Transparent nätverks-IP-upplösning
LitaPåServercertifikat Förtroendeservercertifikat

SqlBulkCopy RowsCopied-egenskap

Egenskapen RowsCopied ger skrivskyddad åtkomst till antalet rader som har bearbetats i den pågående bulk copy-operationen. Det här värdet kanske inte nödvändigtvis är lika med det slutliga antalet rader som läggs till i måltabellen.

Åsidosättningar för öppnande av anslutning

Standardbeteendet för SqlConnection.Open() kan åsidosättas för att inaktivera fördröjningen på tio sekunder och automatiska anslutningsförsök som utlöses av tillfälliga fel.

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

Not

Den här åsidosättningen gäller för SqlConnection.OpenAsync() från och med Microsoft.Data.SqlClient v6.0.0.

Användarnamnsstöd för interaktivt Active Directory-läge

Ett användarnamn kan anges i anslutningssträngen när du använder Interaktiv autentiseringsläge för Microsoft Entra för både .NET Framework och .NET Core

Ange ett användarnamn med hjälp av egenskapen anslutningssträng "Användar-ID " eller "UID ".

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

Ordertips för SqlBulkCopy

Ordertips kan tillhandahållas för att förbättra prestanda för masskopieringsåtgärder i tabeller med klustrade index. Mer information finns i avsnittet masskopieringsåtgärder.

SNI-beroendeändringar

Microsoft.Data.SqlClient (.NET Core och .NET Standard) i Windows är nu beroende av Microsoft.Data.SqlClient.SNI.runtimeoch ersätter det tidigare beroendet av runtime.native.System.Data.SqlClient.SNI. Det nya beroendet lägger till stöd för ARM-plattformen tillsammans med plattformarna Arm64, x64 och x86 som redan stöds i Windows.

2.0 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 1.1.0

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-repositoryt: 1.1 Versionsanteckningar.

Nya funktioner i 1.1

Always Encrypted med säkra enklaver

Always Encrypted är tillgängligt från och med Microsoft SQL Server 2016. Säkra enklaver är tillgängliga från och med Microsoft SQL Server 2019. Om du vill använda enklavens funktion bör anslutningssträngarna innehålla det nödvändiga attesteringsprotokollet och attesterings-URL:en. Till exempel:

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

Mer information finns i:

1.1 Stöd för målplattform

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

Viktig information för Microsoft.Data.SqlClient 1.0

Den första versionen för namnområdet Microsoft.Data.SqlClient erbjuder fler funktioner i det befintliga namnområdet System.Data.SqlClient.

Fullständiga versionsanteckningar, inklusive beroenden, är tillgängliga i GitHub-repositoriet: 1.0 Versionsanteckningar.

Nya funktioner i 1.0

Nya funktioner i .NET Framework 4.7.2 System.Data.SqlClient

  • Data Classification – Tillgänglig i Azure SQL Database och Microsoft SQL Server 2019.

  • UTF-8 stöder – Tillgänglig i Microsoft SQL Server 2019.

Nya funktioner i .NET Core 2.2 System.Data.SqlClient

  • Data Classification – Tillgänglig i Azure SQL Database och Microsoft SQL Server 2019.

  • UTF-8 stöder – Tillgänglig i Microsoft SQL Server 2019.

  • Autentisering – autentiseringsläge för Active Directory-lösenord.

Dataklassificering

Dataklassificering ger en ny uppsättning API:er som exponerar skrivskyddad information om datakänslighet och klassificering om objekt som hämtats via SqlDataReader när den underliggande källan stöder funktionen och innehåller metadata om datakänslighet och klassificering. Se exempelprogrammet på Data Discovery and Classification i 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
    }
}

STÖD FÖR UTF-8

STÖD FÖR UTF-8 kräver inga ändringar i programkoden. Dessa SqlClient-ändringar optimerar kommunikationen mellan klient och server när servern stöder UTF-8 och den underliggande kolumnsorteringen är UTF-8. Se avsnittet UTF-8 under Vad är nytt i SQL Server 2019.

Alltid krypterad med säkra enklaver

I allmänhet bör befintlig dokumentation som använder System.Data.SqlClient på .NET Framework och inbyggda kolumnhuvudnyckellagringsproviders nu också fungera med .NET Core.

Utveckla med Always Encrypted och .NET Framework Data Provider

Always Encrypted: Skydda känsliga data och lagra krypteringsnycklar i Windows-certifikatarkivet

Autentisering

Olika autentiseringslägen kan anges med hjälp av alternativet autentisering anslutningssträng. Mer information finns i dokumentationen för SqlAuthenticationMethod.

Notera

Anpassade nyckellagringsleverantörer, till exempel Azure Key Vault-providern, måste uppdateras för att stödja Microsoft.Data.SqlClient. På samma sätt måste enklavprovidrar också uppdateras för att stödja Microsoft.Data.SqlClient. Always Encrypted stöds endast mot .NET Framework- och .NET Core-mål. Det stöds inte mot .NET Standard eftersom .NET Standard saknar vissa krypteringsberoenden.

1.0 Stöd för målplattform

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