Partilhar via

Introdução ao namespace Microsoft.Data.SqlClient

  • Artigo

Download ADO.NET

O namespace Microsoft.Data.SqlClient é essencialmente uma nova versão do namespace System.Data.SqlClient. Microsoft.Data.SqlClient geralmente mantém a mesma API e retrocompatibilidade com o System.Data.SqlClient. Para migrar de System.Data.SqlClient para Microsoft.Data.SqlClient, para a maioria dos aplicativos, é simples. Adicione uma dependência NuGet em Microsoft.Data.SqlClient e atualize referências e instruções using a Microsoft.Data.SqlClient.

Há algumas diferenças em APIs menos usadas em comparação com System.Data.SqlClient que podem afetar alguns aplicativos. Para essas diferenças, consulte o útil portabilidade cheat sheet.

Referência da API

Os detalhes da API Microsoft.Data.SqlClient podem ser encontrados no .NET API Browser.

Notas de versão do Microsoft.Data.SqlClient 6.0

Mudanças significativas na versão 6.0

  • Caiu o suporte para .NET Standard. #2386
  • Caiu o suporte para .NET 6 #2927
  • Referências a UWP (UAP) removidas. #2483
  • Removido o suporte de depuração do lado do cliente para o SQL 2000 no .NET Framework #2981, #2940

Novos recursos na versão 6.0

  • Adicionado suporte para JSON tipo de dados #2916, #2892, #2891, #2880, #2882, #2829, #2830
  • Adicionado suporte para .NET 9 #2946
  • Adicionado tipo Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic em .NET. #2226
  • Adicionado suporte DateOnly e TimeOnly para DataTable como um parâmetro estruturado. #2258
  • Adicionado suporte para SqlConnectionOverrides no OpenAsync() API #2433
  • Adicionada localização em Checo, Polaco e Turco #2987
  • Objeto TokenCredential adicionado para aproveitar o cache de tokens no ActiveDirectoryAuthenticationProvider. #2380
  • Ficheiro README adicionado ao pacote NuGet #2826
  • Auditoria de pacotes NuGet ativada por meio da fonte de auditoria NuGet.org #3024
  • Foi adicionado o exemplo de código ausente de SqlCommand_BeginExecuteReader #3009
  • Adicionado rastreamento de escopo para GenerateSspiClientContext. #2497#2725

Suporte a tipos de dados JSON

O suporte ao tipo de dados JSON agora está disponível em Microsoft.Data.SqlClient v6.0. Esta versão apresenta o tipo de SqlJson disponível como uma extensão para 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 ; }
    }
}

O tipo de dados JSON suporta operações de leitura, gravação, streaming e cópia em massa.

Apresentando o SqlClientDiagnostics

Novos tipos estão disponíveis no namespace Microsoft.Data.SqlClient.Diagnostics que fornecem uma coleção fortemente tipada de pares chave/valor. Esses tipos podem ser capturados consumindo aplicativos para coletar eventos de diagnóstico emitidos pelo driver. Esta versão apresenta os seguintes tipos:

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

Adicionado suporte para ajustes de conexão na API OpenAsync()

O comportamento padrão do SqlConnection.OpenAsync() pode ser substituído para desativar o atraso de dez segundos e as novas tentativas automáticas de conexão acionadas por erros transitórios.

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

6.0 Suporte à plataforma de destino

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

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 6.0 Release Notes.

Notas de versão do Microsoft.Data.SqlClient 5.2

Novos recursos na versão 5.2

  • Adicionado suporte de SqlDiagnosticListener em .NET Standard. #1931
  • Adicionadas novas propriedades RowsCopied64 a SqlBulkCopy. #2004Leia mais
  • Adicionada uma nova API de AccessTokenCallBack para SqlConnection. #1260Leia mais
  • Adicionado suporte para a opção de registro SuperSocketNetLib para criptografar no .NET no Windows. #2047
  • Adicionado suporte SqlBatch em .NET 6+ #1825, #2223Leia mais
  • Adicionado suporte à autenticação de identidade de carga de trabalho #2159#2264
  • Adicionado suporte de localização no .NET #2210
  • Adicionado suporte para agrupamento georgiano #2194
  • Adicionado suporte para sistemas Big Endian #2170
  • Adicionado suporte do .NET 8 #2230
  • Adicionada versão explícita para as principais dependências da versão .NET em System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 e System.Diagnostics.DiagnosticSource 8.0.0 #2303
  • Adicionada a capacidade de gerar símbolos de depuração num ficheiro de pacote separado #2137

Adicionada nova propriedade RowsCopied64 a SqlBulkCopy

SqlBulkCopy tem uma nova propriedade RowsCopied64 que suporta long tipos de valor.

Observe que o comportamento de SqlBulkCopy.RowsCopied existente permanece inalterado. Quando o valor excede int.MaxValue, RowsCopied pode retornar um número negativo.

Exemplo de uso:

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

Adicionada nova propriedade AccessTokenCallBack a SqlConnection

SqlConnection dá suporte à autenticação TokenCredential introduzindo uma nova propriedade AccessTokenCallBack como um delegado Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>> para retornar um token de acesso de autenticação federada.

Exemplo de uso:

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

Exemplo de uso:

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 Suporte à plataforma de destino

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

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 5.2 Release Notes.

Alterações significativas na versão 5.1

