Freigeben über

Einführung in den Namespace „Microsoft.Data.SqlClient“

  • Artikel

Herunterladen von ADO.NET

Der Microsoft.Data.SqlClient-Namespace ist im Wesentlichen eine neue Version des System.Data.SqlClient-Namespace. Microsoft.Data.SqlClient behält in der Regel die API- und Abwärtskompatibilität von System.Data.SqlClient bei. Die Migration von System.Data.SqlClient zu Microsoft.Data.SqlClient ist für die meisten Anwendungen einfach. Fügen Sie Microsoft.Data.SqlClient eine NuGet-Abhängigkeit hinzu, und aktualisieren Sie Verweise und using-Anweisungen auf Microsoft.Data.SqlClient.

Im Vergleich zu System.Data.SqlClient gibt es einige Unterschiede bei weniger verwendeten APIs, die sich auf einige Anwendungen auswirken können. Informationen zu diesen Unterschieden finden Sie im Spickzettel zur Portierung.

API-Verweis

Die Details der Microsoft.Data.SqlClient-API finden Sie im .NET-API-Browser.

Versionshinweise für Microsoft.Data.SqlClient 5.2

Neue Features in Version 5.2

  • Unterstützung für SqlDiagnosticListener auf .NET Standard hinzugefügt. #1931
  • Neue RowsCopied64-Eigenschaft zu SqlBulkCopy hinzugefügt. #2004 Weitere Informationen
  • Eine neue AccessTokenCallBack-API wurde zu SqlConnection hinzugefügt. #1260 Weitere Informationen
  • Unterstützung für die SuperSocketNetLib-Registrierungsoption "Verschlüsseln" unter .NET unter Windows wurde hinzugefügt. #2047
  • SqlBatch-Unterstützung für .NET 6+ #1825, #2223 hinzugefügt. Weitere Informationen
  • Unterstützung der Workload-Identitätsauthentifizierung hinzugefügt #2159, #2264
  • Lokalisierungs-Unterstützung auf .NET hinzugefügt #2210
  • Unterstützung für Georgische Sortierung hinzugefügt #2194
  • Unterstützung für Big Endian-Systeme hinzugefügt #2170
  • .NET 8-Unterstützung hinzugefügt #2230
  • Explizite Version für Haupt-.NET-Versionsabhängigkeiten zu System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 und System.Diagnostics.DiagnosticSource 8.0.0 hinzugefügt #2303
  • Die Möglichkeit zum Generieren von Debugsymbolen in einer separaten Paketdatei hinzugefügt #2137

Neue Eigenschaft RowsCopied64 zu SqlBulkCopy hinzugefügt

SqlBulkCopy verfügt über eine neue Eigenschaft RowsCopied64, die long-Werttypen unterstützt.

Beachten Sie, dass das vorhandene SqlBulkCopy.RowsCopied-Verhalten unverändert bleibt. Wenn der Wert int.MaxValue überschreitet, kann RowsCopied eine negative Zahl zurückgeben.

Beispielverwendung:

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

Neue Eigenschaft AccessTokenCallBack zu SqlConnection hinzugefügt

SqlConnection unterstützt TokenCredential-Authentifizierung, indem eine neue AccessTokenCallBack-Eigenschaft als Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>>-Stellvertretung eingeführt wird, um ein Verbundauthentifizierungs-Zugriffstoken zurückzugeben.

Beispielverwendung:

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

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

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

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

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

SqlBatch-API

Beispielverwendung:

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

Unterstützung der Zielplattform 5.2

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

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository in den Anmerkungen zu Version 5.2 zur Verfügung.

Breaking Changes in Version 5.1

  • Unterstützung für .NET Core 3.1 wurde eingestellt. #1704 #1823

Neue Features in Version 5.1

  • Unterstützung für DateOnly und TimeOnly wurde für den Wert SqlParameter sowie GetFieldValue hinzugefügt. 1813
  • Unterstützung für TLS 1.3 wurde für .NET Core und SNI Native hinzugefügt. 1821
  • Die ServerCertificateEinstellung wurde für Encrypt=Mandatory oder Encrypt=Strict hinzugefügt. #1822 Weitere Informationen
  • Unterstützung von Windows ARM64-Bereitstellungen für das .NET Framework wurde hinzugefügt. 1828

Serverzertifikat

Der Standardwert der ServerCertificate-Verbindungseinstellung ist eine leere Zeichenfolge. Wenn Encrypt auf Mandatory oder Strict festgelegt ist, kann ServerCertificate verwendet werden, um einen Pfad im Dateisystem zu einer Zertifikatdatei anzugeben, die mit dem TLS-/SSL-Zertifikat des Servers abgeglichen werden soll. Das angegebene Zertifikat muss exakt übereinstimmen, um gültig zu sein. Die akzeptierten Zertifikatformate sind PEM, DER und CER. Im Folgenden finden Sie ein Beispiel zur Verwendung:

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

Unterstützung der Zielplattform 5.1

  • .NET Framework 4.6.2+ (Windows x86, Windows x64)
  • .NET 6.0 und höher (Windows x86, Windows x64, Windows ARM64, Microsoft Azure Resource Manager, Linux, macOS)
  • .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)

Die vollständigen Versionshinweise, einschließlich der Abhängigkeiten, stehen im GitHub-Repository Hinweise zu Version 5.1 zur Verfügung.

Versionshinweise für Microsoft.Data.SqlClient 5.0

Breaking Changes in Version 5.0

  • Unterstützung für .NET Framework 4.6.1 wurde entfernt. #1574
  • Es wurde eine Abhängigkeit vom Paket Microsoft.SqlServer.Server hinzugefügt. Diese neue Abhängigkeit kann zu Namespacekonflikten führen, wenn Ihre Anwendung auf diesen Namespace verweist und weiterhin Paketverweise (direkt oder indirekt) auf System.Data.SqlClient von .NET Core enthält.
  • Klassen aus dem Namespace Microsoft.Data.SqlClient.Server wurden verworfen und durch unterstützte Typen aus dem Paket Microsoft.SqlServer.Server-Paket ersetzt. #1585. Die betroffenen Klassen und Enumerationen sind:
    • 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
    • (Enumeration:) Microsoft.Data.SqlClient.Server.DataAccessKind -> Microsoft.SqlServer.Server.DataAccessKind
    • (Enumeration:) Microsoft.Data.SqlClient.Server.Format -> Microsoft.SqlServer.Server.Format
    • (Enumeration:) Microsoft.Data.SqlClient.Server.SystemDataAccessKind -> Microsoft.SqlServer.Server.SystemDataAccessKind

