Opções de conexão para Microsoft. Data.SqlClient

Este artigo lista todas as palavras-chave de cadeia de conexão que a Microsoft. Data.SqlClient aceita. Cada palavra-chave também possui uma propriedade de correspondência SqlConnectionStringBuilder . Para uma introdução, padrões comuns e regras de análise sintática, veja Strings de conexão.

Palavras-chave e apelidos não são sensíveis a maiúsculas e minúsculas. Quando você define um valor através de um imóvel de construtor, o construtor escreve a palavra-chave canônica na coluna Palavra-chave .

Definir opções com SqlConnectionStringBuilder

Comece por uma cadeia de conexão base que armazena as configurações do servidor, banco de dados e autenticação. Depois, defina opções específicas de carga de trabalho através das propriedades do construtor. As abas do .NET Framework usam C# 7.3. Para criar um projeto que execute as amostras, veja Criar o projeto.

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

A saída é:

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

Um novo SqlCommand toma seu tempo padrão a partir da Command Timeout palavra-chave da sua conexão.

Verifique valores padrão

Um novo SqlConnectionStringBuilder reporta o padrão para cada opção. Este programa imprime os padrões que a maioria dos aplicativos revisa:

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

No .NET, a saída é:

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True é a Mandatory opção. No .NET Framework, o nome padrão da aplicação é Framework Microsoft SqlClient Provedor de Dados.

Opções de servidor e banco de dados

Keyword Aliases Propriedade do construtor Padrão Descrição
Data Source Server, Address, Addr, Network Address DataSource Vazio O servidor para se conectar. Aceita um nome de host, host,port, host\instance, (localdb)\instance, e um tcp: prefixo de protocolo ou np: . Para os formulários aceitos, veja Especificar o servidor e o banco de dados.
Initial Catalog Database InitialCatalog Vazio O banco de dados para usar após o login. Quando está vazio, o servidor usa o banco de dados padrão do login.
AttachDbFilename Extended Properties, Initial File Name AttachDBFilename Vazio O caminho completo de um arquivo de banco de dados primário para anexar, para SQL Server Express e LocalDB.
User Instance None UserInstance false Redireciona a conexão para uma instância de usuário do SQL Server Express. Para mais informações, veja SQL Server Express instâncias de usuário.
Failover Partner FailoverPartner FailoverPartner Vazio O parceiro de espelhamento do banco de dados pode tentar quando o servidor principal não estiver disponível. O espelhamento de banco de dados está obsoleto. Use grupos de disponibilidade para novas implantações.
Current Language Language CurrentLanguage Vazio O nome da linguagem SQL Server para a sessão, como us_english. Controla formatos de data e linguagem de mensagens do sistema.

Opções de identidade de aplicação

Keyword Aliases Propriedade do construtor Padrão Descrição
Application Name App ApplicationName Core Microsoft SqlClient Data Provider O nome que o servidor reporta através APP_NAME() e nas visualizações da sessão. Use um nome estável para cada carga de trabalho implantada. Valores distintos criam pools de conexões distintas.
Workstation ID WorkstationID, WSID WorkstationID O nome do computador local O nome do computador cliente que o servidor reporta através HOST_NAME()de .
Application Intent ApplicationIntent ApplicationIntent ReadWrite ReadOnly solicita roteamento de intenção de leitura quando o alvo o suporta. Não torna as declarações somente leitura. Para mais informações, veja Alta disponibilidade e recuperação em caso de desastres.

Para informar qual framework ou ferramenta abriu uma conexão, use a RegisteredApplication propriedade. Não possui palavra-chave de cadeia de conexão. Para mais informações, veja Reportar a identidade da aplicação.

Opções de autenticação

Keyword Aliases Propriedade do construtor Padrão Descrição
Authentication None Authentication Não especificado O método de autenticação. Para valores aceitos, veja a tabela a seguir.
Integrated Security Trusted_Connection IntegratedSecurity false true, yes, ou sspi usa a identidade do processo atual.
User ID UID, User UserID Vazio O nome de login SQL, ou o identificador de usuário ou cliente do Microsoft Entra ID, dependendo de Authentication.
Password PWD Password Vazio A senha ou o segredo do cliente para métodos que aceitam um.
Persist Security Info PersistSecurityInfo PersistSecurityInfo false Quando false, o driver remove a senha após SqlConnection.ConnectionString a abertura da conexão. Deixa pra lá false.
Server SPN ServerSPN ServerSPN Derivado do nome do servidor Substitui o Nome da Entidade de Serviço (SPN) usado para autenticação integrada com o servidor principal.
Failover Partner SPN FailoverPartnerSPN FailoverPartnerSPN Derivado do nome de parceiro Sobrepõe o SPN usado para autenticação integrada ao parceiro de failover.