Novos recursos na versão 5.1

  • Adicionado suporte para DateOnly e TimeOnly para SqlParameter valor e GetFieldValue. #1813
  • Adicionado suporte para TLS 1.3 para .NET Core e SNI Native. #1821
  • Foi adicionada a configuração ServerCertificate para Encrypt=Mandatory ou Encrypt=Strict. #1822Leia mais
  • Adicionado suporte ao Windows Arm64 ao direcionar o .NET Framework. #1828

Certificado do servidor

O valor padrão da configuração de conexão ServerCertificate é uma cadeia de caracteres vazia. Quando Encrypt é definido como Mandatory ou Strict, ServerCertificate pode ser usado para especificar um caminho no sistema de arquivos para um arquivo de certificado para corresponder ao certificado TLS/SSL do servidor. O certificado especificado deve coincidir exatamente para ser válido. Os formatos de certificado aceitos são PEM, DERe CER. Aqui está um exemplo de uso:

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

5.1 Suporte à plataforma de destino

  • .NET Framework 4.6.2+ (Windows x86, Windows x64)
  • .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Gerenciador de Recursos do Windows Azure, Linux, macOS)
  • .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 5.1 Release Notes.

Notas de versão do Microsoft.Data.SqlClient 5.0

Quebrando mudanças na versão 5.0

  • Caiu o suporte para o .NET Framework 4.6.1 #1574
  • Foi adicionada uma dependência ao pacote Microsoft.SqlServer.Server. Essa nova dependência pode causar conflitos de namespace se seu aplicativo fizer referência a esse namespace e ainda tiver referências de pacote (diretas ou indiretas) para System.Data.SqlClient do .NET Core.
  • Descartou classes do namespace Microsoft.Data.SqlClient.Server e as substituiu por tipos suportados do pacote Microsoft.SqlServer.Server.#1585. As classes e enums afetados são:
    • Microsoft.Data.SqlClient.Server.IBinarySerialize -> Microsoft.SqlServer.Server.IBinarySerialize
    • Microsoft.Data.SqlClient.Server.InvalidUdtException -> Microsoft.SqlServer.Server.InvalidUdtException
    • Microsoft.Data.SqlClient.Server.SqlFacetAttribute -> Microsoft.SqlServer.Server.SqlFacetAttribute
    • Microsoft.Data.SqlClient.Server.SqlFunctionAttribute -> Microsoft.SqlServer.Server.SqlFunctionAttribute
    • Microsoft.Data.SqlClient.Server.SqlMethodAttribute -> Microsoft.SqlServer.Server.SqlMethodAttribute
    • Microsoft.Data.SqlClient.Server.SqlUserDefinedAggregateAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute
    • Microsoft.Data.SqlClient.Server.SqlUserDefinedTypeAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute
    • (enum) Microsoft.Data.SqlClient.Server.DataAccessKind -> Microsoft.SqlServer.Server.DataAccessKind
    • (enum) Microsoft.Data.SqlClient.Server.Format -> Microsoft.SqlServer.Server.Format
    • (enum) Microsoft.Data.SqlClient.Server.SystemDataAccessKind -> Microsoft.SqlServer.Server.SystemDataAccessKind

Novos recursos na versão 5.0

  • Adicionado suporte para TDS8. Para usar o TDS 8, os usuários devem especificar Encrypt=Strict na cadeia de conexão. #1608Leia mais
  • Adicionado suporte para especificar o SPN do Servidor e o SPN do Servidor de Failover na conexão. #1607Leia mais
  • Adicionado suporte para aliases ao direcionar o .NET Core no Windows. #1588Leia mais
  • Adicionado SqlDataSourceEnumerator. #1430, Leia mais
  • Adicionada uma nova opção AppContext para suprimir avisos TLS inseguros. #1457, Leia mais

TDS 8 segurança reforçada

Para usar o TDS 8, especifique Encrypt=Strict na cadeia de conexão. No modo estrito, TrustServerCertificate é desativado (sempre considerado como falso). HostNameInCertificate foi adicionado para ajudar alguns cenários de modo estrito. O TDS 8 inicia e continua toda a comunicação do servidor dentro de uma conexão TLS segura e criptografada.

Novos valores de criptografia foram adicionados para esclarecer o comportamento de criptografia de conexão. Encrypt=Mandatory é equivalente a Encrypt=True e criptografa conexões durante a negociação de conexão TDS. Encrypt=Optional é equivalente a Encrypt=False e só criptografa a conexão se o servidor informar ao cliente que a criptografia é necessária durante a negociação da conexão TDS.

Para obter mais informações sobre como criptografar conexões com o servidor, consulte Criptografia e validação de certificado.

HostNameInCertificate pode ser especificado na cadeia de conexão ao usar nomes alternativos para se conectar com criptografia a um servidor que tenha um certificado de servidor com um nome diferente ou nome de sujeito alternativo do nome usado pelo cliente para identificar o servidor (nomes alternativos de DNS, por exemplo). Exemplo de uso: HostNameInCertificate=MyDnsAliasName

SPN do servidor

Ao conectar-se num ambiente que tenha uma topografia única de domínio/floresta, poderá ter requisitos específicos para os SPNs do servidor. As configurações de cadeia de conexão ServerSPN/Server SPN e FailoverServerSPN/Failover Server SPN podem ser usadas para substituir os SPNs de servidor gerados automaticamente usados durante a autenticação integrada em um ambiente de domínio

