Možnosti připojení pro Microsoft. Data.SqlClient

Tento článek uvádí všechna klíčová slova připojovací řetězec, která Microsoft. Data.SqlClient přijímá. Každé klíčové slovo má také shodnou vlastnost SqlConnectionStringBuilder . Pro úvod, běžné vzory a pravidla parsování viz Spojovací řetězce.

Klíčová slova a aliasy nejsou rozlišující velká písmena. Když nastavíte hodnotu přes developerskou nemovitost, stavitel napíše kanonické klíčové slovo do sloupce Klíčové slovo .

Nastavte možnosti pomocí SqlConnectionStringBuilder

Začněte se základním připojovací řetězec, který obsahuje nastavení serveru, databáze a autentizace. Pak nastavte možnosti specifické pro zátěž přes builder properties. Záložky .NET Framework používají C# 7.3. Pro vytvoření projektu, který skládá vzorky, viz Vytvořit projekt.

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

.NET Framework

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

Výstup je:

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

Nová SqlCommand si bere výchozí časový limit od Command Timeout klíčového slova svého spojení.

Zkontrolujte výchozí hodnoty

Nový SqlConnectionStringBuilder hlásí výchozí hodnotu pro každou možnost. Tento program tiskne výchozí hodnoty, které většina aplikací kontroluje:

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

.NET Framework

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

Na .NET je výstup:

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 je Mandatory možnost. Ve .NET Frameworku je výchozí název Framework Microsoft SqlClient Zprostředkovatel dataplikace .

Možnosti serveru a databáze

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Data Source	Server, Address, , AddrNetwork Address	DataSource	Empty	Na server, ke kterému se připojit. Přijímá hostitelské jméno, host,port, host\instance, (localdb)\instance, a tcp: protokolovou předponu OR np: . Pro přijaté formuláře viz Specifikujte server a databázi.
Initial Catalog	Database	InitialCatalog	Empty	Databáze pro použití po přihlášení. Když je prázdný, server použije výchozí databázi přihlašovacího údaje.
AttachDbFilename	Extended Properties, Initial File Name	AttachDBFilename	Empty	Celá cesta primárního databázového souboru k připojení pro SQL Server Express a LocalDB.
User Instance	None	UserInstance	false	Přesměruje spojení na uživatelskou instanci SQL Server Express. Pro více informací viz uživatelské instance SQL Server Express.
Failover Partner	FailoverPartner	FailoverPartner	Empty	Partner pro zrcadlení databáze to zkouší, když není primární server dostupný. Zrcadlení databází je zastaralá funkce. Používejte skupiny dostupnosti pro nové nasazení.
Current Language	Language	CurrentLanguage	Empty	Název jazyka SQL Server pro relaci, například us_english. Řídí formáty dat a jazyk systémových zpráv.

Možnosti identity aplikace

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Application Name	App	ApplicationName	Core Microsoft SqlClient Data Provider	Jméno, které server hlásí skrze APP_NAME() a v session views. Pro každou nasazenou pracovní zátěž použijte jedno stabilní jméno. Různé hodnoty vytvářejí odlišné skupiny spojů.
Workstation ID	WorkstationID, WSID	WorkstationID	Název místního počítače	Klientský počítač je název, který server hlásí přes HOST_NAME().
Application Intent	ApplicationIntent	ApplicationIntent	ReadWrite	ReadOnly požaduje směrování s úmyslem čtení při podpoře cíle. Nezobrazuje výroky pouze pro čtení. Pro více informací viz Vysoká dostupnost a obnova po havárii.

Pro nahlášení, který framework nebo nástroj otevřel spojení, použijte tuto vlastnost RegisteredApplication . Nemá žádné klíčové slovo pro připojovací řetězec. Pro více informací viz Nahlásit identitu aplikace.

Možnosti ověřování

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Authentication	None	Authentication	Neurčeno	Metoda ověřování. Pro přijímané hodnoty viz následující tabulka.
Integrated Security	Trusted_Connection	IntegratedSecurity	false	true, yes, nebo sspi používá identitu aktuálního procesu.
User ID	UID, User	UserID	Empty	SQL přihlašovací jméno nebo identifikátor uživatele či klienta Microsoft Entra ID, v závislosti na Authentication.
Password	PWD	Password	Empty	Heslo nebo klientské tajemství pro metody, které ho přijímají.
Persist Security Info	PersistSecurityInfo	PersistSecurityInfo	false	Když false, ovladač odstraní heslo po SqlConnection.ConnectionString otevření připojení. Nech to falsebýt.
Server SPN	ServerSPN	ServerSPN	Odvozeno z názvu serveru	Přepíše název instančního objektu služby (SPN) používaný pro integrované ověřování vůči primárnímu serveru.
Failover Partner SPN	FailoverPartnerSPN	FailoverPartnerSPN	Odvozeno od partnerského jména	Přepisuje SPN používané pro integrovanou autentizaci vůči failover partnerovi.

