Cadeias de conexão para Microsoft.Data.SqlClient

Uma cadeia de conexão Microsoft.Data.SqlClient é uma lista de pares nome-valor keyword=value separados por ponto e vírgula. Passe para SqlConnection ou SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Uma cadeia de conexão responde a quatro perguntas:

1. Qual servidor e banco de dados o aplicativo usa?
2. Usando qual identidade o aplicativo é executado?
3. Como o cliente valida o certificado do servidor?
4. De qual comportamento de conexão a carga de trabalho precisa?

Este artigo aborda essas escolhas e as regras que o driver usa para ler o texto. Para cada palavra-chave, seus sinônimos e seu valor padrão, veja Opções de Conexão. Para criar e alterar cadeias de conexão no código, veja Construtores de cadeias de conexão.

Escolha um padrão de autenticação

Use o padrão que combine com a implantação. Substitua cada marcador de lugar, como <server>, pelo seu valor.

A autenticação integrada do Windows se conecta como a identidade do processo. Para um aplicativo desktop ou de console, geralmente é o usuário logado. Para um aplicativo web ou serviço Windows, é o pool de aplicações ou conta de serviço. A representação pode mudar a identidade. Conceda permissões de login e de banco de dados para a identidade que seu aplicativo realmente utiliza.

Essas três formas de autenticação integrada do Windows são equivalentes:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Se uma string define Integrated Security=true e também define User ID e Password, o driver usa autenticação do Windows e ignora o nome de usuário e a senha.

Microsoft. Data.SqlClient 7.0 e versões posteriores precisam do pacote compatível Microsoft.Data.SqlClient.Extensions.Azure com versão para os métodos de autenticação do Microsoft Entra ID fornecidos pelo driver. Você não precisa desse pacote quando o código da aplicação fornece um token de acesso ou um callback de token de acesso.

Para os valores aceitos Authentication , veja Opções de autenticação. A autenticação também requer usuários do banco de dados, permissões e configuração de identidade no servidor. Para as etapas de configuração, veja autenticação Microsoft Entra ID e autenticação SQL Server.

Especifique o servidor e o banco de dados

Server e Database são os nomes-chave mais legíveis. O construtor os escreve como seus equivalentes canônicos, Data Source e Initial Catalog. Todos os quatro nomes funcionam em uma cadeia de conexão.

Configure Server para uma destas formas:

Use tcp:, um nome de host totalmente qualificado e uma porta explícita em produção. Use um nome DNS que corresponda aos nomes no certificado do servidor, não um endereço IP, porque a validação do certificado compara o nome do servidor na cadeia de conexão com os nomes no certificado.

Quando você se conecta ao Banco de Dados SQL do Azure com autenticação SQL e um nome de usuário na forma user@servername, a parte servername deve corresponder ao servidor em Server.

Para um ouvinte de grupo de disponibilidade ou uma instância de cluster de failover, também revise Multi Subnet Failover em opções de conexão.

Configurar criptografia e validação de certificados

A palavra-chave Encrypt aceita os seguintes valores, independentemente de maiúsculas/minúsculas:

Use Strict quando o servidor oferecer suporte a TDS 8.0 e tiver um certificado que o cliente possa validar. Banco de Dados SQL do Azure e SQL Database no Microsoft Fabric suportam isso. Uma conexão LocalDB não é criptografada, mesmo com Mandatory, e Strict falha.

Os valores Encrypt e Trust Server Certificate se combinam da seguinte forma:

Não configure Trust Server Certificate=true para corrigir um erro de conexão em produção. Ele criptografa o canal, mas não confirma a identidade do servidor. Limite isso a ambientes de desenvolvimento onde um certificado confiável não está disponível.

Quando o nome do servidor em Data Source não corresponder ao certificado, defina Host Name In Certificate como o nome no certificado. O SqlClient verifica isso apenas quando o nome do servidor não bate, e não faz pinning de certificado. Para aceitar apenas um certificado específico, defina Server Certificate para o caminho de um arquivo PEM, DER ou CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Para as regras completas de validação, veja Criptografia e validação de certificados.

