Microsoft. Data.SqlClient para SQL Server

Baixar ADO.NET

Microsoft.Data.SqlClient é o fornecedor de dados do .NET suportado para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base de dados SQL na Microsoft Fabric e Warehouse na Microsoft Fabric. É distribuído como um pacote NuGet, evolui independentemente do runtime .NET e substitui System.Data.SqlClient para novos desenvolvimentos. Use-o para abrir ligações, executar comandos, processar resultados, gerir transações, carregar dados em massa e usar funcionalidades específicas do SQL Server de aplicações .NET.

Escolhe o teu ponto de partida

Escolha uma base de dados

Crie uma base de dados ou ligue-se a uma base de dados existente numa das seguintes plataformas:

Platform Configuração
Base de Dados SQL do Azure Crie uma base de dados usando o portal Azure.
Banco de dados SQL no Microsoft Fabric Carregue os dados de exemplo do AdventureWorks.
SQL Server Instale o SQL Server ou use uma instância existente disponível através do TCP.
Contentor do SQL Server Crie um contentor com Docker, sqlcmd ou a extensão MSSQL para Visual Studio Code.

Linha de base de produção para o SQL do Azure

Use este excerto como ponto de partida para um caminho de acesso a dados SQL do Azure orientado para produção. Lê os nomes do servidor e da base de dados a partir de IConfiguration, por isso os valores vêm dos fornecedores de configuração que o host liga (appsettings.json, variáveis de ambiente, Azure App Configuration, definições suportadas pelo Key Vault, e assim por diante). A configuração combina Segurança da Camada de Transporte (TLS), identidade gerida, resiliência de ligações ociosas, nova tentativa no estabelecimento inicial da ligação através de lógica de repetição configurável (CRL) com registo estruturado, nova tentativa ao nível do comando para erros transitórios que ocorrem a meio da consulta e recuperação rápida do grupo de failover.

Para maior segurança e para suportar configurações em vários ambientes, mantenha a informação de ligação fora do seu código. Em produção, armazene a informação de ligação no sistema de configuração da sua aplicação e use o Azure Key Vault para valores sensíveis. Para obter mais informações, consulte Proteger informações de conexão.

O excerto de C# neste artigo omite using diretivas e envelopes de classe para maior brevidade.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Este excerto destina-se a qualquer endpoint do SQL Database Engine configurado para utilizar a autenticação do Microsoft Entra: Base de Dados SQL do Azure, Azure SQL Managed Instance, base de dados SQL no Microsoft Fabric e SQL Server 2022 e versões posteriores em Máquinas Virtuais do Azure ou ativado através do Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict seleciona a encriptação TDS 8.0. Requer a Microsoft. Data.SqlClient 5.0 e versões posteriores e um servidor que suporta TDS 8.0 (SQL Server 2022 e versões posteriores, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric). Volta a SqlConnectionEncryptOption.Mandatory quando ligas a servidores mais antigos.

ConnectRetryCount e ConnectRetryInterval aplicam-se durante o estabelecimento inicial da ligação e na recuperação de uma ligação inativa. Quando ConnectRetryCount é maior do que zero, o controlador repete as falhas transitórias elegíveis durante Open(). Depois de Open() ser bem-sucedido, o controlador também utiliza estas definições para restabelecer uma ligação inativa que tenha sido interrompida no comando seguinte. O openRetry provedor atribuído a SqlConnection.RetryLogicProvider adiciona uma política configurável de recuo exponencial a Open(). Tenha em conta ambas as camadas de repetição quando definir o número de tentativas e o tempo limite da ligação.

O evento Retrying em cada provedor é acionado antes de cada nova tentativa e inclui o número de repetições, o atraso antes da tentativa seguinte e as exceções observadas até ao momento. Encaminhe-o para ILogger ou para o seu pipeline de telemetria para manter visível em produção o ciclo de repetição.