Suporte para aliases SQL

Os usuários podem configurar aliases usando o SQL Server Configuration Manager. Esses aliases são armazenados no registro do Windows e já são suportados quando o alvo é o .NET Framework. Esta versão traz suporte para aliases ao direcionar .NET ou .NET Core para Windows.

Suporte ao Enumerador de Fonte de Dados SQL

Fornece um mecanismo para enumerar todas as instâncias disponíveis do SQL Server na rede local.

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

Suprimir avisos TLS inseguros

Um aviso de segurança será emitido no console se a versão TLS menor que 1.2 for usada para negociar com o servidor. Esse aviso pode ser suprimido na conexão SQL durante o Encrypt = false habilitando a seguinte opção AppContext na inicialização do aplicativo:

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

5.0 Suporte à plataforma de destino

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

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 5.0 Release Notes.

Notas de versão do Microsoft.Data.SqlClient 4.1

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 4.1 Release Notes.

Novos recursos na versão 4.1

Introduzir Protocolo de Atestado Nenhum

Um novo protocolo de atestado chamado None é permitido na cadeia de conexão. Este protocolo permite que os usuários renunciem ao atestado de enclave para enclaves VBS. Quando esse protocolo é definido, a propriedade URL de atestado de enclave é opcional.

Exemplo de cadeia de conexão:

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

4.1 Suporte à plataforma de destino

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

Notas de versão do Microsoft.Data.SqlClient 4.0

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 4.0 Release Notes.

Mudanças significativas na versão 4.0

  • Alterada a propriedade da cadeia de conexão Encrypt para ser true por padrão. #1210Leia mais
  • O driver agora gera SqlException substituindo AggregateException nos modos de autenticação do Active Directory. #1213
  • Foi removida a propriedade de conexão Asynchronous Processing obsoleta do .NET Framework. #1148
  • Interruptor de segurança Configurable Retry Logic removido. #1254Leia mais
  • Caiu o suporte para .NET Core 2.1 #1272
  • [.NET Framework] A exceção não é lançada se um ID de usuário for fornecido na cadeia de conexão ao usar a autenticação Active Directory Integrated#1359

Novos recursos na versão 4.0

Criptografar o valor padrão definido como true

O valor padrão da configuração de conexão Encrypt foi alterado de false para true. Com o uso crescente de bancos de dados em nuvem e a necessidade de garantir que essas conexões sejam seguras, é hora dessa mudança que quebra a compatibilidade com versões anteriores.

Assegurar que as conexões sejam interrompidas quando a criptografia for necessária

Em cenários em que as bibliotecas de criptografia de cliente estavam desabilitadas ou indisponíveis, era possível que conexões não criptografadas fossem feitas quando Encrypt fosse definido como true ou o servidor exigisse criptografia.

Opção de contexto do aplicativo para usar protocolos padrão do sistema

TLS 1.3 não é suportado pelo driver; portanto, ele foi removido da lista de protocolos suportados por padrão. Os usuários podem voltar a forçar o uso dos protocolos de cliente do Sistema Operacional, habilitando a seguinte opção de Contexto do Aplicativo:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Ativar vinculação de parâmetros otimizada

Microsoft.Data.SqlClient introduz uma nova API SqlCommand, EnableOptimizedParameterBinding para melhorar o desempenho de consultas com grande número de parâmetros. Esta propriedade está desativada por padrão. Quando definido como true, os nomes dos parâmetros não são enviados para a instância do SQL Server quando o comando é executado.

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

Remova o interruptor de segurança lógico de repetição configurável

A opção de contexto do aplicativo "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" não é mais necessária para usar o recurso de lógica de repetição configurável. O recurso agora é suportado no ambiente de produção. O comportamento padrão do recurso continua a ser uma política de não repetição que os aplicativos cliente precisam substituir para habilitar tentativas.

Suporte às instâncias partilhadas SqlLocalDb

As instâncias compartilhadas SqlLocalDb agora são suportadas ao usar o SNI gerenciado.

  • Cenários possíveis:
    • (localdb)\. (conecta-se à instância padrão de SqlLocalDb)
    • (localdb)\<named instance>
    • (localdb)\.\<shared instance name> (*suporte recém-adicionado)

Suporte GetFieldValueAsync<T> e GetFieldValue<T> para XmlReader, TextReaderStream tipos

XmlReader, TextReader, Stream tipos agora são suportados ao usar GetFieldValueAsync<T> e GetFieldValue<T>.

Exemplo de uso:

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 Suporte para a plataforma-alvo

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

Notas de versão do Microsoft.Data.SqlClient 3.0

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 3.0 Release Notes.

Quebrando mudanças na versão 3.0

  • A versão mínima suportada do .NET Framework foi aumentada para v4.6.1. O .NET Framework v4.6.0 não é mais suportado. #899
  • User Id propriedade de conexão agora requer Client Id em vez de Object Id para User-Assigned Managed Identity#1010Leia mais
  • SqlDataReader agora retorna um valor DBNull em vez de um byte[]vazio. O comportamento herdado pode ser habilitado definindo AppContext opção Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Leia mais

Novos recursos na versão 3.0

Lógica de repetição configurável