Neue Features in Version 5.0

Erweiterte Sicherheit in TDS 8

Um TDS 8 zu verwenden, geben Sie in der Verbindungszeichenfolge „Encrypt=Strict“ an. Im Strict-Modus ist TrustServerCertificate deaktiviert (im Strict-Modus immer als FALSE behandelt). HostNameInCertificate wurde zur Unterstützung bei einigen Szenarien im Strict-Modus hinzugefügt. TDS 8 beginnt die gesamte Serverkommunikation in einer sicheren, verschlüsselten TLS-Verbindung und setzt sie dort auch fort.

Neue Werte für „Encrypt“ wurden hinzugefügt, um das Verbindungsverschlüsselungsverhalten klarzustellen. Encrypt=Mandatory entspricht Encrypt=True und verschlüsselt Verbindungen während der TDS-Verbindungsverhandlung. Encrypt=Optional entspricht Encrypt=False und verschlüsselt die Verbindung nur, wenn der Server gegenüber dem Client angibt, dass während der TDS-Verbindungsverhandlung Verschlüsselung erforderlich ist.

Weitere Informationen zum Verschlüsseln von Verbindungen mit dem Server finden Sie unter Verschlüsselung und Zertifikatüberprüfung.

Wenn eine verschlüsselte Verbindung mit einem Server, dessen Serverzertifikat einen anderen Namen oder einen alternativen Antragstellernamen aufweist, als vom Client für die Identifizierung des Servers verwendet wird, mithilfe von Aliasen erfolgt (z. B. DNS-Aliase), kann in der Verbindungszeichenfolge HostNameInCertificate angegeben werden. Beispielverwendung: HostNameInCertificate=MyDnsAliasName

Server-SPN

Wenn Sie eine Verbindung in einer Umgebung herstellen, die eine eindeutige Domänen-/Gesamtstrukturtopografie aufweist, liegen möglicherweise bestimmte Anforderungen für Server-SPNs vor. Mit den Einstellungen für ServerSPN/Server-SPN und FailoverServerSPN/Failoverserver-SPN der Verbindungszeichenfolge können die automatisch generierten Server-SPNs außer Kraft gesetzt werden, die bei der integrierten Authentifizierung in einer Domänenumgebung verwendet werden.

Unterstützung für SQL-Aliase

Benutzer*innen können Aliase mithilfe von SQL Server-Konfigurations-Manager konfigurieren. Diese Aliase werden in der Windows-Registrierung gespeichert und werden bereits für .NET Framework als Ziel unterstützt. Dieses Release bietet Unterstützung für Aliase bei .NET oder .NET Core unter Windows als Ziel.

SQL-Datenquellen-Enumeratorunterstützung

Stellt einen Mechanismus für das Auflisten aller verfügbaren Instanzen von SQL Server im lokalen Netzwerk bereit.

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

Unterdrücken von Warnungen zu unsicherem TLS

Eine Sicherheitswarnung wird auf der Konsole ausgegeben, wenn für die Verhandlung mit dem Server eine TLS-Version unter 1.2 verwendet wird. Diese Warnung kann bei der SQL-Verbindung mit Encrypt = false unterdrückt werden, indem der folgenden AppContext-Schalter beim Start der Anwendung aktiviert wird:

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Unterstützung der Zielplattform 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)

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository in den Anmerkungen zu Version 5.0 zur Verfügung.

Versionshinweise für Microsoft.Data.SqlClient 4.1

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 4.1 zur Verfügung.

Neue Features in Version 4.1

Einführung von Nachweisprotokoll „None“

In der Verbindungszeichenfolge kann ein neues Nachweisprotokoll namens None verwendet werden. Dieses Protokoll ermöglicht es den Benutzer*innen, für VBS-Enclaves auf einen Enclavenachweis zu verzichten. Wenn dieses Protokoll festgelegt ist, ist die URL-Eigenschaft für den Enclavenachweis optional.

Beispiel für Verbindungszeichenfolge:

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

Unterstützung der Zielplattform 4.1

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

Versionshinweise für Microsoft.Data.SqlClient 4.0

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 4.0 zur Verfügung.

Breaking Changes in Version 4.0

  • Der Standardwert für die Encrypt-Verbindungszeichenfolgeneigenschaft wurde auf true festgelegt. #1210 Weitere Informationen
  • Der Treiber löst jetzt SqlException anstelle von AggregateException für Active Directory-Authentifizierungsmodi aus. #1213
  • Die veraltete Verbindungseigenschaft Asynchronous Processing wurde aus dem .NET Framework entfernt. #1148
  • Die Sicherheitsoption Configurable Retry Logic wurde entfernt. #1254 Weitere Informationen
  • Die Unterstützung für .NET Core 2.1 wurde entfernt. #1272
  • [.NET Framework] Es wird keine Ausnahme ausgelöst, wenn bei Verwendung der Active Directory Integrated-Authentifizierung eine Benutzer-ID in der Verbindungszeichenfolge angegeben wird. #1359

Neue Features in Version 4.0

Standardwert für Verschlüsselung auf TRUE festgelegt

Der Standardwert der Encrypt-Verbindungseinstellung wurde von false in true geändert. Da Clouddatenbanken zunehmend verwendet werden und die Sicherheit dieser Verbindungen gewährleistet werden muss, ist es an der Zeit, diesen Breaking Change für die Abwärtskompatibilität durchzuführen.

Sicherstellen eines Verbindungsfehlers bei erforderlicher Verschlüsselung