Uso de agrupamento de conexões

O pooling está ativado por padrão. Quando você abre um SqlConnection, o driver pega uma conexão física de um pool que corresponde à conexão solicitada. Quando você fecha ou descarta a conexão, a conexão física retorna ao pool em vez de fechar. Uma abertura do pool pula a conexão de rede, o handshake TLS e o login.

Siga estas regras:

• Abra uma conexão pouco antes de precisar dela e descarte-a assim que terminar, com using ou await using. Uma conexão que não é descartada permanece alocada, e o pool pode se esgotar.

• Construa a cadeia de conexão uma vez na inicialização e reutilize-a. A chave do pool inclui o texto exato da cadeia de conexão, então uma ordem diferente de palavras-chave, um sinônimo ou um valor por requisição, como um ID de requisição ou nome de usuário, cria um pool separado. O construtor escreve uma forma canônica. Para mais informações, veja Manter uma cadeia de conexão canônica.

• Espere um pool separado para cada identidade do Windows sob autenticação integrada, cada instância de SqlCredential e cada valor de AccessToken. Utilize um método fornecido Authentication pelo driver ou um reutilizado AccessTokenCallback em vez de configurar AccessToken em cada conexão.

• Procure conexões que não estejam descartadas antes de você aumentar Max Pool Size, que por padrão é 100. Quando toda conexão em um pool está em uso, Open espera até Connect Timeout e então lança InvalidOperationException:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• Planeje a capacidade do servidor para cada pool. Cada processo, ou cada domínio de aplicação no .NET Framework, possui seus próprios pools. As conexões com o servidor podem chegar a Max Pool Size multiplicado pelos pools em cada processo e pelo número de instâncias da aplicação.

• Não defina Pooling=false para contornar um problema de pooling. Cada abertura então realiza um login completo.

Para fechar conexões agrupadas que ficam inativas por muito tempo, veja Limitar o tempo de inatividade da conexão. Para chaves de pool, dimensionamento, limpeza e transações, veja pool de conexões do SQL Server.

Configurações separadas de conexão e comando

Uma cadeia de conexão controla o estabelecimento de conexão e o comportamento da sessão. Um comando controla uma operação SQL.

Um tempo de espera mais longo não é lógica de repetição de tentativas. Um tempo limite limita uma espera. Uma nova tentativa inicia outra tentativa, e ela deve ser limitada e segura para repetir.

Informe a identidade da aplicação

Application Name define o nome que o servidor reporta através de APP_NAME(). Use um nome estável para cada carga de trabalho implantada. Frameworks e ferramentas que abrem conexões para uma aplicação também podem se reportar por meio da RegisteredApplication propriedade, que não possui palavra-chave de cadeia de conexão. Para mais informações, veja Relatar a identidade do aplicativo.

Construa as strings de conexão com segurança

Use SqlConnectionStringBuilder quando o código adiciona ou altera um valor. Não junte texto não confiável a uma cadeia de conexão, porque um ponto e vírgula nesse texto pode adicionar ou substituir uma palavra-chave. O construtor valida valores, mapeia sinônimos para palavras-chave canônicas e coloca cada valor entre aspas para que o valor não possa adicionar palavras-chave. Para exemplos, veja Construtores de strings de conexão.

Armazene informações de conexão fora do código

Carregue as strings de conexão do sistema de configuração da aplicação. Aplicações .NET comumente utilizam variáveis de ambiente, segredos de usuário para desenvolvimento local, Configuração de Aplicativos do Azure e Azure Key Vault.

Siga estas regras:

• Não comprometa senhas, segredos de clientes, tokens de acesso ou strings de conexão de produção.
• Prefira um método de autenticação que não precise de senha na cadeia de conexão.
• Restringa o acesso à fonte de configuração.
• Faça a rotação dos segredos armazenados e reinicie ou atualize aplicações que os armazenem em cache.
• Não grave cadeias de conexão em logs, exceções, rastreamentos ou telemetria.
• Deixe Persist Security Info=false, o valor padrão, para que uma conexão aberta não exponha a senha por meio da propriedade ConnectionString dela.

Para provedores de configuração .NET, veja Configuração em .NET. Para mais opções, veja Proteger informações de conexão.

Regras de análise sintática

O motorista aplica estas regras:

• Palavras-chave não diferenciam maiúsculas de minúsculas. DATABASE, Database, e database são a mesma palavra-chave.
• Muitas palavras-chave têm sinônimos. Server e Data Source definem o mesmo valor. O artigo Opções de Conexão lista os sinônimos para cada palavra-chave.
• Quando uma palavra-chave aparece mais de uma vez, o último valor vence. Sinônimos contam como a mesma palavra-chave.
• O driver ignora os espaços ao redor de palavras-chave e ao redor de valores sem aspas.
• Um ponto e vírgula final é opcional.
• Uma palavra-chave que o driver não reconhece gera ArgumentException junto com a mensagem Keyword not supported.

Os valores podem ser diferenciados em maiúsculas e minúsculas, dependendo da palavra-chave. Uma senha diferencia maiúsculas de minúsculas. Encrypt=STRICT e Encrypt=strict são iguais.

Este programa mostra como o construtor normaliza palavras-chave, resolve uma cópia e cita caracteres especiais. A aba .NET Framework usa C# 7.3. Para criar um projeto que execute as amostras, veja Criar o projeto.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

A saída é:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

A primeira linha mostra cada sinônimo substituído por sua palavra-chave canônica: por , por , por , e timeout por Connect Timeout.User IDuidInitial CatalogDATABASEData Sourceserver

Valores das citações

Inclua um valor entre aspas duplas (") ou aspas simples (') quando contém ponto e vírgula, começa ou termina com um espaço, ou começa ou termina com aspas. Dentro de um valor entre aspas, escreva as aspas delimitadoras duas vezes.

Regras de orçamento são fáceis de errar. Defina os valores através das SqlConnectionStringBuilder propriedades e deixe o construtor fazer orçamentos. Para mais informações, consulte Criação segura de cadeias de conexão.

Especificar valores booleanos

Palavras-chave que assumem valor booleano aceitam true, false, yes, e no, em qualquer caso. Integrated Security também aceita sspi, o que significa true. O construtor escreve True ou False.

Use palavras-chave de outros motoristas

Microsoft. Data.SqlClient não aceita palavras-chave ODBC ou OLE DB como Driver e Provider. Remova essas palavras-chave quando mover uma cadeia de conexão de outro driver. System.Data.SqlClientstrings de conexão funcionam no Microsoft.Data.SqlClient, com estas diferenças:

• Encrypt é definido como Mandatory no Microsoft.Data.SqlClient. Um servidor sem um certificado confiável falha na validação do certificado. Instale um certificado confiável no servidor.
• Em .NET, Network Library, Connection Reset, e Transparent Network IP Resolution não são suportados. Remova-as.
• Não há suporte para Context Connection=true.
• Asynchronous Processing não é uma palavra-chave suportada e lança ArgumentException. Remova-o. Métodos assíncronos funcionam sem isso.
• Não há suporte para Type System Version=SQL Server 2000. Criar a conexão lança ArgumentException. Use Latest, SQL Server 2012, SQL Server 2008, ou SQL Server 2005.

Conteúdo relacionado

• Use a Microsoft. Data.SqlClient em um aplicativo .NET
• Opções de conexão
• Construtores de cadeia de conexão
• Conectar-se a uma fonte de dados
• Pooling de conexões do SQL Server
• Autenticação da ID do Microsoft Entra
• Criptografia e validação de certificado
• Instâncias de usuário do SQL Server Express
• Ciclo de vida de suporte do driver do SqlClient