Anslutningsalternativ för Microsoft. Data.SqlClient

Den här artikeln listar varje reťazec pripojenia-nyckelord som Microsoft. Data.SqlClient accepterar. Varje nyckelord har också en matchande SqlConnectionStringBuilder egenskap. För en introduktion, vanliga mönster och parsningsregler, se Anslutningssträngar.

Nyckelord och alias är inte kasuskänsliga. När du sätter ett värde via en byggaregenskap skriver byggaren det kanoniska nyckelordet i kolumnen Nyckelord .

Sätt inställningar med SqlConnectionStringBuilder

Börja från en grundläggande reťazec pripojenia som innehåller server, databas och autentiseringsinställningar. Ställ sedan in arbetsbelastningsspecifika alternativ via builder-egenskaper. .NET Framework-flikarna använder C# 7.3. För att skapa ett projekt som kör proverna, se Skapa projektet.

.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-ramverket

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

Resultatet är:

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

En ny SqlCommand tar sin standardtimeout från Command Timeout nyckelordet för dess anslutning.

Kontrollera standardvärden

En ny SqlConnectionStringBuilder rapporterar standarden för varje alternativ. Detta program skriver ut standardinställningarna som de flesta applikationer granskar:

.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-ramverket

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

På .NET är utdatan:

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 är alternativet Mandatory . På .NET Framework är Framework Microsoft SqlClient Data Providerstandardnamnet på applikationen .

Server- och databasalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Data Source	Server, Address, Addr, Network Address	DataSource	Tomt	Servern att ansluta till. Accepterar ett värdnamn, host,port, host\instance, (localdb)\instance, och ett tcp: eller np: protokollprefix. För de accepterade formulären, se Specificera servern och databasen.
Initial Catalog	Database	InitialCatalog	Tomt	Databasen att använda efter inloggning. När den är tom använder servern inloggningens standarddatabas.
AttachDbFilename	Extended Properties, Initial File Name	AttachDBFilename	Tomt	Den fullständiga vägen för en primär databasfil att bifoga, för SQL Server Express och LocalDB.
User Instance	None	UserInstance	false	Omdirigerar anslutningen till en SQL Server Express-användarinstans. För mer information, se SQL Server Express användarinstanser.
Failover Partner	FailoverPartner	FailoverPartner	Tomt	Databasspegelpartnern för att försöka när primärservern inte är tillgänglig. Databasspegling är föråldrad. Använd tillgänglighetsgrupper för nya distributioner.
Current Language	Language	CurrentLanguage	Tomt	SQL Server-språkets namn för sessionen, såsom us_english. Kontrollerar datumformat och systemmeddelandespråk.

Applikationsidentitetsalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Application Name	App	ApplicationName	Core Microsoft SqlClient Data Provider	Namnet som servern rapporterar genom APP_NAME() och i sessionsvyer. Använd ett stabilt namn för varje distribuerad arbetsbelastning. Distinkta värden skapar olika kopplingspooler.
Workstation ID	WorkstationID, WSID	WorkstationID	Namnet på den lokala datorn	Klientdatorns namn som servern rapporterar genom HOST_NAME().
Application Intent	ApplicationIntent	ApplicationIntent	ReadWrite	ReadOnly begär läsavsiktsroutning när målet stöder det. Den gör inte uttalanden skrivskyddade. För mer information, se Hög tillgänglighet och katastrofåterställning.

För att rapportera vilket ramverk eller verktyg som öppnade en anslutning, använd egenskapen RegisteredApplication . Det finns inget reťazec pripojenia-nyckelord. För mer information, se Rapportera applikationens identitet.

Autentiseringsalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Authentication	None	Authentication	Har inte angetts	Autentiseringsmetoden. För accepterade värden, se följande tabell.
Integrated Security	Trusted_Connection	IntegratedSecurity	false	true, yes, eller sspi använder identiteten för den aktuella processen.
User ID	UID, User	UserID	Tomt	SQL-inloggningsnamnet, eller Microsoft Entra ID:s användar- eller klientidentifierare, beroende på Authentication.
Password	PWD	Password	Tomt	Lösenordet eller klienthemligheten för metoder som accepterar en.
Persist Security Info	PersistSecurityInfo	PersistSecurityInfo	false	När false, tar drivrutinen bort lösenordet från SqlConnection.ConnectionString efter att anslutningen öppnats. Låt det vara false.
Server SPN	ServerSPN	ServerSPN	Härlett från servernamnet	Åsidosätter Service Principal Name (SPN) som används för integrerad autentisering till primärservern.
Failover Partner SPN	FailoverPartnerSPN	FailoverPartnerSPN	Härlett från partnernamnet	Åsidosätter SPN:n som används för integrerad autentisering till failover-partnern.