In Szenarien, in denen Clientverschlüsselungsbibliotheken deaktiviert oder nicht verfügbar waren, konnten unverschlüsselte Verbindungen hergestellt werden, obwohl „Encrypt“ auf TRUE festgelegt war oder der Server eine Verschlüsselung verlangte.

App-Kontextwechsel für die Verwendung von Standardprotokollen des Systems

TLS 1.3 wird vom Treiber nicht unterstützt. Daher wurde es standardmäßig aus der Liste der unterstützten Protokolle entfernt. Benutzer*innen können die Verwendung der Clientprotokolle des Betriebssystems wieder erzwingen, indem sie die folgende App-Kontextoption aktivieren:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Aktivieren der optimierten Parameterbindung

Microsoft.Data.SqlClient führt eine neue SqlCommand-API namens EnableOptimizedParameterBinding ein, um die Leistung von Abfragen mit einer großen Anzahl von Parametern zu verbessern. Diese Eigenschaft ist standardmäßig deaktiviert. Wenn dieser Wert auf true festgelegt ist, werden beim Ausführen des Befehls keine Parameternamen an die SQL-Server-Instance gesendet.

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

Entfernen der Sicherheitsoption für konfigurierbare Wiederholungslogik

Die App-Kontextoption „Switch.Microsoft.Data.SqlClient.EnableRetryLogic“ ist nicht mehr erforderlich, um das Feature der konfigurierbaren Wiederholungslogik zu verwenden. Das Feature wird jetzt in der Produktion unterstützt. Das Standardverhalten des Features ist weiterhin eine Nicht-Wiederholungsrichtlinie, die von Clientanwendungen überschrieben werden muss, um Wiederholungen zu ermöglichen.

Unterstützung freigegebener SqlLocalDb-Instanzen

Freigegebene SqlLocalDb-Instanzen werden jetzt bei Verwendung der verwalteten SNI unterstützt.

  • Mögliche Szenarien:
    • (localdb)\. (stellt eine Verbindung mit der Standardinstanz von SqlLocalDb her.)
    • (localdb)\<named instance>
    • (localdb)\.\<shared instance name> (*neu hinzugefügte Unterstützung)

GetFieldValueAsync<T>- und GetFieldValue<T>-Unterstützung für die Typen XmlReader, TextReader und Stream

Die Typen XmlReader, TextReader und Stream werden bei Verwendung von GetFieldValueAsync<T> und GetFieldValue<T> jetzt unterstützt.

Beispielverwendung:

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

Unterstützung der Zielplattform 4.0

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

Versionshinweise für Microsoft.Data.SqlClient 3.0

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 3.0 zur Verfügung.

Breaking Changes in Version 3.0

  • Die niedrigste unterstützte Version von .NET Framework ist nun Version 4.6.1. Version 4.6.0 von .NET Framework wird nicht mehr unterstützt. #899
  • Für die Verbindungseigenschaft User Id muss jetzt bei Benutzerseitig zugewiesene verwaltete Identität anstelle der Object Id die Client Id angegeben werden. #1010 Weitere Informationen
  • SqlDataReader gibt jetzt anstelle eines leeren byte[] einen DBNull-Wert zurück. Das Legacyverhalten kann durch Festlegen der Option AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior aktiviert werden. #998 Weitere Informationen

Neue Features in Version 3.0

Konfigurierbare Wiederholungslogik

Mit diesem neuen Feature wird die konfigurierbare Unterstützung für Clientanwendungen eingeführt, um vorübergehend auftretende oder wiederholbare Fehler zu wiederholen. Die Konfiguration kann über Code oder Anwendungskonfigurationsdateien erfolgen, und Wiederholungsvorgänge können angewendet werden, um eine Verbindung zu öffnen oder einen Befehl auszuführen. Dieses Feature ist standardmäßig deaktiviert und befindet sich derzeit in der Vorschauversion. Zum Aktivieren dieser Unterstützung muss für Clientanwendungen die folgende Sicherheitsoption aktiviert werden:

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

Nachdem die .NET AppContext-Option aktiviert wurde, kann mit verschiedenen Anpassungsoptionen für SqlConnection und SqlCommand einzeln oder zusammen eine Richtlinie für die Wiederholungslogik definiert werden.

In SqlConnection und SqlCommand wurden neue öffentliche APIs zum Registrieren einer benutzerdefinierten SqlRetryLogicBaseProvider-Implementierung eingeführt:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Im Folgenden sind Beispiele für die Verwendung der APIs aufgeführt:

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

Zudem wurden neue Konfigurationsabschnitte eingeführt, die dieselbe Registrierung über Konfigurationsdateien ermöglichen, ohne vorhandenen Code ändern zu müssen:

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

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

Im Folgenden finden Sie ein einfaches Beispiel für die Verwendung der neuen Konfigurationsabschnitte in Konfigurationsdateien:

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

Alternativ können Anwendungen einen eigenen Anbieter der Basisklasse SqlRetryLogicBaseProvider implementieren und bei SqlConnection/SqlCommand registrieren.

Ereigniszähler

Für Anwendungen für NET Core ab Version 3.1 und .NET Standard ab Version 2.1 sind nun die folgenden Zähler verfügbar:

name `Display name` BESCHREIBUNG
active-hard-connections Tatsächliche aktive Verbindungen, die derzeit mit Servern bestehen Anzahl der Verbindungen, die derzeit für Datenbankserver geöffnet sind.
hard-connects Tatsächliche Rate der Verbindungen mit Servern Anzahl der geöffneten Verbindungen mit Datenbankservern pro Sekunde.
hard-disconnects Tatsächliche Rate der Trennungen von Servern Anzahl der getrennten Verbindungen mit Datenbankservern pro Sekunde.
active-soft-connects Aus dem Verbindungspool abgerufene aktive Verbindungen Anzahl der bereits geöffneten Verbindungen, die über den Verbindungspool genutzt werden.
soft-connects Rate der aus dem Verbindungspool abgerufenen Verbindungen Anzahl der über den Verbindungspool genutzten Verbindungen pro Sekunde.
soft-disconnects Anzahl der Verbindungen, die an den Verbindungspool zurückgegeben werden Anzahl der an den Verbindungspool zurückgegebenen Verbindungen pro Sekunde.
number-of-non-pooled-connections Anzahl der Verbindungen, für die kein Verbindungspool genutzt wird Anzahl der aktiven Verbindungen, für die kein Verbindungspool genutzt wird.
number-of-pooled-connections Anzahl der vom Verbindungspool verwalteten Verbindungen Anzahl der aktiven Verbindungen, die von der Verbindungspoolinfrastruktur verwaltet werden.
number-of-active-connection-pool-groups Anzahl der aktiven eindeutigen Verbindungszeichenfolgen Anzahl der aktiven eindeutigen Verbindungspoolgruppen. Dieser Indikator beruht auf der Anzahl eindeutiger Verbindungszeichenfolgen in der Anwendungsdomäne (AppDomain).
number-of-inactive-connection-pool-groups Anzahl der eindeutigen Verbindungszeichenfolgen, die darauf warten, gelöscht zu werden Anzahl der eindeutigen Verbindungspoolgruppen, die zum Löschen gekennzeichnet sind. Dieser Indikator beruht auf der Anzahl eindeutiger Verbindungszeichenfolgen in der Anwendungsdomäne (AppDomain).
number-of-active-connection-pools Anzahl der aktiven Verbindungspools Gesamtzahl der Verbindungspools
number-of-inactive-connection-pools Anzahl der inaktiven Verbindungspools Anzahl inaktiver Verbindungspools, die in letzter Zeit keine Aktivitäten zu verzeichnen hatten und auf den Löschvorgang warten.
number-of-active-connections Anzahl der aktiven Verbindungen Anzahl zurzeit verwendeter aktiver Verbindungen.
number-of-free-connections Anzahl der bereiten Verbindungen im Verbindungspool Anzahl der offenen Verbindungen, die für die Verwendung in den Verbindungspools verfügbar sind.
number-of-stasis-connections Anzahl der Verbindungen, die derzeit auf den Bereitstatus warten Anzahl der Verbindungen, die derzeit auf den Abschluss einer Aktion warten und für die Verwendung durch die Anwendung nicht verfügbar sind.
number-of-reclaimed-connections Anzahl der von der GC freigegebenen Verbindungen Anzahl der Verbindungen, die durch die Garbage Collection freigegeben wurden, wobei Close oder Dispose nicht von der Anwendung aufgerufen wurde. Hinweis: Das nicht explizite Schließen oder Freigeben von Verbindungen beeinträchtigt die Leistung.

Diese Zähler können mit den globalen CLI-Tools von .NET Core verwendet werden: dotnet-counters und dotnet-trace in Windows oder Linux und PerfView in Windows, wobei Microsoft.Data.SqlClient.EventSource als Anbietername verwendet wird. Weitere Informationen finden Sie unter Abrufen von Ereigniszählerwerten.

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

Einführung in die Azure.Identity-Abhängigkeit

Microsoft.Data.SqlClient hängt nun in Bezug auf das Abrufen von Tokens für die Authentifizierungsmodi „Active Directory mit verwalteter Identität/MSI“ und „Active Directory-Dienstprinzipal“ von der Azure.Identity-Bibliothek ab. Diese Änderung bringt die folgenden Änderungen bei der öffentlichen Oberfläche mit sich:

  • Breaking Change
    Für die Benutzer-ID muss jetzt bei „Benutzerseitig zugewiesene verwaltete Identität“ anstelle der Objekt-ID die Client-ID angegeben werden.
  • Öffentliche API
    Neue schreibgeschützte öffentliche Eigenschaft: SqlAuthenticationParameters.ConnectionTimeout
  • Abhängigkeit
    Azure.Identity v1.3.0

Verbesserungen bei der Ereignisablaufverfolgung in SNI.dll

Die Versionen Microsoft.Data.SqlClient.SNI (Abhängigkeit von .NET Framework) und Microsoft.Data.SqlClient.SNI.runtime (Abhängigkeit von .NET Core/Standard) wurden auf v3.0.0-preview1.21104.2 aktualisiert. Die Ereignisablaufverfolgung in „SNI.dll“ wird nicht mehr über eine Clientanwendung aktiviert. Es reicht aus, eine Sitzung beim Anbieter Microsoft.Data.SqlClient.EventSource über Tools wie xperf oder perfview zu abonnieren. Weitere Informationen finden Sie unter Unterstützung der Ereignisablaufverfolgung in nativer SNI-Datei.

Aktivieren des Nullverhaltens der Zeilenversion

SqlDataReader gibt anstelle eines leeren byte[] einen DBNull-Wert zurück. Wenn Sie das Legacyverhalten aktivieren möchten, aktivieren Sie beim Starten der Anwendung die folgende AppContext-Option: „Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior“

Unterstützung der Microsoft Entra-Standardauthentifizierung

Hinweis

Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.

Mit diesem PR wird die neue SQL-Authentifizierungsmethode Active Directory Default eingeführt. Mit diesem Authentifizierungsmodus gibt es mehr Möglichkeiten bei der Benutzerauthentifizierung mit Microsoft Entra ID, sodass Anmeldungen nun auch über die Clientumgebung, Visual Studio Code, Visual Studio, die Azure CLI usw. möglich sind.