Este novo recurso introduz suporte configurável para aplicativos cliente para repetir erros "transitórios" ou "recuperáveis". A configuração pode ser feita por meio de arquivos de código ou configuração de aplicativo e operações de repetição podem ser aplicadas para abrir uma conexão ou executar um comando. Este recurso está desativado por padrão e está atualmente em pré-visualização. Para habilitar esse suporte, os aplicativos cliente devem ativar a seguinte opção de segurança:

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

Depois que a opção .NET AppContext estiver habilitada, uma política de lógica de repetição poderá ser definida para SqlConnection e SqlCommand de forma independente ou em conjunto usando várias opções de personalização.

Novas APIs públicas são introduzidas no SqlConnection e SqlCommand para registrar uma implementação de SqlRetryLogicBaseProvider personalizada:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Exemplos de uso da API podem ser encontrados aqui:

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

Novas seções de configuração também foram introduzidas para fazer o mesmo registro a partir de arquivos de configuração, sem ter que modificar o código existente:

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

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

Aqui está um exemplo simples de como usar as novas seções de configuração em arquivos de configuração:

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

Como alternativa, os aplicativos podem implementar seu próprio provedor da classe base SqlRetryLogicBaseProvider e registrá-la com SqlConnection/SqlCommand.

Contadores de eventos

Os contadores a seguir agora estão disponíveis para aplicativos destinados ao .NET Core 3.1+ e ao .NET Standard 2.1+:

Nome Nome para exibição Descrição
ligações ativas e rígidas Conexões ativas reais atualmente feitas a servidores O número de conexões atualmente abertas para servidores de banco de dados.
liga diretamente Taxa de conexão real aos servidores O número de conexões por segundo que estão a ser abertas para servidores de base de dados.
desconexões bruscas Taxa de desconexão real dos servidores O número de desconexões por segundo que estão sendo feitas aos servidores de banco de dados.
active-conexões-suaves Conexões ativas recuperadas do pool de conexões O número de conexões já abertas que estão a ser consumidas do pool de conexões.
conecta suavemente Taxa de conexões recuperadas do pool de conexões O número de conexões consumidas por segundo do pool de conexões.
desligamentos suaves Taxa de conexões retornadas ao pool de conexões O número de conexões por segundo a serem devolvidas ao pool de conexões.
número de conexões não agrupadas Número de conexões que não utilizam agrupamento de conexões O número de conexões ativas que não são agrupadas.
número de conexões agrupadas Número de ligações geridas pelo pool de conexões O número de conexões ativas gerenciava a infraestrutura do pool de conexões.
número de grupos de pool de conexões ativas Número de cadeias de conexão únicas ativas O número de grupos de pool de conexões ativos e exclusivos. Esse contador é baseado no número de cadeias de conexão exclusivas encontradas no AppDomain.
número de grupos de conexões inativas Número de cadeias de conexão exclusivas aguardando remoção O número de grupos de pool de conexões exclusivos marcados para poda. Esse contador é baseado no número de cadeias de conexão exclusivas encontradas no AppDomain.
número de pools de conexões activas Número de pools de conexões ativos O número total de pools de conexões.
número de pools de conexões inativas Número de pools de conexões inativas O número de pools de conexões inativas sem atividade recente e à espera de serem eliminados.
número de conexões ativas Número de conexões ativas O número de conexões ativas atualmente em uso.
número de conexões gratuitas Número de conexões prontas no pool de conexões O número de conexões abertas disponíveis para uso nos pools de conexões.
número de conexões de estase Número de conexões atualmente aguardando para serem prontas O número de conexões atualmente aguardando a conclusão de uma ação e que não estão disponíveis para uso pelo aplicativo.
número de conexões recuperadas Número de conexões recuperadas do GC O número de conexões recuperadas por meio da coleta de lixo onde Close ou Dispose não foi chamado pelo aplicativo. Observação Não fechar ou descartar conexões explicitamente prejudica o desempenho.

Esses contadores podem ser usados com as ferramentas globais da CLI do .NET Core: dotnet-counters e dotnet-trace no Windows ou Linux e PerfView no Windows, usando Microsoft.Data.SqlClient.EventSource como o nome do provedor. Para obter mais informações, consulte Recuperar valores de contador de eventos.

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

Introdução à dependência do Azure Identity

Microsoft.Data.SqlClient agora depende da biblioteca Azure.Identity para adquirir tokens para os modos de autenticação "Active Directory Managed Identity/MSI" e "Active Directory Service Principal". Esta alteração introduz as seguintes alterações na superfície pública:

  • Mudança Crítica
    A propriedade de conexão "User ID" agora requer "Client ID" em vez de "Object ID" para "User-Assigned Managed Identity".
  • API pública
    Nova propriedade pública de apenas leitura: SqlAuthenticationParameters.ConnectionTimeout
  • Dependência
    Azure.Identity v1.3.0

Melhorias no rastreamento de eventos no SNI.dll

As versões Microsoft.Data.SqlClient.SNI (dependência do .NET Framework) e Microsoft.Data.SqlClient.SNI.runtime (dependência do .NET Core/Standard) foram atualizadas para v3.0.0-preview1.21104.2. O rastreamento de eventos no SNI.dll não está mais habilitado por meio de um aplicativo cliente. Inscrever uma sessão no fornecedor Microsoft.Data.SqlClient.EventSource através de ferramentas como xperf ou perfview é suficiente. Para obter mais informações, consulte Suporte para rastreamento de eventos no SNI Nativo.