Define MultiSubnetFailover = true quando o destino é Base de Dados SQL do Azure, Azure SQL Managed Instance, base de dados SQL no Microsoft Fabric, um ouvinte de grupo de disponibilidade ou uma instância de cluster de failover. Seleciona um caminho de código de ligação paralela que tenta ligações TCP a todos os endereços IP resolvidos em paralelo e usa a primeira ligação que tem sucesso, evitando a caminhada sequencial lenta por IP que, de outra forma, poderia bloquear essas ligações. Em alvos single-IP, a configuração é segura. MultiSubnetFailover não é suportado quando se liga a uma instância nomeada, através de um protocolo diferente do TCP, ou a uma instância configurada com mais de 64 endereços IP. Também não podes usá-lo com espelhamento de base de dados, que está obsoleto em todas as versões suportadas do SQL Server. Em vez disso, use os grupos de disponibilidade Always On. Para mais informações, consulte Alta disponibilidade e recuperação de desastres e Desabilitação da Resolução IP de Rede Transparente.

Se o destino for Base de Dados SQL do Azure serverless com a pausa automática ativada, aumente ConnectTimeout para pelo menos 60 segundos. Uma base de dados em pausa automática é retomada com o primeiro Open(), e esse primeiro Open() pode falhar com o erro 40613 enquanto a base de dados é retomada. O erro 40613 está na lista de erros transitórios incorporada, por isso openRetry tenta novamente. Os timeouts do lado do cliente aparecem como erro -2, que não está nessa lista, por isso openRetry não salvam um Open() que expira a meio do retom. A tentativa de contacto individual deve ser longa o suficiente para cobrir o currículo. Para mais informações, veja Pausa automática e retomada automática.

A nova tentativa ao nível do comando fica à decisão do chamador, para cada comando. Associar commandRetry a SqlCommand.RetryLogicProvider apenas quando for seguro reexecutar o comando: leituras, MERGE protegido por uma chave natural, upserts através de um procedimento armazenado e outras operações idempotentes. O fornecedor de comandos incorporado não efetua novas tentativas quando existe uma transação ativa, pelo que as transações com múltiplas instruções têm de ser novamente tentadas pelo código da aplicação que possa reabrir a transação. A definição TransientErrors substitui a lista de erros incorporada do driver; para estender a linha base incorporada, use SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 e posteriores).

Para mais informações sobre cada parte desta configuração, veja:

Principais características

  • Suporte moderno para .NET: Funciona nas versões atuais de .NET e .NET Framework. Para a divisão por versão, veja Ciclo de vida de Suporte.
  • Cifrado por predefinição: ligações cifradas com TLS e Encrypt=true por predefinição. Defina Encrypt=Strict para a encriptação TDS 8.0 no Microsoft.Data.SqlClient 5.0 e posterior.
  • Autenticação Microsoft Entra ID: Ligações sem palavra-passe com identidade gerida, principal de serviço, fluxos interativos e integrados, cadeia de credenciais predefinida e fluxos de token de acesso.
  • Kerberos e NTLM: autenticação integrada do Windows para o Active Directory no local e cenários legados.
  • Always Encrypted: Encriptação do lado do cliente para colunas sensíveis, com enclaves seguros opcionais para operações no local.
  • Cópia em massa: Inserções de alto débito com SqlBulkCopy.
  • Resiliência da ligação: novas tentativas de ligação integradas (ConnectRetryCount e ConnectRetryInterval), além de lógica de repetição configurável, ativada opcionalmente, para ligações e comandos.
  • Tipos de dados enriquecidos do SQL Server: datetimeoffset, sql_variant, JSON, vetorial, espacial, XML e parâmetros com valores em tabelas.
  • Diagnóstico: rastreio de fontes de eventos, contadores de diagnóstico, estatísticas de fornecedores e um guia dedicado à resolução de problemas.

Introdução

Artigo Description
Comece a usar o driver SqlClient Configura um projeto, cria uma base de dados, liga-te, consulta e adiciona resiliência na ligação.
Arquitetura ADO.NET com Microsoft. Data.SqlClient Saiba como a Microsoft. Data.SqlClient implementa acesso ADO.NET conectado, desconectado e independente do fornecedor.
Instalar, atualizar e implementar a Microsoft. Data.SqlClient Instale pacotes NuGet, escolha uma release, atualize o driver e prepare a saída da implementação.
Ciclo de vida do suporte Consulte as versões dos drivers suportados e as datas de suporte.
Migrar do System.Data.SqlClient para a Microsoft. Data.SqlClient Atualize referências de pacotes, namespaces, configuração e altere o comportamento dos drivers.
Espaço de nomes Microsoft.Data.SqlClient e compatibilidade Compreenda a relação do driver com ADO.NET, System.Data.SqlClient, .NET e SQL Server.
Novidades na Microsoft. Data.SqlClient Encontre lançamentos atuais, grandes alterações de atualização e notas de lançamento a montante.