Authentication tyto hodnoty přijímá. Stavitel je zapisuje bez mezer, například ActiveDirectoryDefault, a parser přijímá obě formy.

Value	Identity
Sql Password	SQL přihlášení s User ID a Password.
Active Directory Default	Řetězec zdrojů přihlašovacích údajů, jako jsou proměnné prostředí, spravovaná identita a přihlášení vývojářských nástrojů.
Active Directory Managed Identity	Spravovaná identita. Nastavte User ID na ID klienta uživatelem přiřazené identity. služba Active Directory MSI je alias.
Active Directory Workload Identity	Identita workloadu v Kubernetes.
Active Directory Service Principal	Aplikace s User ID nastaveným na ID klienta a Password nastaveným na klientské tajemství.
Active Directory Interactive	Uživatel, který se přihlásí přes výzvu prohlížeče.
Active Directory Device Code Flow	Uživatel, který se přihlásí na jiném zařízení pomocí kódu.
Active Directory Integrated	Přihlášený uživatel Windows prostřednictvím federované nebo bezproblémové konfigurace jednorázového přihlášení.
Active Directory Password	Uživatelské jméno a heslo. Tato metoda je zastaralá. Použijte jinou metodu.

Microsoft Entra ID metody potřebují Microsoft.Data.SqlClient.Extensions.Azure tento balíček. Pro nastavení a příklady viz Microsoft Entra ID autentizace a SQL Server autentizace.

Možnosti šifrování

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Encrypt	None	Encrypt	Mandatory	Strict používá TDS 8.0 a vždy ověřuje serverový certifikát. Mandatory, true, nebo yes šifruje spojení. Optional, false, nebo no šifruje celé spojení pouze tehdy, když to server vyžaduje. Když server šifrování podporuje, ale nevyžaduje ho, zašifruje se pouze přihlašovací paket.
Trust Server Certificate	TrustServerCertificate	TrustServerCertificate	false	true přeskočí validaci serverového certifikátu. Ignoruje se, pokud Encrypt=Strict. Nepoužívejte ho v produkčním prostředí.
Host Name In Certificate	HostNameInCertificate	HostNameInCertificate	Empty	Záložní název pro ověřování certifikátů. SqlClient nejprve ověří certifikát vůči názvu serveru v Data Source. Kontroluje Host Name In Certificate to jen tehdy, když se jméno neshoduje, takže špatná hodnota nezpůsobí selhání, když už název serveru sedí. Certifikát se nepřipíná. Pro požadavek konkrétního certifikátu použijte Server Certificate. Nemění cílovou stanici sítě ani neobchází kontroly řetězce důvěry a expirace. Nechte to nenastavené, když už název serveru odpovídá certifikátu.
Server Certificate	ServerCertificate	ServerCertificate	Empty	Cesta souboru PEM, DER nebo CER, která musí přesně odpovídat certifikátu serveru. Řidič kontroluje shodu pouze při ověřování certifikátu, takže ji použije s Encrypt=Mandatory nebo Encrypt=Strict a Trust Server Certificate=false. Shodný soubor nahrazuje ověřování řetězce a hostitelského jména, takže funguje s vlastním podepsaným certifikátem, kterému klient nedůvěřuje.

Pro úplná validační pravidla viz Šifrování a ověřování certifikátů.

Možnosti s vždy šifrovaním

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Column Encryption Setting	ColumnEncryption	ColumnEncryptionSetting	Disabled	Enabled zapne Always Encrypted pro připojení.
Attestation Protocol	None	AttestationProtocol	Neurčeno	Protokol pro ověřování enklávy: AAS, HGS, nebo None.
Enclave Attestation Url	None	EnclaveAttestationUrl	Empty	Endpoint pro potvrzovací službu pro Always Encrypted s bezpečnými enklávami.

