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

Este artigo lista todas as palavras-chave de cadeia de ligação que a Microsoft. Data.SqlClient aceita. Cada palavra-chave também tem 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 pseudónimos não são sensíveis a maiúsculas minúsculas. Quando defines um valor através de uma propriedade do construtor, o construtor escreve a palavra-chave canónica na coluna Palavra-chave .

Definir opções com SqlConnectionStringBuilder

Comece a partir de uma cadeia de ligação base que guarda o servidor, a base de dados e as definições de autenticação. Depois define opções específicas de carga de trabalho através das propriedades do construtor. Os separadores do .NET Framework usam C# 7.3. Para criar um projeto que execute as amostras, veja Criar o projeto.

.NET
Framework .NET

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

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        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,
        };

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

            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 o seu timeout padrão da Command Timeout palavra-chave da sua ligação.

Verificar valores padrão

Um novo SqlConnectionStringBuilder reporta o padrão para todas as opções. Este programa imprime os valores predefinidos que a maioria das aplicações analisa:

.NET
Framework .NET

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

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        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 Data Provider.

Opções de servidor e base de dados

Keyword	Aliases	Propriedade do construtor	Default	Description
`Data Source`	`Server`, `Address`, `Addr`, `Network Address`	`DataSource`	Empty	O servidor a que se deve ligar. Aceita um nome de host, `host,port`, `host\instance`, `(localdb)\instance`, e um `tcp:` prefixo de protocolo ou `np:` . Para os formulários aceites, consulte Especificar o servidor e a base de dados.
`Initial Catalog`	`Database`	`InitialCatalog`	Empty	A base de dados a usar após iniciar sessão. Quando está vazio, o servidor usa a base de dados padrão do login.
`AttachDbFilename`	`Extended Properties`, `Initial File Name`	`AttachDBFilename`	Empty	O caminho completo de um ficheiro principal de base de dados a anexar, para SQL Server Express e LocalDB.
`User Instance`	None	`UserInstance`	`false`	Redireciona a ligação para uma instância de utilizador do SQL Server Express. Para mais informações, consulte SQL Server Express instâncias de utilizador.
`Failover Partner`	`FailoverPartner`	`FailoverPartner`	Empty	O parceiro de espelhamento da base de dados tenta quando o servidor principal não está disponível. O espelhamento de bases de dados está obsoleto. Use grupos de disponibilidade para novas implementações.
`Current Language`	`Language`	`CurrentLanguage`	Empty	O nome da linguagem SQL Server para a sessão, como `us_english`. Controla os formatos de data e a linguagem das mensagens do sistema.

Opções de identidade de aplicação