Authentication aceita esses valores. O construtor as escreve sem espaços, como ActiveDirectoryDefault, e o analisador aceita ambas as formas.

Valor Identity
Sql Password Um login SQL com User ID e Password.
Active Directory Default Uma cadeia de fontes de credenciais, como variáveis de ambiente, identidade gerenciada e login de ferramentas de desenvolvedores.
Active Directory Managed Identity Uma identidade gerenciada. Definido User ID para o ID do cliente de uma identidade atribuída pelo usuário. Active Directory MSI é um alias.
Active Directory Workload Identity Uma identidade de carga de trabalho do Kubernetes.
Active Directory Service Principal Uma aplicação com User ID definido para o ID do cliente e Password definido para o sigilo do cliente.
Active Directory Interactive Um usuário que faz login por meio de um prompt no navegador.
Active Directory Device Code Flow Um usuário que faz login em outro dispositivo com um código.
Active Directory Integrated O usuário do Windows logado, por meio de uma configuração federada ou contínua de login único.
Active Directory Password Um nome de usuário e senha. Esse método é obsoleto. Use outro método.

Os métodos Microsoft Entra ID precisam do Microsoft.Data.SqlClient.Extensions.Azure pacote. Para configuração e exemplos, veja a autenticação Microsoft Entra ID e a autenticação do SQL Server.

Opções de criptografia

Keyword Aliases Propriedade do construtor Padrão Descrição
Encrypt None Encrypt Mandatory Strict usa TDS 8.0 e sempre valida o certificado do servidor. Mandatory, true, ou yes criptografa a conexão. Optional, false, ou no criptografa toda a conexão apenas quando o servidor exige. Quando o servidor suporta criptografia, mas não a exige, apenas o pacote de login é criptografado.
Trust Server Certificate TrustServerCertificate TrustServerCertificate false true ignora a validação do certificado do servidor. Ignorado quando Encrypt=Strict. Não o use em produção.
Host Name In Certificate HostNameInCertificate HostNameInCertificate Vazio Um nome de reserva para validação de certificado. O SqlClient primeiro valida o certificado contra o nome do servidor em Data Source. Ele verifica Host Name In Certificate apenas quando o nome não coincide, então um valor errado não causa falha quando o nome do servidor já coincide. Não é um certificado de fixação. Para exigir um certificado específico, use Server Certificate. Não muda o destino da rede nem contorna a cadeia de confiança e as verificações de expiração. Deixe-o não definido quando o nome do servidor já corresponder ao do certificado.
Server Certificate ServerCertificate ServerCertificate Vazio O caminho de um arquivo PEM, DER ou CER que deve corresponder exatamente ao certificado do servidor. O motorista verifica a correspondência apenas quando valida o certificado, então use-o com Encrypt=Mandatory ou Encrypt=Strict e Trust Server Certificate=false. Um arquivo correspondente substitui a validação de nome de cadeia e de host, então funciona com um certificado autoassinado que o cliente não confia.

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

Opções Always Encrypted

Keyword Aliases Propriedade do construtor Padrão Descrição
Column Encryption Setting ColumnEncryption ColumnEncryptionSetting Disabled Enabled ativa o modo Sempre Criptografado para a conexão.
Attestation Protocol None AttestationProtocol Não especificado O protocolo de atestação do enclave: AAS, HGS, ou None.
Enclave Attestation Url None EnclaveAttestationUrl Vazio O endpoint do serviço de atestação para Always Encrypted com enclaves seguros.

Opções de rede