Možnosti sítě

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Multi Subnet Failover	MultiSubnetFailover	MultiSubnetFailover	false	Zkouší všechny IP adresy, na které se server paralelně vyřeší. Použijte ho pro skupinové posluchače dostupnosti a instance failover clusterů dosažené přes TCP. Není podporováno zrcadlením databází. Pojmenované instance závisí na implementaci sítě. Spravovaná implementace, kterou .NET používá na Linuxu a macOS a na Windows, když je zapnutá spravovaná síť, podporuje pojmenovanou instanci a posílá požadavek SQL Server Browseru na každou vyřešenou adresu paralelně. Nativní implementace ve Windows může odmítnout pojmenovanou instanci s chybou SNI 48.
IP Address Preference	IPAddressPreference	IPAddressPreference	IPv4First	Pořadí pro pokus o vyřešené adresy: IPv4First, IPv6First, nebo UsePlatformDefault.
Packet Size	PacketSize	PacketSize	8000	Velikost paketu Tabular Data Stream (TDS) v bajtech od 512 do 32 768.

Přepínač AppContext v celém procesu může změnit Multi Subnet Failover výchozí na .true Pro více informací viz AppContext switchi v SqlClient.

Možnosti timeoutu

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Connect Timeout	Connection Timeout, ConnectTimeout, Timeout	ConnectTimeout	15	Několik sekund čekání na připojení, včetně čekání na spojení, kdy je pool plný. 0 čeká donekonečna.
Command Timeout	None	CommandTimeout	30	Výchozí CommandTimeout nastavení je v sekundách pro příkazy vytvořené na připojení. 0 čeká donekonečna.

Connect Timeout Neomezuje to provádění dotazů. Command Timeout Neomezuje přihlášení ani čekání na společné připojení. Předejte a CancellationToken na asynchronní hovory, aby volající mohl přestat čekat dříve, než vyprší časový limit.

Možnosti obnovy spojení

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Connect Retry Count	ConnectRetryCount	ConnectRetryCount	1	Znovu se pokusí po kvalifikačním přechodném selhání při prvním otevření a při obnově přerušeného nečinného spojení. 0 Vypíná opakované pokusy. Platné hodnoty jsou 0 až 255.
Connect Retry Interval	ConnectRetryInterval	ConnectRetryInterval	10	Sekundy mezi pokusy o opakování. Platné hodnoty jsou od 1 do 60.

Když Connect Retry Count je 1, což je výchozí nastavení, ovladač používá 2 pro Azure SQL endpointy a 5 pro serverless SQL pool endpointy Azure Synapse Analytics, když obnovuje přerušené nefunkční připojení. První otevření používá hodnotu nastavenou, takže výchozí umožňuje jedno opakování na každém koncovém bodě. Ovladač používá jakoukoli jinou hodnotu nastavenou v obou případech.

Tato klíčová slova nezkoušejí znovu příkaz, který selže, zatímco běží. Pro přeskočení vestavěného pokusu pro jedno otevření voláme Open přetížení s OpenWithoutRetry. Pro vlastní politiky viz Konfigurovatelná logika opakovaných pokusů. Zopakujte příkaz jen tehdy, když je opakování bezpečné.

Možnosti sdružování

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Pooling	None	Pooling	true	Znovu používá fyzická spojení pro porovnávání spojovacích řetězců.
Min Pool Size	None	MinPoolSize	0	Fyzická spojení, která bazén udržuje otevřený i po svém vytvoření.
Max Pool Size	None	MaxPoolSize	100	Nejvíce fyzických spojení v jednom bazénu. Musí být alespoň 1.
Connection Idle Timeout	None	IdleTimeout	300	Sekundy, kdy může spojení zůstat nečinné v bazénu, než ho pool uzavře. 0 Vypne vypršení volnoběhu. Vynucováno pouze tehdy, když je přepínač Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext .false Ve výchozím nastavení je to true.
Load Balance Timeout	Connection Lifetime	LoadBalanceTimeout	0	Maximální stáří připojení v sekundách se vrátilo do poolu. Starší spojení je uzavřené. 0 Vypíná limit.
Pool Blocking Period	PoolBlockingPeriod	PoolBlockingPeriod	Auto	Zda pool na krátkou dobu Autoznovu vyhodí neúspěšné přihlášení v cache: , AlwaysBlock, nebo NeverBlock. Autoturns blocking off for Azure SQL endpoints.

Každý odlišný připojovací řetězec má svůj vlastní pool. Pro klíče poolu, vymazávání a čas nečinnosti viz SQL Server connection pooling.