Keyword	Aliases	Propriedade do construtor	Default	Description
`Application Name`	`App`	`ApplicationName`	`Core Microsoft SqlClient Data Provider`	O nome que o servidor reporta através `APP_NAME()` e nas vistas da sessão. Use um nome estável para cada carga de trabalho implementada. Valores distintos criam pools de ligação distintos.
`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 o encaminhamento de intenção de leitura quando o destino o suporta. Não torna as declarações apenas de leitura. Para mais informações, consulte Alta disponibilidade e recuperação em caso de desastres.

Para reportar qual framework ou ferramenta abriu uma ligação, use a RegisteredApplication propriedade. Não tem palavra-chave de cadeia de ligação. Para mais informações, consulte Reportar a identidade da aplicação.

Opções de autenticação

Keyword	Aliases	Propriedade do construtor	Default	Description
`Authentication`	None	`Authentication`	Não especificado	O método de autenticação. Para valores aceites, consulte a tabela seguinte.
`Integrated Security`	`Trusted_Connection`	`IntegratedSecurity`	`false`	`true`, `yes`, ou `sspi` utiliza a identidade do processo atual.
`User ID`	`UID`, `User`	`UserID`	Empty	O nome de login SQL, ou o identificador de utilizador ou cliente do Microsoft Entra ID, dependendo de `Authentication`.
`Password`	`PWD`	`Password`	Empty	A palavra-passe ou o segredo do cliente para métodos que o aceitam.
`Persist Security Info`	`PersistSecurityInfo`	`PersistSecurityInfo`	`false`	Quando `false`, o driver remove a palavra-passe após `SqlConnection.ConnectionString` a abertura da ligação. Deixa estar `false`.
`Server SPN`	`ServerSPN`	`ServerSPN`	Derivado do nome do servidor	Substitui o Nome Principal do Serviço (SPN) usado na autenticação integrada para o servidor principal.
`Failover Partner SPN`	`FailoverPartnerSPN`	`FailoverPartnerSPN`	Derivado do nome do parceiro	Sobrepõe o SPN utilizado para autenticação integrada ao parceiro de failover.

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

Value	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 gerida e login de ferramentas de programação.
`Active Directory Managed Identity`	Uma identidade gerida. Definido `User ID` para o ID do cliente de uma identidade atribuída pelo utilizador. `Active Directory MSI` é um pseudónimo.
`Active Directory Workload Identity`	Uma identidade de carga de trabalho Kubernetes.
`Active Directory Service Principal`	Uma aplicação com `User ID` definido para o ID do cliente e `Password` definido para o segredo do cliente.
`Active Directory Interactive`	Um utilizador que inicia sessão através de um prompt do navegador.
`Active Directory Device Code Flow`	Um utilizador que inicia sessão noutro dispositivo com um código.
`Active Directory Integrated`	O utilizador Windows iniciado sessão, através de uma configuração federada ou de login único sem interrupções.
`Active Directory Password`	Um nome de utilizador e uma palavra-passe. Este método está obsoleto. Usa outro método.

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

Opções de encriptação

Keyword	Aliases	Propriedade do construtor	Default	Description
`Encrypt`	None	`Encrypt`	`Mandatory`	`Strict` utiliza o TDS 8.0 e valida sempre o certificado do servidor. `Mandatory`, `true`, ou `yes` encripta a ligação. `Optional`, `false`, ou `no` encripta toda a ligação apenas quando o servidor assim o exige. Quando o servidor suporta encriptação mas não a exige, apenas o pacote de login é encriptado.
`Trust Server Certificate`	`TrustServerCertificate`	`TrustServerCertificate`	`false`	`true` ignora a validação do certificado do servidor. Ignorado quando `Encrypt=Strict`. Não o uses na produção.
`Host Name In Certificate`	`HostNameInCertificate`	`HostNameInCertificate`	Empty	Um nome de reserva para validação de certificados. O SqlClient valida primeiro o certificado contra o nome do servidor em `Data Source`. Só verifica `Host Name In Certificate` quando esse nome não coincide, por isso um valor errado não causa falha quando o nome do servidor já coincide. Não fixa um certificado. Para exigir um certificado específico, use `Server Certificate`. Não altera o destino da rede nem contorna a cadeia de confiança e verificações de validade. Deixa-o desligado quando o nome do servidor já corresponde ao certificado.
`Server Certificate`	`ServerCertificate`	`ServerCertificate`	Empty	O caminho de um ficheiro PEM, DER ou CER que deve corresponder exatamente ao certificado do servidor. O condutor verifica a correspondência apenas quando valida o certificado, por isso use-o com `Encrypt=Mandatory` ou `Encrypt=Strict` e `Trust Server Certificate=false`. Um ficheiro correspondente substitui a validação do nome da cadeia e do nome do host, por isso funciona com um certificado auto-assinado em que o cliente não confia.

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

Opções Always Encrypted

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

Opções de rede

Keyword	Aliases	Propriedade do construtor	Default	Description
`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 base de dados. Instâncias nomeadas dependem da implementação da rede. A implementação gerida, que o .NET utiliza no Linux e macOS e no Windows quando a rede gerida está ativa, suporta uma instância nomeada e envia o pedido 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 responde: `IPv4First`, `IPv6First`, ou `UsePlatformDefault`.
`Packet Size`	`PacketSize`	`PacketSize`	`8000`	O tamanho do pacote Tabular Data Stream (TDS) em bytes, de 512 a 32.768.

Um comutador AppContext de todo o processo pode alterar o predefinido Multi Subnet Failover para true. Para mais informações, consulte as comutações AppContext no SqlClient.

Opções de limite de tempo

Keyword	Aliases	Propriedade do construtor	Default	Description
`Connect Timeout`	`Connection Timeout`, `ConnectTimeout`, `Timeout`	`ConnectTimeout`	`15`	Segundos para esperar por uma ligação, incluindo a espera por uma ligaçã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 ligaçã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 ligação em pool. Passe a CancellationToken para chamadas assíncronas para que o interlocutor possa parar de esperar antes de expirar qualquer um dos tempos.

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

Keyword	Aliases	Propriedade do construtor	Default	Description
`Connect Retry Count`	`ConnectRetryCount`	`ConnectRetryCount`	`1`	Tenta novamente após uma falha temporária qualificada durante a primeira abertura e ao restaurar uma ligação de repouso partida. `0` Desliga as tentativas de novo. Os valores válidos são de 0 a 255.
`Connect Retry Interval`	`ConnectRetryInterval`	`ConnectRetryInterval`	`10`	Segundos entre tentativas de novo. 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 quando restaura uma ligação idle avariada. A primeira abertura usa o valor como definido, por isso o padrão permite uma retentativa em cada endpoint. O driver usa qualquer outro valor definido em ambos os casos.