Ativando o comportamento nulo da versão da linha

SqlDataReader retorna um valor DBNull em vez de um byte[]vazio. Para habilitar o comportamento herdado, você deve habilitar a seguinte opção AppContext na inicialização do aplicativo: "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"

Suporte à autenticação padrão do Microsoft Entra

Observação

Embora o Microsoft Entra ID seja o novo nome para o Azure Active Directory (Azure AD), para evitar a interrupção dos ambientes existentes, o Azure AD ainda permanece em alguns elementos codificados, como campos de UI, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Esta PR introduz um novo método de autenticação SQL, Active Directory Default. Este modo de autenticação amplia as possibilidades de autenticação do usuário com o Microsoft Entra ID, estendendo as soluções de login para o ambiente do cliente, Visual Studio Code, Visual Studio, Azure CLI etc.

Com esse modo de autenticação, o driver adquire um token passando "DefaultAzureCredential" da biblioteca de Identidade do Azure para adquirir um token de acesso. Este modo tenta usar esses tipos de credenciais para adquirir um token de acesso na seguinte ordem:

  • EnvironmentCredential
    • Permite a autenticação com o Microsoft Entra ID usando cliente e segredo, ou nome de usuário e senha, detalhes configurados nas seguintes variáveis de ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (Mais detalhes)
  • CredencialDeIdentidadeGerida
    • Tenta autenticação com o Microsoft Entra ID usando uma identidade gerenciada que foi atribuída ao ambiente de implantação. A "ID do cliente" de uma de "identidade gerenciada atribuída pelo usuário" é lida da propriedade de conexão "ID do usuário" .
  • SharedTokenCacheCredential
    • Autentica usando tokens no cache local compartilhado entre aplicativos da Microsoft.
  • VisualStudioCredential
    • Habilita a autenticação com o Microsoft Entra ID usando dados do Visual Studio
  • VisualStudioCodeCredential
    • Habilita a autenticação com o Microsoft Entra ID usando dados do Visual Studio Code.
  • AzureCliCredential
    • Habilita a autenticação com a ID do Microsoft Entra usando a CLI do Azure para obter um token de acesso.

InteractiveBrowserCredential está desabilitado na implementação de driver de "Ative Directory Default" e "Ative Directory Interactive" é a única opção disponível para adquirir um token usando autenticação MFA/Interactive.

Outras opções de personalização não estão disponíveis no momento.

Aprimoramentos no registro do fornecedor de armazenamento de chave principal personalizada

Microsoft.Data.SqlClient agora oferece mais controlo sobre onde os provedores de armazenamento da chave mestra são acessíveis numa aplicação para oferecer melhor suporte para aplicações multicliente e o seu uso de criptografia/descriptografia de coluna. As APIs a seguir são introduzidas para permitir o registro de provedores de armazenamento de chaves mestras personalizadas em instâncias de SqlConnection e SqlCommand:

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

A API estática em SqlConnection, SqlConnection.RegisterColumnEncryptionKeyStoreProviders, usada para registrar provedores de armazenamento de chaves mestras personalizadas globalmente, continua a ser suportada. A cache de chave de encriptação de coluna mantida globalmente só se aplica a fornecedores registados globalmente.

Prioridade de registo do provedor de armazenamento de chaves mestras da coluna

Os provedores de armazenamento de chaves mestras de coluna internos que estão disponíveis para o Windows Certificate Store, CNG Store e CSP são pré-registrados. Nenhum provedor deve ser registado nas instâncias de conexão ou comando se for necessário um dos fornecedores de armazenamento de chaves mestras de coluna integrados.

Os provedores de armazenamento de chaves mestras personalizadas podem ser registrados com o driver em três camadas diferentes. O nível global é o que é atualmente. Os novos registros por conexão e por nível de comando estão vazios inicialmente e podem ser definidos mais de uma vez.

As precedências dos três registos são as seguintes:

  • O registro por comando é verificado se não estiver vazio.
  • Se o registro por comando estiver vazio, o registro por conexão será verificado se não estiver vazio.
  • Se o registro por conexão estiver vazio, o registro global será verificado.

Uma vez que qualquer provedor de armazenamento de chaves é encontrado em um nível de registro, o driver NÃO recorrer aos outros registros para procurar um provedor. Se os provedores estiverem registrados, mas o provedor adequado não for encontrado em um nível, uma exceção será lançada contendo apenas os provedores registrados no registro verificado.

Precedência do cache da chave de criptografia de coluna

O driver não armazena em cache as chaves de criptografia de coluna (CEKs) para provedores de armazenamento de chaves personalizados registrados usando as novas APIs de nível de instância. Os principais provedores de armazenamento precisam implementar seu próprio cache para obter desempenho. O driver desabilita o cache local de chaves de criptografia de coluna implementadas por provedores de armazenamento de chaves personalizados se a instância do provedor de armazenamento de chaves estiver registrada no driver em nível global.

Uma nova API também foi introduzida na classe base SqlColumnEncryptionKeyStoreProvider para definir o tempo de vida do cache:

public abstract class SqlColumnEncryptionKeyStoreProvider
{
    // The default value of Column Encryption Key Cache Time to Live is 0.
    // Provider's local cache is disabled for globally registered providers.
    // Custom key store provider implementation must include column encryption key cache to provide caching support to locally registered providers.
    public virtual TimeSpan? ColumnEncryptionKeyCacheTtl { get; set; } = new TimeSpan(0);
}

Preferência de endereço IP

Uma nova propriedade de conexão IPAddressPreference é introduzida para especificar a preferência da família de endereços IP para o driver ao estabelecer conexões TCP. Se Transparent Network IP Resolution (no .NET Framework) ou Multi Subnet Failover estiver definido como true, essa configuração não terá efeito. Existem os três valores aceites para esta propriedade:

  • IPv4First

    • Esse valor é o padrão. O driver usa endereços IPv4 resolvidos primeiro. Se nenhum deles puder ser conectado com êxito, ele tentará endereços IPv6 resolvidos.

  • IPv6First

    • O driver usa endereços IPv6 resolvidos primeiro. Se nenhum deles puder ser conectado com êxito, ele tentará endereços IPv4 resolvidos.

  • UsarPadrãoDaPlataforma

    • O driver tenta endereços IP na ordem recebida da resposta de resolução DNS.

3.0 Suporte à plataforma de destino

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

Notas de versão do Microsoft.Data.SqlClient 2.1

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 2.1 Release Notes.

Novos recursos na versão 2.1

Suporte multiplataforma para Always Encrypted

Microsoft.Data.SqlClient v2.1 estende o suporte para Always Encrypted nas seguintes plataformas:

Suporte a Always Encrypted Suporte para Always Encrypted com Secure Enclave Plataforma de Destino Versão Microsoft.Data.SqlClient Sistema Operativo
Sim Sim .NET Framework 4.6+ 1.1.0+ Windows
Sim Sim .NET Core 2.1+ 2.1.0+1 Windows, Linux, macOS
Sim Não2 .NET Padrão 2.0 2.1.0+ Windows, Linux, macOS
Sim Sim .NET Standard 2.1+ 2.1.0+ Windows, Linux, macOS

Observação

1 Antes da versão v2.1 do Microsoft.Data.SqlClient, o Always Encrypted só é suportado no Windows.

2 Always Encrypted com enclaves seguros não é suportado no .NET Standard 2.0.

Autenticação do fluxo de código do dispositivo Microsoft Entra

Microsoft.Data.SqlClient v2.1 fornece suporte para autenticação "Device Code Flow" com MSAL.NET. Documentação de referência: fluxo de concessão de autorização de dispositivo OAuth2.0

Exemplo de cadeia de conexão:

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

A API a seguir permite a personalização do mecanismo de retorno de chamada do Device Code Flow:

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

Autenticação de identidade gerida pelo Microsoft Entra

Microsoft.Data.SqlClient v2.1 introduz suporte para autenticação Microsoft Entra usando identidades gerenciadas.

As seguintes palavras-chave do modo de autenticação são suportadas:

  • Identidade gerenciada do Ative Directory
  • MSI do Active Directory (para compatibilidade entre drivers MS SQL)

Exemplos de cadeia de conexão:

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

Aprimoramentos de autenticação do Microsoft Entra Interactive

Microsoft.Data.SqlClient v2.1 adiciona as seguintes APIs para personalizar a experiência de autenticação do Microsoft Entra Interactive:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

SqlClientAuthenticationProviders seção de configuração

Microsoft.Data.SqlClient v2.1 introduz uma nova seção de configuração, SqlClientAuthenticationProviders (um clone do SqlAuthenticationProvidersexistente). A seção de configuração existente, SqlAuthenticationProviders, ainda é suportada para garantir a compatibilidade retroativa quando o tipo apropriado é definido.

A nova seção permite que os arquivos de configuração do aplicativo contenham uma seção SqlAuthenticationProviders para System.Data.SqlClient e uma seção SqlClientAuthenticationProviders para Microsoft.Data.SqlClient.

Autenticação do Microsoft Entra usando uma ID de cliente de aplicativo

Microsoft.Data.SqlClient v2.1 introduz suporte para passar uma ID de cliente de aplicativo definida pelo usuário para a Biblioteca de Autenticação da Microsoft. A ID do cliente da aplicação é usada ao autenticar com o Microsoft Entra ID.

As seguintes novas APIs são introduzidas:

  1. Um novo construtor foi introduzido em ActiveDirectoryAuthenticationProvider:
    [Aplica-se a todas as plataformas .NET (.NET Framework, .NET Core e .NET Standard)]

    public ActiveDirectoryAuthenticationProvider(string applicationClientId)

    Utilização:

    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. Uma nova propriedade de configuração foi introduzida em SqlAuthenticationProviderConfigurationSection e SqlClientAuthenticationProviderConfigurationSection:
    [Aplica-se ao .NET Framework e ao .NET Core]

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

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

    Utilização:

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

Suporte à Classificação de Dados v2

Microsoft.Data.SqlClient v2.1 introduz suporte para informações de "Ranking de Sensibilidade" da Classificação de Dados. As novas APIs a seguir já estão disponíveis:

public class SensitivityClassification
{
    public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
    public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

ID de processo do servidor para um SqlConnection ativo

Microsoft.Data.SqlClient v2.1 introduz uma nova propriedade SqlConnection, ServerProcessId, em uma conexão ativa.

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

Suporte para registo de rastreio no SNI nativo

Microsoft.Data.SqlClient v2.1 estende a implementação de SqlClientEventSource existente para habilitar o rastreamento de eventos em SNI.dll. Os eventos devem ser capturados usando uma ferramenta como o Xperf.

O rastreamento pode ser ativado enviando um comando para SqlClientEventSource conforme ilustrado:

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

Propriedade da cadeia de conexão "Command Timeout"

Microsoft.Data.SqlClient v2.1 introduz a propriedade de cadeia de conexão "Command Timeout" para substituir o padrão de 30 segundos. O tempo limite para comandos individuais pode ser substituído usando a propriedade CommandTimeout no SqlCommand.

Exemplos de cadeia de conexão:

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

Remoção de símbolos do SNI nativo

Com o Microsoft.Data.SqlClient v2.1, removemos os símbolos introduzidos no v2.0.0 do Microsoft.Data.SqlClient.SNI.runtime do NuGet, começando com v2.1.1. Os símbolos públicos agora são publicados no Microsoft Symbols Server para ferramentas como BinSkim que exigem acesso a símbolos públicos.

Símbolos de Source-Linking do Microsoft.Data.SqlClient

A partir de Microsoft.Data.SqlClient v2.1, os símbolos Microsoft.Data.SqlClient são vinculados à fonte e publicados no Microsoft Symbols Server para uma experiência de depuração aprimorada sem a necessidade de baixar o código-fonte.

2.1 Suporte à plataforma de destino

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

Notas de versão do Microsoft.Data.SqlClient 2.0

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 2.0 Release Notes.

Quebrando mudanças na versão 2.0

  • O modificador de acesso para a interface do provedor de enclave SqlColumnEncryptionEnclaveProvider foi alterado de public para internal.
  • As constantes na classe SqlClientMetaDataCollectionNames foram atualizadas para refletir as alterações no SQL Server.
  • O driver agora executa a validação do Certificado de Servidor quando o SQL Server de destino impõe a criptografia TLS, que é o padrão para conexões do Azure.
  • SqlDataReader.GetSchemaTable() agora retorna um DataTable vazio em vez null.
  • O driver agora executa arredondamento de escala decimal para corresponder ao comportamento do SQL Server. Para compatibilidade com versões anteriores, o comportamento anterior de truncamento pode ser habilitado usando uma opção AppContext.
  • Para aplicativos .NET Framework que consomem Microsoft.Data.SqlClient , os arquivos de SNI.dll baixados anteriormente para as pastas bin\x64 e bin\x86 agora são nomeados Microsoft.Data.SqlClient.SNI.x64.dll e Microsoft.Data.SqlClient.SNI.x86.dll e são baixados para o diretório bin.
  • Novos sinônimos de propriedade de cadeia de conexão substituem propriedades antigas ao buscar cadeia de conexão de SqlConnectionStringBuilder para consistência. Leia mais

Novos recursos na versão 2.0

Os novos recursos a seguir foram introduzidos no Microsoft.Data.SqlClient 2.0.

Resiliência a falhas de DNS

O driver agora armazena em cache endereços IP de todas as conexões bem-sucedidas em um ponto de extremidade do SQL Server que oferece suporte ao recurso. Se ocorrer uma falha de resolução DNS durante uma tentativa de conexão, o driver tentará estabelecer uma conexão usando um endereço IP armazenado em cache para esse servidor, se existir.

Rastreamento de "EventSource"

Esta versão introduz suporte para a captura de registos de rastreamento de eventos para depuração de aplicações. Para capturar esses eventos, os aplicativos cliente devem ouvir eventos da implementação EventSource do SqlClient:

Microsoft.Data.SqlClient.EventSource

Para obter mais informações, consulte como Habilitar rastreamento de eventos no SqlClient.

Habilitando a rede gerenciada no Windows

Uma nova opção AppContext, "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", permite o uso de uma implementação SNI gerenciada no Windows para fins de teste e depuração. Essa opção alterna o comportamento do driver para usar um SNI gerenciado em projetos .NET Core 2.1+ e .NET Standard 2.0+ no Windows, eliminando todas as dependências em bibliotecas nativas para a biblioteca Microsoft.Data.SqlClient.

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

Consulte Switches AppContext no SqlClient para obter uma lista completa de switches disponíveis no driver.

Ativando o comportamento de truncamento decimal

O driver arredonda a escala de dados decimal, por padrão, como é feito pelo SQL Server. Para compatibilidade com versões anteriores, você pode definir a opção AppContext "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" como true.

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

Novos sinónimos de propriedades de cadeias de conexão

Novos sinônimos foram adicionados para as seguintes propriedades de cadeia de conexão existentes para evitar confusão de espaçamento em torno de propriedades com mais de uma palavra. Nomes de propriedades antigos continuam a ser suportados para assegurar compatibilidade retroativa. Mas as novas propriedades da cadeia de conexão agora são incluídas quando a cadeia de conexão é obtida do SqlConnectionStringBuilder.

Propriedade de cadeia de conexão existente Novo Sinónimo
Intenção do aplicativo Intenção do aplicativo
ConnectRetryCount Número de Tentativas de Reconexão
ConnectRetryInterval Intervalo de Tentativa de Reconexão
Período de Bloqueio da Piscina Período de bloqueio da piscina
MultipleActiveResultSets Vários conjuntos de resultados ativos
MultiSubnetFailover Failover de várias sub-redes
Resolução de IP de Rede Transparente Resolução IP de rede transparente
TrustServerCertificate Certificado de servidor confiável

Propriedade RowsCopied de SqlBulkCopy

A propriedade RowsCopied fornece acesso somente leitura ao número de linhas que foram processadas na operação de cópia em massa em andamento. Este valor pode não ser necessariamente igual ao número final de linhas adicionadas à tabela de destino.

Substituições abertas de conexão

O comportamento padrão de SqlConnection.Open() pode ser substituído para desabilitar o atraso de dez segundos e as novas tentativas automáticas de conexão desencadeadas por erros transitórios.

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

Observação

Essa substituição pode ser aplicada a SqlConnection.OpenAsync() começando com Microsoft.Data.SqlClient v6.0.0.

Suporte de nome de usuário para o modo interativo do Ative Directory

Um nome de usuário pode ser especificado na cadeia de conexão ao usar o modo de autenticação do Microsoft Entra Interactive para .NET Framework e .NET Core

Defina um nome de utilizador usando a propriedade User ID ou a propriedade UID da cadeia de conexão.

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

Dicas de pedido para SqlBulkCopy

Dicas de ordem podem ser fornecidas para melhorar o desempenho de operações de cópia em massa em tabelas com índices clusterizados. Para obter mais informações, consulte a seção operações de cópia em massa.

Alterações na dependência do SNI

Microsoft.Data.SqlClient (.NET Core e .NET Standard) no Windows agora depende de Microsoft.Data.SqlClient.SNI.runtime , substituindo a dependência anterior em runtime.native.System.Data.SqlClient.SNI. A nova dependência adiciona suporte para a plataforma ARM, juntamente com as plataformas já suportadas Arm64, x64 e x86 no Windows.

2.0 Suporte à plataforma de destino

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

Notas de versão do Microsoft.Data.SqlClient 1.1.0

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 1.1 Release Notes.

Novos recursos na versão 1.1

Sempre criptografado com enclaves seguros

O Always Encrypted está disponível a partir do Microsoft SQL Server 2016. Enclaves seguros estão disponíveis a partir do Microsoft SQL Server 2019. Para usar o recurso de enclave, as cadeias de conexão devem incluir o protocolo de atestado necessário e a URL de atestado. Por exemplo:

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

Para mais informações, consulte:

1.1 Suporte à plataforma de destino

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

Notas de versão do Microsoft.Data.SqlClient 1.0

A versão inicial para o namespace Microsoft.Data.SqlClient oferece mais funcionalidade sobre o namespace System.Data.SqlClient existente.

As notas de versão completas, incluindo dependências, estão disponíveis no repositório GitHub: 1.0 Release Notes.

Novos recursos na versão 1.0

Novos recursos sobre o .NET Framework 4.7.2 System.Data.SqlClient