Authentication accepterar dessa värderingar. Byggaren skriver dem utan mellanslag, såsom ActiveDirectoryDefault, och parsern accepterar båda formerna.

Value	Identity
Sql Password	En SQL-inloggning med User ID och Password.
Active Directory Default	En kedja av inloggningskällor, såsom miljövariabler, hanterad identitet och inloggning för utvecklarverktyg.
Active Directory Managed Identity	En hanterad identitet. Ställ User ID in till klient-ID för en användartilldelad identitet. služba Active Directory MSI är ett alias.
Active Directory Workload Identity	En Kubernetes-arbetsbelastningsidentitet.
Active Directory Service Principal	En applikation med User ID inställning till klient-ID och Password klienthemlighet.
Active Directory Interactive	En användare som loggar in via en webbläsarprompt.
Active Directory Device Code Flow	En användare som loggar in på en annan enhet med en kod.
Active Directory Integrated	Den inloggade Windows-användaren, via en federerad eller sömlös enkel inloggningskonfiguration.
Active Directory Password	Ett användarnamn och lösenord. Den här metoden är föråldrad. Använd en annan metod.

Microsoft Entra ID-metoder kräver paketetMicrosoft.Data.SqlClient.Extensions.Azure. För uppsättning och exempel, se Microsoft Entra ID-autentisering och SQL Server-autentisering.

Krypteringsalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Encrypt	None	Encrypt	Mandatory	Strict använder TDS 8.0 och validerar alltid servercertifikatet. Mandatory, true, eller yes krypterar anslutningen. Optional, false, eller no krypterar hela anslutningen endast när servern kräver det. När servern stödjer kryptering men inte kräver det, är det bara inloggningspaketet som krypteras.
Trust Server Certificate	TrustServerCertificate	TrustServerCertificate	false	true Hoppar över validering av servercertifikat. Ignoreras när Encrypt=Strict. Använd den inte i produktion.
Host Name In Certificate	HostNameInCertificate	HostNameInCertificate	Tomt	Ett reservnamn för certifikatvalidering. SqlClient validerar först certifikatet mot servernamnet i Data Source. Den kontrollerar Host Name In Certificate bara när det namnet inte stämmer, så ett felaktigt värde orsakar inte ett fel när servernamnet redan stämmer. Det fäster inget certifikat. För att kräva ett specifikt certifikat, använd Server Certificate. Det ändrar inte nätverksdestinationen eller kringgår förtroendekedja och utgångskontroller. Låt den vara oaktiverad när servernamnet redan matchar certifikatet.
Server Certificate	ServerCertificate	ServerCertificate	Tomt	Sökvägen för en PEM-, DER- eller CER-fil som exakt måste matcha servercertifikatet. Föraren kontrollerar matchningen endast när den validerar certifikatet, så använd det med Encrypt=Mandatory eller Encrypt=Strict och Trust Server Certificate=false. En matchande fil ersätter verifiering av kedjan och värdnamnet, så den fungerar med ett självsignerat certifikat som klienten inte litar på.

För fullständiga valideringsregler, se Kryptering och certifikatvalidering.

Alltid krypterade alternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Column Encryption Setting	ColumnEncryption	ColumnEncryptionSetting	Disabled	Enabled aktiverar Alltid krypterat för anslutningen.
Attestation Protocol	None	AttestationProtocol	Har inte angetts	Enklavattesteringsprotokollet: AAS, HGS, eller None.
Enclave Attestation Url	None	EnclaveAttestationUrl	Tomt	Attestationstjänstens endpoint för Always Encrypted with secure enclaves.

Nätverksalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Multi Subnet Failover	MultiSubnetFailover	MultiSubnetFailover	false	Försöker alla IP-adresser som servernamnet löses till parallellt. Använd det för tillgänglighetsgrupplyssnare och failover-klusterinstanser som nås via TCP. Stöds inte med databasspegling. Namngivna instanser beror på nätverksimplementationen. Den hanterade implementationen, som .NET använder på Linux och macOS samt på Windows när hanterad nätverksfunktion är på, stöder en namngiven instans och skickar SQL Server Browser-begäran till varje löst adress parallellt. Den inbyggda implementationen på Windows kan avvisa en namngiven instans med SNI-fel 48.
IP Address Preference	IPAddressPreference	IPAddressPreference	IPv4First	Ordningen för att försöka lösa adresser: IPv4First, IPv6First, eller UsePlatformDefault.
Packet Size	PacketSize	PacketSize	8000	Tabular Data Stream (TDS)-paketstorleken i bytes, från 512 till 32 768.

Ett processomfattande AppContext-byte kan ändra standardinställningen Multi Subnet Failover till true. För mer information, se AppContext-switchar i SqlClient.

Timeout-alternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Connect Timeout	Connection Timeout, ConnectTimeout, Timeout	ConnectTimeout	15	Sekunder att vänta på en anslutning, inklusive väntan på en poolad anslutning när poolen är full. 0 väntar på obestämd tid.
Command Timeout	None	CommandTimeout	30	Standarden CommandTimeout i sekunder för kommandon som skapas på anslutningen. 0 väntar på obestämd tid.

Connect Timeout Det begränsar inte frågeexekveringen. Command Timeout Det begränsar inte inloggning eller väntan på en poolad anslutning. Skicka a CancellationToken till asynkrona samtal så att uppringaren kan sluta vänta innan någon av timeouterna går ut.

Alternativ för anslutningsåterställning

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Connect Retry Count	ConnectRetryCount	ConnectRetryCount	1	Omprov efter ett kval-passientfel under första öppningen och när man återställde en trasig tomgångsanslutning. 0 stänger av omförsök. Giltiga värden är 0 till 255.
Connect Retry Interval	ConnectRetryInterval	ConnectRetryInterval	10	Sekunder mellan försöken till om. Giltiga värden är 1 till 60.

När Connect Retry Count är 1, vilket är standard, använder 2 drivrutinen för Azure SQL-endpoints och 5 för Azure Synapse Analytics serverless SQL pool-endpoints när den återställer en bruten idle-anslutning. Den första öppningen använder värdet som satt, så standarden tillåter ett nytt försök på varje ändpunkt. Drivrutinen använder ett annat värde som är satt i båda fallen.

Dessa nyckelord försöker inte om ett kommando som misslyckas medan det körs. För att hoppa över det inbyggda försöket för en öppen, anropa en Open överbelastning med OpenWithoutRetry. För anpassade policyer, se Konfigurerbar återförsökslogik. Försök om ett kommando bara när det är säkert att upprepa det.

Alternativ för poolning

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Pooling	None	Pooling	true	Återanvänder fysiska kopplingar för att matcha anslutningssträngar.
Min Pool Size	None	MinPoolSize	0	Fysiska kopplingar som poolen håller öppna efter att den har skapats.
Max Pool Size	None	MaxPoolSize	100	De flesta fysiska kopplingarna i en pool. Måste vara minst 1.
Connection Idle Timeout	None	IdleTimeout	300	Sekunder då en anslutning kan stå stilla i poolen innan poolen stänger den. 0 stänger av tomgångsutlopp. Endast upprätthållen när AppContext-omkopplingen Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior är false. Som standardvärde är det true.
Load Balance Timeout	Connection Lifetime	LoadBalanceTimeout	0	Den maximala åldern i sekunder för en anslutning som återvänder till poolen. En äldre anslutning är stängd. 0 stänger av gränsen.
Pool Blocking Period	PoolBlockingPeriod	PoolBlockingPeriod	Auto	Om poolen kastar om ett cachelagrat inloggningsfel under en kort period: Auto, AlwaysBlock, eller NeverBlock. Autostänger av blockeringen för Azure SQL-endpoints.

Varje distinkt reťazec pripojenia får sin egen pool. För poolnycklar, rensning och inaktiv, se SQL Server connection pooling.