Estas palavras-chave não tentam novamente um comando que falha enquanto está a correr. Para saltar a retentativa incorporada para uma abertura, chame uma Open sobrecarga com OpenWithoutRetry. Para políticas personalizadas, veja Lógica de retentativas configurável. Tente um comando apenas quando repeti-lo for seguro.

Opções de agrupamento

Keyword	Aliases	Propriedade do construtor	Default	Description
`Pooling`	None	`Pooling`	`true`	Reutiliza ligações físicas para corresponder cadeias de ligação.
`Min Pool Size`	None	`MinPoolSize`	`0`	Ligações físicas que a piscina mantém abertas depois de criada.
`Max Pool Size`	None	`MaxPoolSize`	`100`	O maior número de ligações físicas numa só piscina. Deve ser pelo menos 1.
`Connection Idle Timeout`	None	`IdleTimeout`	`300`	Segundos em que uma ligação pode ficar parada na piscina antes de esta a fechar. `0` Desliga a expiração de idle. Aplicado apenas quando a `Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior` comutação AppContext é `false`. Por padrão, é `true`.
`Load Balance Timeout`	`Connection Lifetime`	`LoadBalanceTimeout`	`0`	A idade máxima em segundos de uma ligação regressou à piscina. Uma ligação mais antiga está fechada. `0` Desliga o Limit.
`Pool Blocking Period`	`PoolBlockingPeriod`	`PoolBlockingPeriod`	`Auto`	Se o pool relança uma falha de login em cache durante um curto período: `Auto`, `AlwaysBlock`, ou `NeverBlock`. `Auto`desativa o bloqueio para endpoints SQL do Azure.

Cada cadeia de ligação distinta tem o seu próprio pool. Para chaves de pool, limpeza e tempo de inatividade, veja pooling de ligações ao SQL Server.

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

Keyword	Aliases	Propriedade do construtor	Default	Description
`Enlist`	None	`Enlist`	`true`	Regista a ligação na transação ambiente `System.Transactions` quando esta abre.
`Transaction Binding`	None	`TransactionBinding`	`Implicit Unbind`	`Implicit Unbind` Desliga a ligação quando a transação dos praças termina. `Explicit Unbind` mantém-no ligado até a ligação fechar ou o código o separar.
`Multiple Active Result Sets`	`MultipleActiveResultSets`	`MultipleActiveResultSets`	`false`	Permite mais do que um lote ativo numa só ligaçã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`. Deixa em `Latest`.
`Replication`	None	`Replication`	`false`	Identifica a ligação como uma ligação de replicação.

Opções apenas para o framework .NET

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

Keyword	Aliases	Propriedade do construtor	Default	Description
`Network Library`	`Net`, `Network`	`NetworkLibrary`	Empty	A biblioteca da rede. Não o combines com o prefixo ou `tcp:np:` em `Data Source`, porque a ligação falha. No .NET, prefixo `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` lança InvalidOperationException. Microsoft. O Data.SqlClient não suporta ligações contextuais SQL CLR.
`Asynchronous Processing`	Lança `ArgumentException: Keyword not supported`. Métodos assíncronos funcionam sem isso.
`Driver`, `Provider`	Lança `ArgumentException: Keyword not supported`. Estas palavras-chave pertencem ao ODBC e ao OLE DB.

Regras de validação

SqlConnectionStringBuilder rejeita palavras-chave desconhecidas e muitos valores inválidos quando as define. SqlConnectionFaz mais verificações quando defines a sua cadeia de ligação, incluindo valores individuais que o construtor aceita e combinações de palavras-chave. Uma cadeia que o construtor aceita pode ainda falhar quando crias a ligação.

O construtor e a conexão rejeitam estes 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 estes valores com ArgumentException, mesmo que o construtor os aceite:

Type System Version Exceto Latest, SQL Server 2012, SQL Server 2008, ou SQL Server 2005.
Transaction Binding exceto Implicit Unbind ou Explicit Unbind.
Um valor superior ao limite TDS para Application Name, Current Language, Data Source, Failover Partner, Initial Catalog, PasswordUser ID, , Workstation ID, , ou AttachDBFilename.

SqlConnection também rejeita estas 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.

Alterações na opção de revisão

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

Regista a cadeia de ligação atual, a versão do driver, o tipo de endpoint e o problema que estás a resolver.
Muda uma opção de cada vez.
Teste o estabelecimento da ligação, a autenticação, a validação de certificados, o pooling, o failover, o cancelamento e a execução de consultas.
Meça a latência da ligação, as esperas do pool e os números de erro.
Confirma a definição em cada instância implementada.

Uma cadeia de ligação alterada cria um novo pool. Durante uma implementação faseada, pools antigos e novos existem ao mesmo tempo, pelo que o número total de ligações físicas ao servidor pode aumentar.

Comentários

Esta página foi útil?

Última atualização a 2026-10-28