Transakční a relační možnosti

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Enlist	None	Enlist	true	Při otevření se připojí k připojení do ambientní System.Transactions transakce.
Transaction Binding	None	TransactionBinding	Implicit Unbind	Implicit Unbind odpojí spojení po ukončení transakce s zařazenými vojáky. Explicit Unbind Drží ho připojeného, dokud se spojení nezavře nebo ho kód neodpojí.
Multiple Active Result Sets	MultipleActiveResultSets	MultipleActiveResultSets	false	Umožňuje více než jednu aktivní dávku na jednom připojení.
Type System Version	None	TypeSystemVersion	Latest	Systém typu serveru, který ovladač zpřístupňuje. Přijímá Latest, SQL Server 2012, SQL Server 2008, a SQL Server 2005. Nechte to na Latest.
Replication	None	Replication	false	Identifikuje spojení jako replikační spojení.

Pouze možnosti pro .NET Framework

Tato klíčová slova jsou přijímána pouze ve .NET Frameworku. Na .NET stavitel hází NotSupportedException a SqlConnection hází ArgumentException.

Keyword	Aliases	Nemovitost pro stavitele	Výchozí	Popis
Network Library	Net, Network	NetworkLibrary	Empty	Síťová knihovna. Nekombinujte ho s prefixem nebo tcp:np: v , Data Sourceprotože spojení selže. Na .NET předponu Data Source použijte s tcp: nebo np: místo toho.
Connection Reset	None	ConnectionReset	true	Obsolete.
Transparent Network IP Resolution	TransparentNetworkIPResolution	TransparentNetworkIPResolution	true	Obsolete.

Nepodporovaná klíčová slova

Keyword	Result
Context Connection	Context Connection=true vyhodí InvalidOperationException. Microsoft. Data.SqlClient nepodporuje kontextová spojení s SQL CLR.
Asynchronous Processing	Vyhodí ArgumentException: Keyword not supported. Asynchronní metody fungují i bez něj.
Driver, Provider	Vyhodí ArgumentException: Keyword not supported. Tato klíčová slova patří do ODBC a OLE DB.

Pravidla ověřování

SqlConnectionStringBuilder Odmítá neznámá klíčová slova a mnoho neplatných hodnot, když je nastavíte. SqlConnectionprovádí více kontrol, když nastavíte svůj připojovací řetězec, včetně jednotlivých hodnot, které builder přijímá, a kombinací klíčových slov. Řetězec, který builder přijme, může při vytvoření spojení selhat.

Stavitel a spojení tyto hodnoty odmítají s ArgumentException:

• Connect Timeout, Command Timeout, , , Connection Idle Timeout, nebo Min Pool SizeLoad Balance Timeoutméně než 0.
• Max Pool Size méně než 1.
• Packet Size venku od 512 do 32 768.
• Connect Retry Count venku od 0 do 255.
• Connect Retry Interval venku od 1 do 60.
• Klíčové slovo, které v tomto článku není.

SqlConnection také odmítá tyto hodnoty s ArgumentException, i když je stavitel přijímá:

• Type System Version kromě Latest, SQL Server 2012, SQL Server 2008, nebo SQL Server 2005.
• Transaction Bindingkromě Implicit Unbind nebo .Explicit Unbind
• Hodnota delší než limit TDS pro Application Name, Current Language, Data Source, Failover Partner, Initial Catalog, Password, User ID, Workstation IDnebo .AttachDBFilename

SqlConnection také odmítá tyto kombinace s ArgumentException:

• Min Pool Size větší než Max Pool Size.
• Failover Partner bez Initial Catalog.
• Failover Partner s Multi Subnet Failover=true, User Instance=true, nebo Application Intent=ReadOnly.
• Authentication s Integrated Security=true.
• Passwords služba Active Directory Integrated, služba Active Directory Interactive, služba Active Directory Managed Identity, služba Active Directory MSI, , služba Active Directory Defaultnebo .služba Active Directory Workload Identity
• User IDnebo Password s .služba Active Directory Device Code Flow

Zkontrolujte změny možností

Než změníte možnost ve výrobě:

1. Zaznamenejte aktuální připojovací řetězec, verzi ovladače, typ endpointu a problém, který řešíte.
2. Měňte jednu možnost po druhé.
3. Otestujte navázání spojení, autentizaci, ověřování certifikátů, poolování, failover, rušení a provádění dotazů.
4. Měřte latenci připojení, čekání na pool a chybová čísla.
5. Potvrďte nastavení na každé nasazené instanci.

Změněný připojovací řetězec vytvoří nový pool. Během postupného nasazení existují současně staré i nové pooly, takže celkový počet fyzických připojení k serveru může stoupat.

Související obsah

• Připojovací řetězce
• Tvůrci připojovacích řetězců
• Připojte se ke zdroji dat
• SQL Server connection pooling
• Šifrování a ověřování certifikátů