Bei diesem Authentifizierungsmodus erhält der Treiber ein Token, indem er DefaultAzureCredential aus der Azure Identity-Bibliothek übergibt, um ein Zugriffstoken zu erhalten. In diesem Modus wird mit diesen Anmeldeinformationstypen ein Zugriffstoken wie folgt abgerufen:

  • EnvironmentCredential
    • Ermöglicht die Authentifizierung bei Microsoft Entra ID mit Client und Geheimnis oder mit Benutzername und Kennwort. Dabei müssen folgende Umgebungsvariablen konfiguriert werden: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Weitere Informationen)
  • ManagedIdentityCredential
    • Authentifizierung bei Microsoft Entra ID mit einer verwalteten Identität, die der Bereitstellungsumgebung zugewiesen wurde. Die „Client-ID“ einer „benutzerseitig zugewiesenen verwalteten Identität“ wird aus der Verbindungseigenschaft „Benutzer-ID“ ausgelesen.
  • SharedTokenCacheCredential
    • Authentifizierung mit Token in dem von Microsoft-Anwendungen gemeinsam genutzten lokalen Cache.
  • VisualStudioCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID anhand von Daten aus Visual Studio
  • VisualStudioCodeCredential
    • Ermöglicht die Authentifizierung mit Microsoft Entra ID anhand von Daten aus Visual Studio Code.
  • AzureCliCredential
    • Aktiviert die Authentifizierung mit Microsoft Entra ID mithilfe der Azure CLI, um ein Zugriffstoken abzurufen.

„InteractiveBrowserCredential“ ist in der Treiberimplementierung von „Active Directory Default“ deaktiviert. „Active Directory Interactive“ ist die einzige verfügbare Option zum Abrufen eines Tokens mithilfe der MFA/interaktiven Authentifizierung.*

Weitere Anpassungsoptionen sind derzeit nicht verfügbar.

Verbesserungen bei der Registrierung des benutzerdefinierten Hauptschlüsselspeicheranbieters

Microsoft.Data.SqlClient bietet jetzt mehr Kontrolle darüber, an welcher Stelle in einer Anwendung auf Hauptschlüsselspeicheranbieter zugegriffen werden kann, sodass mehrinstanzenfähige Anwendungen und deren Einsatz der Spaltenverschlüsselung/-entschlüsselung besser unterstützt werden. Die folgenden APIs wurden eingeführt, um die Registrierung von benutzerdefinierten Hauptschlüsselspeicheranbietern bei Instanzen von SqlConnection und SqlCommand zu ermöglichen:

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

Die statische API für SqlConnection, d. h. SqlConnection.RegisterColumnEncryptionKeyStoreProviders, wird weiterhin zum globalen Registrieren von benutzerdefinierten Hauptschlüsselspeicheranbietern unterstützt. Der global verwaltete Cache für Spaltenverschlüsselungsschlüssel wird nur für global registrierte Anbieter verwendet.

Priorität der Registrierung des Anbieters von Speicher für Spaltenhauptschlüssel

Die integrierten Speicheranbieter für Spaltenhauptschlüssel, die für Windows-Zertifikatspeicher, CNG Store und CSP verfügbar sind, wurden bereits vorab registriert. Wenn einer der integrierten Anbieter von Speicher für Spaltenhauptschlüssel benötigt wird, darf kein Anbieter bei der Verbindungs- oder Befehlsinstanz registriert sein.

Benutzerdefinierte Anbieter von Speicher für Spaltenhauptschlüssel können beim Treiber auf drei verschiedenen Ebenen registriert werden. Die globale Ebene ist so, wie sie derzeit ist. Die neuen Registrierungen auf Verbindungs- und Befehlsebene sind anfänglich leer und können mehrmals festgelegt werden.

Für die drei Registrierungen gilt folgende Priorität:

  • Die Registrierung auf Befehlsebene wird überprüft, falls sie nicht leer ist.
  • Wenn die Registrierung auf Befehlsebene leer ist, wird die Registrierung auf Verbindungsebene überprüft, falls sie nicht leer ist.
  • Wenn die Registrierung pro Verbindung leer ist, wird die globale Registrierung überprüft.

Wenn ein Schlüsselspeicheranbieter auf Registrierungsebene gefunden wurde, greift der Treiber bei der Suche nach einem Anbieter NICHT auf die anderen Registrierungen zurück. Wenn Anbieter registriert sind, der richtige Anbieter jedoch nicht auf einer Ebene gefunden wurde, wird eine Ausnahme ausgelöst, die nur die registrierten Anbieter in der überprüften Registrierung umfasst.

Priorität des Cache für Spaltenverschlüsselungsschlüssel

Die Spaltenverschlüsselungsschlüssel (Column Encryption Keys, CEKs) für benutzerdefinierte Schlüsselspeicheranbieter, die mit den neuen APIs auf Instanzebene registriert wurden, werden vom Treiber nicht zwischengespeichert. Die Schlüsselspeicheranbieter müssen zur Leistungssteigerung einen eigenen Cache implementieren. Der lokale Cache mit Spaltenverschlüsselungsschlüsseln, die von benutzerdefinierten Schlüsselspeicheranbietern implementiert werden, wird vom Treiber deaktiviert, wenn die Schlüsselspeicheranbieterinstanz im Treiber auf globaler Ebene registriert ist.

Darüber hinaus wurde eine neue API für die Basisklasse SqlColumnEncryptionKeyStoreProvider eingeführt, über die die Gültigkeitsdauer für den Cache festgelegt werden kann:

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

Einstellung der IP-Adresse

In der neuen Version gibt es die neue Verbindungseigenschaft IPAddressPreference, über die beim Herstellen von TCP-Verbindungen die Einstellung der IP-Adressfamilie für den Treiber festgelegt werden kann. Wenn Transparent Network IP Resolution (in .NET Framework) oder Multi Subnet Failover auf true festgelegt wird, hat diese Einstellung keine Auswirkungen. Im Folgenden sind die drei zulässigen Werte für diese Eigenschaft aufgeführt:

  • IPv4First

    • Dies ist der Standardwert. Vom Treiber werden zunächst aufgelöste IPv4-Adressen verwendet. Wenn mit keiner dieser Adressen eine Verbindung hergestellt werden kann, werden aufgelöste IPv6-Adressen verwendet.

  • IPv6First

    • Vom Treiber werden zunächst aufgelöste IPv6-Adressen verwendet. Wenn mit keiner dieser Adressen eine Verbindung hergestellt werden kann, werden aufgelöste IPv4-Adressen verwendet.

  • UsePlatformDefault

    • Vom Treiber werden IP-Adressen in der Reihenfolge ausprobiert, in der sie in der Antwort auf die DNS-Auflösung empfangen wurden.