Configurar e ligar

Artigo Description
Liga-te a uma fonte de dados Abra e gere ligações ao SQL Server e ao SQL do Azure.
Cadeias de ligação Configurar servidor, base de dados, autenticação, encriptação e comportamento de ligação.
Encriptação e validação de certificados Configurar ligações encriptadas e validação de certificados do servidor.
Agrupamento de ligações do SQL Server Reutilize as ligações físicas de forma eficiente.
Eventos de ligação Responda ao estado da ligação e às mensagens informativas.

Autenticar e proteger

Artigo Description
Segurança do SQL Server Revise as orientações de autenticação, autorização e segurança da aplicação.
Autenticação do Microsoft Entra Ligue-se à identidade gerida, principal de serviço, palavra-passe e fluxos interativos.
Proteger a informação da ligação Mantenha credenciais e definições de ligação fora do código da aplicação.
Sempre criptografado Proteger valores sensíveis das colunas do sistema de base de dados.
Sempre criptografado com enclaves seguros Efetue operações avançadas em dados encriptados com um enclave seguro.

Recuperar e atualizar dados

Artigo Description
Comandos e parâmetros Executar instruções SQL parametrizadas e procedimentos armazenados.
Adaptadores de Dados e Leitores de Dados Transmitir conjuntos de resultados em fluxo ou preencher estruturas de dados desconectadas.
Transações e concorrência Use transações locais e distribuídas e controlos de concorrência.
Recuperar informação do esquema da base de dados Descubra coleções e restrições de esquemas.
Operações de cópia em massa Carregar grandes conjuntos de dados eficientemente com SqlBulkCopy.
Parâmetros com valores de tabela Envie várias linhas para uma instrução parametrizada ou procedimento armazenado.
Programação assíncrona Use operações de ligação, comandos e dados assíncronas.
Vários conjuntos de resultados ativos (MARS) Intercalar vários lotes numa só ligação.

Tipos de dados

Artigo Description
Mapeamentos de tipos de dados ADO.NET Mapear tipos do Common Language Runtime para tipos do fornecedor e do SQL Server.
Tipos de dados do SQL Server Trabalhe com valores e System.Data.SqlTypes tipos específicos do SQL Server.
Dados JSON Enviar e recuperar o tipo de dados do SQL Server json.
Dados vetoriais Enviar e recuperar valores de vetores.
Dados XML Lê, escreve e parametriza valores XML.
Dados binários e de grande valor Transmitir e atualizar dados binários, FILESTREAM e dados de grande valor.

Fiabilidade e diagnóstico

Artigo Description
Lógica de repetição de tentativas configurável Repita falhas transitórias de conexão e de comando com políticas limitadas.
Alta disponibilidade e recuperação de desastres Ligue-se a ouvintes de grupos de disponibilidade e parceiros de failover.
Contadores de diagnóstico Monitorizar ligações ativas, ligações em pool e outras métricas de controladores.
Ativar rastreio de fontes de eventos Capturar eventos detalhados do controlador para diagnóstico.
Rastreio de dados Rastrear operações ADO.NET e acesso aos dados.
Guia de resolução de problemas do SqlClient Diagnosticar problemas comuns de conetividade e de controladores.
Notificações de consulta Receba notificações quando os resultados da consulta mudam.

Funcionalidades do SQL Server

Artigo Description
Funcionalidades e ADO.NET do SQL Server Explore funcionalidades específicas do SQL Server disponíveis através do SqlClient.
LocalDB Ligue-se às instâncias do SQL Server Express LocalDB.
Deteção e classificação de dados Leia metadados de classificação de sensibilidade a partir de conjuntos de resultados.

Referência e recursos

Artigo Description
Referência da API de Microsoft.Data.SqlClient Consulte a referência da API .NET para o driver.
Interruptores do AppContext Configure o comportamento de compatibilidade e segurança.
Encontre informações adicionais sobre SqlClient Encontre código-fonte, suporte e recursos comunitários.

Conteúdo relacionado

  • Last updated on