Keyword Aliases Propriedade do construtor Padrão Descrição
Multi Subnet Failover MultiSubnetFailover MultiSubnetFailover false Tenta todos os endereços IP para os quais o nome do servidor resolve em paralelo. Use-o para ouvintes de grupos de disponibilidade e instâncias de cluster de failover alcançadas via TCP. Não suportado com espelhamento de banco de dados. Instâncias nomeadas dependem da implementação da rede. A implementação gerenciada, que o .NET usa no Linux e macOS e no Windows quando a rede gerenciada está ativada, suporta uma instância nomeada e envia a requisição do SQL Server Browser para todos os endereços resolvidos em paralelo. A implementação nativa no Windows pode rejeitar uma instância nomeada com erro SNI 48.
IP Address Preference IPAddressPreference IPAddressPreference IPv4First A ordem para tentar resolver aborda: IPv4First, IPv6First, ou UsePlatformDefault.
Packet Size PacketSize PacketSize 8000 O tamanho do pacote do Fluxo de Dados Tabulares (TDS) em bytes, de 512 a 32.768.

Um comutador AppContext em todo o processo pode mudar o Multi Subnet Failover padrão para true. Para mais informações, veja as comutações AppContext no SqlClient.

Opções de timeout

Keyword Aliases Propriedade do construtor Padrão Descrição
Connect Timeout Connection Timeout, ConnectTimeout, Timeout ConnectTimeout 15 Segundos para esperar por uma conexão, incluindo a espera por uma conexão em pool quando a piscina está cheia. 0 espera indefinidamente.
Command Timeout None CommandTimeout 30 O padrão CommandTimeout em segundos para comandos criados na conexão. 0 espera indefinidamente.

Connect Timeout Não limita a execução da consulta. Command Timeout Não limita o login nem a espera por uma conexão em pool. Passe a CancellationToken para chamadas assíncronas para que o chamador possa parar de esperar antes que qualquer um dos tempos expire.

Opções de recuperação de conexão

Keyword Aliases Propriedade do construtor Padrão Descrição
Connect Retry Count ConnectRetryCount ConnectRetryCount 1 Tenta novamente após uma falha transitória qualificada durante a primeira abertura e ao restaurar uma conexão ociosa quebrada. 0 Desliga as tentativas novamente. Os valores válidos são de 0 a 255.
Connect Retry Interval ConnectRetryInterval ConnectRetryInterval 10 Segundos entre tentativas de retentativa. Os valores válidos são de 1 a 60.

Quando Connect Retry Count é 1, que é o padrão, o driver usa 2 para endpoints SQL do Azure e 5 para endpoints serverless SQL do Azure Synapse Analytics ao restaurar uma conexão idle quebrada. A primeira abertura usa o valor como definido, então o padrão permite uma tentativa em cada endpoint. O driver usa qualquer outro valor definido em ambos os casos.

Essas palavras-chave não tentam novamente um comando que falha enquanto está rodando. Para pular a retentativa embutida para uma abertura, chame uma Open sobrecarga com OpenWithoutRetry. Para políticas personalizadas, veja Lógica de retentativa configurável. Retente um comando somente quando repeti-lo for seguro.

Opções de agrupamento

Keyword Aliases Propriedade do construtor Padrão Descrição
Pooling None Pooling true Reutiliza conexões físicas para combinar cadeias de conexão.
Min Pool Size None MinPoolSize 0 Conexões físicas que a piscina mantém abertas depois de criada.
Max Pool Size None MaxPoolSize 100 As conexões mais físicas em uma só piscina. Deve ser pelo menos 1.
Connection Idle Timeout None IdleTimeout 300 Segundos em que uma conexão pode ficar ociosa na piscina antes que ela a feche. 0 Desliga a expiração do repouso. Aplicado somente quando a Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior troca do AppContext é false. Por padrão, ele é true.
Load Balance Timeout Connection Lifetime LoadBalanceTimeout 0 A idade máxima em segundos de uma conexão retornava à piscina. Uma conexão antiga está fechada. 0 Desliga o limite.
Pool Blocking Period PoolBlockingPeriod PoolBlockingPeriod Auto Se o pool relança uma falha de login em cache por um curto período: Auto, AlwaysBlock, ou NeverBlock. Autodesativa o bloqueio para endpoints do SQL do Azure.

Cada cadeia de conexão distinta tem seu próprio pool. Para chaves de pool, limpeza e tempo ocioso, veja pool de conexões do SQL Server.

Opções de transação e sessão