Unterstützung der Zielplattform 3.0

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

Versionshinweise für Microsoft.Data.SqlClient 2.1

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 2.1 zur Verfügung.

Neue Features in 2.1

Plattformübergreifende Unterstützung für Always Encrypted

In Microsoft.Data.SqlClient 2.1 wird die Unterstützung für Always Encrypted auf folgenden Plattformen ausgedehnt:

Unterstützung von Always Encrypted Verwenden von Always Encrypted mit Secure Enclaves Zielframework Microsoft.Data.SqlClient-Version Betriebssystem
Ja Ja .NET Framework 4.6+ Ab 1.1.0 Windows
Ja Ja .NET Core 2.1 oder höher Ab 2.1.01 Windows, Linux, macOS
Ja Nein2 .NET-Standard 2.0 Ab 2.1.0 Windows, Linux, macOS
Ja Ja Ab .NET Standard 2.1 Ab 2.1.0 Windows, Linux, macOS

Hinweis

1 Vor Microsoft.Data.SqlClient-Version 2.1 wird Always Encrypted nur unter Windows unterstützt. 2 Always Encrypted mit Secure Enclaves wird nicht unter .NET Standard 2.0 unterstützt.

Microsoft Entra-Authentifizierung mit Gerätecodeflow

Microsoft.Data.SqlClient 2.1 unterstützt die „Gerätecodeflow“-Authentifizierung mit MSAL.NET. Referenzdokumentation: Flow bei Gewährung der OAuth2.0-Geräteautorisierung

Beispiel für Verbindungszeichenfolge:

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

Die folgende API ermöglicht die Anpassung des Rückrufmechanismus des Gerätecodeflows:

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

Microsoft Entra-Authentifizierung mit verwalteter Identität

Microsoft.Data.SqlClient 2.1 bietet Unterstützung für die Microsoft Entra-Authentifizierung mithilfe verwalteter Identitäten.

Die folgenden Schlüsselwörter für den Authentifizierungsmodus werden unterstützt:

  • Active Directory mit verwalteter Identität
  • Active Directory MSI (für übergreifende Kompatibilität mit Microsoft SQL-Treibern)

Beispiele für Verbindungszeichenfolgen:

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

Erweiterungen der interaktiven Microsoft Entra-Authentifizierung

Microsoft.Data.SqlClient 2.1 fügt die folgenden APIs zum benutzerdefinierten Anpassen der Umgebung zur interaktiven Microsoft Entra-Authentifizierung hinzu:

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

Konfigurationsabschnitt SqlClientAuthenticationProviders

Microsoft.Data.SqlClient 2.1 enthält nun den neuen Konfigurationsabschnitt SqlClientAuthenticationProviders (ein Klon des vorhandenen Abschnitts SqlAuthenticationProviders). Der vorhandene Konfigurationsabschnitt SqlAuthenticationProviders wird weiterhin aus Gründen der Abwärtskompatibilität unterstützt, wenn der entsprechende Typ definiert ist.

Der neue Abschnitt ermöglicht es, dass Anwendungskonfigurationsdateien sowohl den Abschnitt SqlAuthenticationProviders für System.Data.SqlClient als auch den Abschnitt SqlClientAuthenticationProviders für Microsoft.Data.SqlClient enthalten.

Microsoft Entra-Authentifizierung mit einer Anwendungsclient-ID

Microsoft.Data.SqlClient 2.1 bietet Unterstützung für das Übergeben einer benutzerdefinierten Anwendungsclient-ID an die Microsoft-Authentifizierungsbibliothek. Die Anwendungsclient-ID wird beim Authentifizieren mit Microsoft Entra-ID verwendet.

Die folgenden neuen APIs werden eingeführt:

  1. In ActiveDirectoryAuthenticationProvider wurde ein neuer Konstruktor eingeführt:
    [Gilt für alle .NET-Plattformen (.NET Framework, .NET Core und .NET Standard)]

    public ActiveDirectoryAuthenticationProvider(string applicationClientId)

    Syntax:

    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. Eine neue Konfigurationseigenschaft wurde unter SqlAuthenticationProviderConfigurationSection und SqlClientAuthenticationProviderConfigurationSection eingeführt:
    [Gilt für .NET Framework und .NET Core]

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

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

    Syntax:

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

Unterstützung von Datenklassifizierung, Version 2

Microsoft.Data.SqlClient 2.1 bietet jetzt Unterstützung von Informationen zur Vertraulichkeitsbewertung zur Datenklassifizierung. Die folgenden neuen APIs sind nun verfügbar:

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
}

Serverprozess-ID für eine aktive SqlConnection

Microsoft.Data.SqlClient 2.1 bietet für eine aktive Verbindung die neue SqlConnection-Eigenschaft ServerProcessId.

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

Unterstützung der Ablaufverfolgungsprotokollierung in nativer SNI-Datei

Microsoft.Data.SqlClient 2.1 dehnt die vorhandene Implementierung von SqlClientEventSource aus, um die Ereignisablaufverfolgung in „SNI.dll“ zu ermöglichen. Ereignisse müssen mithilfe eines Tools wie Xperf aufgezeichnet werden.

Die Ablaufverfolgung kann aktiviert werden, indem wie gezeigt ein Befehl an SqlClientEventSource gesendet wird:

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

Verbindungszeichenfolgen-Eigenschaft „Befehlstimeout“

Microsoft.Data.SqlClient 2.1 führt die Verbindungszeichenfolgen-Eigenschaft „Befehlstimeout“ ein, um den Standardwert von 30 Sekunden zu überschreiben. Das Zeitlimit für einzelne Befehle kann mit der CommandTimeout-Eigenschaft für SqlCommand überschrieben werden.

Beispiele für Verbindungszeichenfolgen:

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

Entfernung von Symbolen aus nativer SNI-Datei

In Microsoft.Data.SqlClient 2.1 haben wir die in v2.0.0 eingeführten Symbole aus dem NuGet-Paket Microsoft.Data.SqlClient.SNI.runtime beginnend mit v2.1.1 entfernt. Die öffentlichen Symbole werden jetzt für Tools wie BinSkim, die Zugriff auf öffentliche Symbole benötigen, auf dem Microsoft-Symbolserver veröffentlicht.