  • Classificação de Dados - Disponível no Azure SQL Database e no Microsoft SQL Server 2019.

  • Suporte para UTF-8 - Disponível no Microsoft SQL Server 2019.

Novos recursos no .NET Core 2.2 System.Data.SqlClient

  • Classificação de Dados - Disponível na Base de Dados SQL do Azure e no Microsoft SQL Server 2019.

  • Suporte a UTF-8 - Disponível no Microsoft SQL Server 2019.

  • Autenticação - modo de autenticação por palavra-passe do Active Directory.

Classificação de dados

A Classificação de Dados introduz um novo conjunto de APIs que expõe informações somente leitura de sensibilidade e classificação de dados sobre objetos recuperados via SqlDataReader, quando a fonte subjacente oferece suporte ao recurso e contém metadados sobre a sensibilidade de dados e a classificação. Consulte o aplicativo de exemplo em Data Discovery and Classification in 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
    }
}

Suporte UTF-8

O suporte a UTF-8 não requer nenhuma alteração no código do aplicativo. Essas alterações SqlClient otimizam a comunicação cliente-servidor quando o servidor suporta UTF-8 e o agrupamento de colunas subjacente é UTF-8. Consulte a seção UTF-8 em O que há de novo no SQL Server 2019.

Sempre criptografado com enclaves seguros

Em geral, a documentação existente que utiliza o System.Data.SqlClient no .NET Framework , assim como os provedores integrados de armazenamento de chaves mestras de coluna, agora também devem funcionar com o .NET Core.

Desenvolver usando Always Encrypted com o provedor de dados .NET Framework

Always Encrypted: Proteja dados confidenciais e armazene chaves de criptografia no repositório de certificados do Windows

Autenticação

Diferentes modos de autenticação podem ser especificados usando a opção Autenticação cadeia de conexão. Para obter mais informações, consulte a documentação para SqlAuthenticationMethod.

Observação

Os provedores de armazenamento de chaves personalizados, como o provedor do Azure Key Vault, precisarão ser atualizados para oferecer suporte a Microsoft.Data.SqlClient. Da mesma forma, os provedores de enclave também precisarão ser atualizados para oferecer suporte a Microsoft.Data.SqlClient. Always Encrypted só é suportado para destinos .NET Framework e .NET Core. Não é suportado no .NET Standard porque o .NET Standard carece de certas dependências de criptografia.

1.0 Suporte à plataforma de destino

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