Transaktions- och sessionsalternativ

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Enlist	None	Enlist	true	Aktiverar anslutningen i ambient-transaktionen System.Transactions när den öppnas.
Transaction Binding	None	TransactionBinding	Implicit Unbind	Implicit Unbind kopplar från anslutningen när transaktionen för värvade avslutas. Explicit Unbind Behåller den ansluten tills anslutningen stängs eller koden kopplar bort den.
Multiple Active Result Sets	MultipleActiveResultSets	MultipleActiveResultSets	false	Tillåter mer än en aktiv batch på en och samma anslutning.
Type System Version	None	TypeSystemVersion	Latest	Servertypen av system som drivrutinen exponerar. Accepterar Latest, SQL Server 2012, SQL Server 2008, och SQL Server 2005. Lämna det vid Latest.
Replication	None	Replication	false	Identifierar anslutningen som en replikationsanslutning.

.NET Framework endast alternativ

Dessa nyckelord accepteras endast på .NET Framework. På .NET kastar NotSupportedException byggaren och SqlConnection kastar ArgumentException.

Keyword	Aliases	Byggarfastighet	Standardinställning	Beskrivning
Network Library	Net, Network	NetworkLibrary	Tomt	Nätverksbiblioteket. Kombinera det inte med a tcp: eller np: prefix i Data Source, eftersom anslutningen misslyckas. På .NET, prefixet Data Source med tcp: eller np: istället.
Connection Reset	None	ConnectionReset	true	Obsolete.
Transparent Network IP Resolution	TransparentNetworkIPResolution	TransparentNetworkIPResolution	true	Obsolete.

Ej stödda nyckelord

Keyword	Result
Context Connection	Context Connection=true kastar InvalidOperationException. Microsoft. Data.SqlClient stöder inte SQL CLR-kontextanslutningar.
Asynchronous Processing	Kastar ArgumentException: Keyword not supported. Asynkrona metoder fungerar utan det.
Driver, Provider	Kastar ArgumentException: Keyword not supported. Dessa nyckelord tillhör ODBC och OLE DB.

Valideringsregler

SqlConnectionStringBuilder Förkastar okända nyckelord och många ogiltiga värden när du sätter dem. SqlConnectionUtför fler kontroller när du ställer in dess reťazec pripojenia, inklusive enskilda värden som byggaren accepterar och kombinationer av nyckelord. En sträng som byggaren accepterar kan fortfarande misslyckas när du skapar anslutningen.

Byggaren och kopplingen förkastar dessa värden med ArgumentException:

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, eller Min Pool Size mindre än 0.
• Max Pool Size mindre än 1.
• Packet Size Utanför 512 till 32 768.
• Connect Retry Count Utanför 0 till 255.
• Connect Retry Interval Utanför 1 till 60.
• Ett nyckelord som inte finns med i den här artikeln.

SqlConnection förkastar också dessa värden med ArgumentException, även om byggaren accepterar dem:

• Type System Versionförutom Latest, , , SQL Server 2008, eller SQL Server 2005SQL Server 2012.
• Transaction Binding annat än Implicit Unbind eller Explicit Unbind.
• Ett värde längre än TDS-gränsen för Application Name, , , Data SourceFailover Partner, , Initial CatalogPassword, User ID, Workstation IDeller AttachDBFilename. Current Language

SqlConnection avvisar också dessa kombinationer med ArgumentException:

• Min Pool Size större än Max Pool Size.
• Failover Partner utan Initial Catalog.
• Failover Partner med Multi Subnet Failover=true, User Instance=true, eller Application Intent=ReadOnly.
• Authentication med Integrated Security=true.
• Password med 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 Default, , eller služba Active Directory Workload Identity.
• User ID eller Password med služba Active Directory Device Code Flow.

Ändringar i granskningsalternativ

Innan du ändrar ett alternativ i produktion:

1. Registrera aktuell reťazec pripojenia, drivrutinsversion, endpoint-typ och problemet du löser.
2. Byt ett alternativ i taget.
3. Testa anslutningsetablering, autentisering, certifikatvalidering, anslutningspoolning, failover, avbrytning och frågekörning.
4. Mät anslutningslatens, poolväntetid och felnummer.
5. Bekräfta inställningen på varje distribuerad instans.

En ändrad reťazec pripojenia skapar en ny pool. Under en stegvis utrullning finns gamla och nya pooler samtidigt, så det totala antalet fysiska anslutningar till servern kan öka.

Relaterat innehåll

• Anslutningssträngar
• Anslutningssträngsbyggare
• Koppla till en datakälla
• SQL Server anslutningspoolning
• Kryptering och certifikatvalidering