Quellverknüpfung von Microsoft.Data.SqlClient-Symbolen

Ab Microsoft.Data.SqlClient 2.1 werden Microsoft.Data.SqlClient-Symbole mit Quellcode verknüpft und auf dem Microsoft-Symbolserver veröffentlicht, um das Debuggen zu erleichtern, ohne dass Quellcode heruntergeladen werden muss.

Unterstützung der Zielplattform 2.1

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

Versionshinweise für Microsoft.Data.SqlClient 2.0

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 2.0 zur Verfügung.

Breaking Changes in Version 2.0

  • Die Zugriffsmodifizierer für die Schnittstelle SqlColumnEncryptionEnclaveProvider des Enclave-Anbieters wurde von public in internal geändert.
  • Konstanten in der SqlClientMetaDataCollectionNames-Klasse wurden aktualisiert, um die Änderungen in SQL Server widerzuspiegeln.
  • Der Treiber führt nun eine Überprüfung des Serverzertifikats aus, wenn die SQL Server-Zielinstanz TLS-Verschlüsselung erzwingt. Dies ist die Standardeinstellung für Azure-Verbindungen.
  • SqlDataReader.GetSchemaTable() gibt nun anstelle von null eine leere DataTable-Klasse zurück.
  • Der Treiber führt nun eine Rundung von Dezimalzahlen durch, um dem Verhalten von SQL Server zu entsprechen. Wenn eine Abwärtskompatibilität erforderlich ist, kann das bisherige Verhalten (Kürzen) mithilfe einer AppContext-Option aktiviert werden.
  • Bei .NET Framework-Anwendungen, die Microsoft.Data.SqlClient nutzen, heißen die zuvor in die Ordner bin\x64 und bin\x86 heruntergeladenen SNI.DLL-Dateien nun Microsoft.Data.SqlClient.SNI.x64.dll und Microsoft.Data.SqlClient.SNI.x86.dll. Sie werden in das Verzeichnis bin heruntergeladen.
  • Aus Gründen der Konsistenz werden alte Eigenschaften beim Abrufen von Verbindungszeichenfolgen aus SqlConnectionStringBuilder durch neue Synonyme für Verbindungszeichenfolgeneigenschaften ersetzt. Weitere Informationen

Neue Features in Version 2.0

Die folgenden neuen Features wurden in Microsoft.Data.SqlClient 2.0 eingeführt.

DNS-Fehlerresilienz

Der Treiber speichert IP-Adressen ab sofort für jede erfolgreiche Verbindung mit einem SQL Server-Endpunkt zwischen, der das Feature unterstützt. Wenn während eines Verbindungsversuchs ein Fehler bei der DNS-Auflösung auftritt, versucht der Treiber, mithilfe einer zwischengespeicherten IP-Adresse für den jeweiligen Server (sofern vorhanden) eine Verbindung herzustellen.

EventSource-Nachverfolgung

Ab diesem Release wird das Erfassen von Ereignisablaufprotokollen unterstützt, um Anwendungen zu debuggen. Zur Erfassung dieser Ereignisse müssen Clientanwendungen auf Ereignisse aus der EventSource-Implementierung von SqlClient lauschen:

Microsoft.Data.SqlClient.EventSource

Weitere Informationen finden Sie unter Aktivieren der Ereignisablaufverfolgung in SqlClient.

Aktivieren verwalteter Netzwerke unter Windows

Mithilfe der neuen AppContext-Option Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows kann unter Windows zu Test- und Debuggingzwecken eine verwaltete SNI-Implementierung verwendet werden. Diese Option schaltet das Verhalten des Treibers so um, dass bei Windows-Projekten in .NET Core 2.1 und höher und in .NET Standard 2.0 und höher eine verwaltete SNI verwendet wird. Somit werden alle Abhängigkeiten von nativen Bibliotheken für die Microsoft.Data.SqlClient-Bibliothek beseitigt.

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

Unter AppContext-Optionen in SqlClient finden Sie eine vollständige Liste verfügbarer Optionen für den Treiber.

Aktivieren des Kürzungsverhaltens für Dezimalzahlen

Dezimaldatentypen werden vom Treiber standardmäßig gerundet, wie das auch bei SQL Server der Fall ist. Aus Gründen der Abwärtskompatibilität können Sie die AppContext-Option Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal auf True festlegen.

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

Neue Synonyme für Verbindungszeichenfolgeneigenschaften

Für die folgenden vorhandenen Verbindungszeichenfolgeneigenschaften wurden neue Synonyme hinzugefügt, um Verwirrung bei den Leerzeichen von Eigenschaften zu verhindern, die aus mehr als einem Wort bestehen. Alte Eigenschaftennamen werden aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Aber die neuen Verbindungszeichenfolgeneigenschaften werden jetzt einbezogen, wenn die Verbindungszeichenfolge aus SqlConnectionStringBuilder abgerufen wird.

Vorhandene Verbindungszeichenfolgeneigenschaft Neues Synonym
ApplicationIntent Application Intent
ConnectRetryCount Connect Retry Count (Anzahl der Verbindungsversuche)
ConnectRetryInterval Connect Retry Interval (Verbindungswiederholungsintervall)
PoolBlockingPeriod Pool Blocking Period (Blockierungszeitraum für einen Pool)
MultipleActiveResultSets Multiple Active Result Sets (Mehrere aktive Resultsets)
MultiSubnetFailover Multiple Subnet Failover (Failover für mehrere Subnetze)
TransparentNetworkIPResolution Transparent Network IP Resolution (Transparente Netzwerk-IP-Adressauflösung)
TrustServerCertificate TrustServerCertificate

SqlBulkCopy-Eigenschaft „RowsCopied“