Keyword Aliases Propriedade do construtor Padrão Descrição
Enlist None Enlist true Registra a conexão na transação ambiente System.Transactions quando ela abre.
Transaction Binding None TransactionBinding Implicit Unbind Implicit Unbind Desconecta a conexão quando a transação dos praças termina. Explicit Unbind Mantém-no conectado até que a conexão se fecha ou o código o desconecte.
Multiple Active Result Sets MultipleActiveResultSets MultipleActiveResultSets false Permite mais de um lote ativo em uma única conexão.
Type System Version None TypeSystemVersion Latest O tipo de servidor que o driver expõe. Aceita Latest, SQL Server 2012, SQL Server 2008, e SQL Server 2005. Deixe em Latest.
Replication None Replication false Identifica a conexão como uma conexão de replicação.

Opções apenas para o framework .NET

Essas palavras-chave são aceitas apenas no .NET Framework. No .NET, o construtor lança NotSupportedException e SqlConnection lança ArgumentException.

Keyword Aliases Propriedade do construtor Padrão Descrição
Network Library Net, Network NetworkLibrary Vazio A biblioteca da rede. Não combine com o prefixo ou tcp:np: em Data Source, porque a conexão falha. No .NET, prefixe Data Source com tcp: ou np: em vez disso.
Connection Reset None ConnectionReset true Obsolete.
Transparent Network IP Resolution TransparentNetworkIPResolution TransparentNetworkIPResolution true Obsolete.

Palavras-chave não suportadas

Keyword Result
Context Connection Context Connection=true InvalidOperationExceptionlança . Microsoft. Data.SqlClient não suporta conexões contextuais SQL CLR.
Asynchronous Processing Gera ArgumentException: Keyword not supported. Métodos assíncronos funcionam sem ele.
Driver, Provider Gera ArgumentException: Keyword not supported. Essas palavras-chave pertencem ao ODBC e ao OLE DB.

Regras de validação

SqlConnectionStringBuilder rejeita palavras-chave desconhecidas e muitos valores inválidos quando você as configura. SqlConnectionRealiza mais verificações quando você define sua cadeia de conexão, incluindo valores únicos que o construtor aceita e combinações de palavras-chave. Uma string que o construtor aceita ainda pode falhar quando você cria a conexão.

O construtor e a conexão rejeitam esses valores com ArgumentException:

  • Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, ou Min Pool Size menos que 0.
  • Max Pool Size menos de 1.
  • Packet Size fora de 512 a 32.768.
  • Connect Retry Count fora de 0 a 255.
  • Connect Retry Interval fora de 1 a 60.
  • Uma palavra-chave que não está neste artigo.

SqlConnection também rejeita esses valores com ArgumentException, mesmo que o construtor os aceite:

  • Type System VersionExceto , LatestSQL Server 2012, SQL Server 2008, ou SQL Server 2005.
  • Transaction Binding além de Implicit Unbind ou Explicit Unbind.
  • Um valor maior que o limite TDS para , , , , , , , , Workstation ID, , ou AttachDBFilename. PasswordUser IDInitial CatalogFailover PartnerData SourceCurrent LanguageApplication Name

SqlConnection também rejeita essas combinações com ArgumentException:

  • Min Pool Size maior que Max Pool Size.
  • Failover Partner sem Initial Catalog.
  • Failover Partner com Multi Subnet Failover=true, User Instance=true, ou Application Intent=ReadOnly.
  • Authentication com Integrated Security=true.
  • Password com Active Directory Integrated, Active Directory Interactive, Active Directory Managed Identity, Active Directory MSI, Active Directory Default, , ou Active Directory Workload Identity.
  • User ID ou Password com Active Directory Device Code Flow.

Mudanças na opção de revisão

Antes de mudar uma opção em produção:

  1. Registre a cadeia de conexão atual, a versão do driver, o tipo de endpoint e o problema que você está resolvendo.
  2. Mude uma opção de cada vez.
  3. Teste o estabelecimento de conexão, a autenticação, a validação de certificado, o pool de conexões, o failover, o cancelamento e a execução de consultas.
  4. Meça a latência da conexão, as esperas do pool e os números de erro.
  5. Confirme a configuração em cada instância implantada.

Uma cadeia de conexão alterada cria um novo pool. Durante um lançamento em etapas, pools antigos e novos existem ao mesmo tempo, então o número total de conexões físicas ao servidor pode aumentar.

Conteúdo relacionado

  • Última atualização em