Die RowsCopied-Eigenschaft bietet schreibgeschützten Zugriff auf die Anzahl der Datensätze, die von einem aktiven Massenkopiervorgang bereits verarbeitet wurden. Dieser Wert entspricht nicht unweigerlich der endgültigen Anzahl an Datensätzen, die der Zieltabelle hinzugefügt wurden.

Überschreibungen von SqlConnection.Open

Das Standardverhalten von SqlConnection.Open() kann überschrieben werden, um die Verzögerung von zehn Sekunden und automatische erneute Verbindungsversuche zu deaktivieren, die von vorübergehenden Fehlern ausgelöst werden.

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

Hinweis

Beachten Sie, dass diese Überschreibung nur auf SqlConnection.Open() angewendet werden kann, nicht auf SqlConnection.OpenAsync().

Unterstützung für Benutzernamen bei der interaktiven Active Directory-Authentifizierung

Bei Verwendung der interaktiven Microsoft Entra-Authentifizierung kann sowohl für .NET Framework als auch für .NET Core ein Benutzername in der Verbindungszeichenfolge angegeben werden.

Legen Sie einen Benutzernamen mithilfe der Verbindungszeichenfolgeneigenschaft User ID oder UID fest:

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

Hinweise für die Sortierung für SqlBulkCopy

Hinweise für die Sortierung können bereitgestellt werden, um die Leistung von Massenkopiervorgängen für Tabellen mit gruppierten Indizes zu verbessern. Weitere Informationen finden Sie unter Hinweise für die Sortierung für Massenkopiervorgänge.

SNI-Abhängigkeitsänderungen

Microsoft.Data.SqlClient (.NET Core und .NET Standard) weisen unter Windows nun eine Abhängigkeit von Microsoft.Data.SqlClient.SNI.runtime auf. Dadurch wird die bisherige Abhängigkeit von runtime.native.System.Data.SqlClient.SNI ersetzt. Mit der neuen Abhängigkeit wird die ARM-Plattform zusammen mit den bereits unterstützten Plattformen ARM64, x64 und x86 unter Windows unterstützt.

Unterstützung der Zielplattform 2.0

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

Versionshinweise zu Microsoft.Data.SqlClient 1.1.0

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 1.1 zur Verfügung.

Neue Features in Version 1.1

Always Encrypted mit Secure Enclaves

Always Encrypted ist ab Microsoft SQL Server 2016 verfügbar. Secure Enclaves sind ab Microsoft SQL Server 2019 verfügbar. Die Verbindungszeichenfolgen müssen das erforderliche Nachweisprotokoll und die Nachweis-URL enthalten, um das Enclave-Feature nutzen zu können. Beispiel:

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

Weitere Informationen finden Sie unter

Unterstützung der Zielplattform 1.1

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

Versionshinweise für Microsoft.Data.SqlClient 1.0

Die erste Version des Namespace „Microsoft.Data.SqlClient“ bietet gegenüber dem bestehenden Namespace „System.Data.SqlClient“ zusätzliche Funktionen.

Vollständige Versionshinweise, einschließlich Abhängigkeiten, stehen im GitHub-Repository unter Hinweise zur Version 1.0 zur Verfügung.

Neue Features in Version 1.0

Neue Features im Vergleich zu System.Data.SqlClient in .NET Framework 4.7.2

  • Datenklassifizierung: verfügbar in Azure SQL-Datenbank und Microsoft SQL Server 2019.

  • UTF-8-Unterstützung: verfügbar in Microsoft SQL Server 2019.

Neue Features im Vergleich zu System.Data.SqlClient in .NET Core 2.2

  • Datenklassifizierung: verfügbar in Azure SQL-Datenbank und Microsoft SQL Server 2019.

  • UTF-8-Unterstützung: verfügbar in Microsoft SQL Server 2019.

  • Authentifizierung: Active Directory-Kennwortauthentifizierungsmodus.

Datenklassifizierung

Das Feature „Datenklassifizierung“ bietet eine neue Gruppe von APIs, die schreibgeschützte Informationen zur Datenvertraulichkeit und -klassifizierung von Objekten verfügbar machen. Diese werden über SqlDataReader abgerufen, wenn die zugrunde liegende Quelle das Feature unterstützt und Metadaten zu Datenvertraulichkeit und -klassifizierung enthält. Unter Microsoft.Data.SqlClient 1.1-Releases finden Sie die Beispielanwendung.

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

Unterstützung für UTF-8

Für UTF-8-Unterstützung sind keine Änderungen am Anwendungscode erforderlich. Diese SqlClient-Änderungen optimieren die Kommunikation zwischen Client und Server, wenn der Server UTF-8 unterstützt und die zugrunde liegende Spaltensortierung UTF-8 ist. Weitere Informationen finden Sie im Abschnitt über UTF-8 unter Neues in SQL Server 2019 (15.x).

Always Encrypted mit Secure Enclaves

Im Allgemeinen sollte die vorhandene Dokumentation zu System.Data.SqlClient im .NET Framework und integrierten Anbietern von Speicher für Spaltenhauptschlüssel nun auch für .NET Core gelten.

Entwickeln von Always Encrypted mit .NET Framework-Datenanbieter

Always Encrypted: Schützen vertraulicher Daten und Speichern von Verschlüsselungsschlüsseln im Windows-Zertifikatspeicher

Authentifizierung

Unterschiedliche Authentifizierungsmodi können angegeben werden, indem in der Verbindungszeichenfolge die Option Authentifizierung verwendet wird. Weitere Informationen finden Sie in der Dokumentation zu SqlAuthenticationMethod.

Hinweis

Anbieter benutzerdefinierter Schlüsselspeicher wie der Azure Key Vault-Anbieter müssen aktualisiert werden, damit Microsoft.Data.SqlClient unterstützt wird. Ebenso müssen auch die Enclave-Anbieter aktualisiert werden, um Microsoft.Data.SqlClient zu unterstützen. Always Encrypted wird nur für .NET Framework- und .NET Core-Ziele unterstützt. Das Feature wird nicht für .NET Standard nicht unterstützt, da .NET Standard bestimmte Verschlüsselungsabhängigkeiten fehlen.

Unterstützung der Zielplattform 1.0

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