Verbindingsopties voor Microsoft. Data.SqlClient

Dit artikel vermeldt elk verbindingsreeks-trefwoord dat Microsoft. Data.SqlClient accepteert. Elk trefwoord heeft ook een overeenkomende SqlConnectionStringBuilder eigenschap. Voor een inleiding, veelvoorkomende patronen en parsingregels, zie Verbindingsstrings.

Trefwoorden en aliassen zijn niet hoofdlettergevoelig. Wanneer je een waarde instelt via een builder-eigenschap, schrijft de builder het canonieke trefwoord in de kolom Trefwoord .

Instellingen instellen met SqlConnectionStringBuilder

Begin met een basis-verbindingsreeks die de server-, database- en authenticatie-instellingen bevat. Stel vervolgens workload-specifieke opties in via builder-eigenschappen. De .NET Framework-tabbladen gebruiken C# 7.3. Om een project te maken dat de samples uitvoert, zie Create the project.

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

De uitvoer is:

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

Een nieuwe SqlCommand neemt zijn standaard time-out uit het Command Timeout sleutelwoord van zijn verbinding.

Controleer de standaardwaarden

Een nieuwe SqlConnectionStringBuilder meldt de standaard voor elke optie. Dit programma print de standaardwaarden af die de meeste applicaties beoordelen:

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

Op .NET is de uitvoer:

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 is de Mandatory optie. Op .NET Framework is Framework Microsoft SqlClient Data Providerde standaard applicatienaam .

Server- en databaseopties

Applicatie-identiteitsopties

Om te rapporteren welk framework of tool een verbinding heeft geopend, gebruik je de RegisteredApplication eigenschap. Het heeft geen verbindingsreeks-sleutelwoord. Voor meer informatie, zie Rapporteer de applicatieidentiteit.

Verificatieopties

Authentication deze waarden accepteert. De bouwer schrijft ze zonder spaties zoals ActiveDirectoryDefault, en de parser accepteert beide vormen.

Microsoft Entra ID-methoden hebben het Microsoft.Data.SqlClient.Extensions.Azure pakket nodig. Voor de opstelling en voorbeelden, zie Microsoft Entra ID-authenticatie en SQL Server-authenticatie.

Versleutelingsopties

Voor de volledige validatieregels, zie Versleuteling en certificaatvalidatie.

Altijd versleutelde opties

Netwerkopties

Een procesbrede AppContext-switch kan de Multi Subnet Failover standaard veranderen naar true. Voor meer informatie, zie AppContext-switches in SqlClient.

Opties voor time-out

Connect Timeout Beperkt de uitvoering van zoekopdrachten niet. Command Timeout Het beperkt het inloggen of het wachten op een gepoolde verbinding niet. Geef a CancellationToken door aan asynchrone oproepen zodat de beller kan stoppen met wachten voordat een van de time-outs verloopt.

Opties voor verbindingsherstel

Wanneer Connect Retry Count , 1wat de standaard is, gebruikt 2 de driver voor Azure SQL-endpoints en 5 voor Azure Synapse Analytics serverless SQL-pool-endpoints wanneer een verbroken idle-verbinding wordt hersteld. De eerste open gebruikt de waarde zoals ingesteld, dus de standaard staat één herpoging toe op elk eindpunt. De driver gebruikt in beide gevallen elke andere waarde als ingesteld.

Deze sleutelwoorden proberen een commando dat mislukt terwijl het wordt uitgevoerd niet opnieuw uit te voeren. Om de ingebouwde herpoging voor één open over te slaan, roep een Open overload aan met OpenWithoutRetry. Voor aangepaste beleidslijnen, zie Configurable retry logic. Probeer een commando alleen opnieuw als het herhalen veilig is.

Poolopties

Elke afzonderlijke verbindingsreeks krijgt zijn eigen pool. Voor poolsleutels, clearing en idle time, zie SQL Server connection pooling.

Opties voor transacties en sessies

.NET Framework alleen opties

Deze trefwoorden worden alleen geaccepteerd op .NET Framework. Op .NET gooit NotSupportedException de bouwer en SqlConnection gooit ArgumentException.

Niet-ondersteunde trefwoorden

Validatieregels

SqlConnectionStringBuilder Weigert onbekende trefwoorden en veel ongeldige waarden wanneer je ze instelt. SqlConnectionvoert meer controles uit wanneer je de verbindingsreeks instelt, inclusief enkele waarden die de builder accepteert en combinaties van trefwoorden. Een string die de builder accepteert kan nog steeds falen wanneer je de verbinding aanmaakt.

De bouwer en de verbinding verwerpen deze waarden met ArgumentException:

• Connect Timeout, Command Timeout, , , Connection Idle Timeout, of Min Pool SizeLoad Balance Timeoutminder dan 0.
• Max Pool Size minder dan 1.
• Packet Size buiten 512 tot en met 32.768.
• Connect Retry Count Buiten 0 tot 255.
• Connect Retry Interval Buiten 1 tot en met 60.
• Een trefwoord dat niet in dit artikel voorkomt.

SqlConnection verwerpt deze waarden ook met ArgumentException, ook al accepteert de bouwer ze:

• Type System Versionbehalve Latest, , , SQL Server 2008, of SQL Server 2005SQL Server 2012.
• Transaction Binding behalve Implicit Unbind of Explicit Unbind.
• Een waarde langer dan de TDS-limiet voor , , , , Failover PartnerInitial Catalog, Password, User ID, Workstation ID, of AttachDBFilename. Data SourceCurrent LanguageApplication Name

SqlConnection verwerpt deze combinaties ook met ArgumentException:

• Min Pool Size groter dan Max Pool Size.
• Failover Partner zonder Initial Catalog.
• Failover Partner met Multi Subnet Failover=true, User Instance=true, of Application Intent=ReadOnly.
• Authentication met Integrated Security=true.
• Password met Active Directory Integrated, Active Directory Interactive, , Active Directory Managed Identity, Active Directory MSI, Active Directory Default, , of Active Directory Workload Identity.
• User ID of Password met Active Directory Device Code Flow.

Wijzigingen in de optie bekijken

Voordat je een optie in productie verandert:

1. Noteer de huidige verbindingsreeks, de driverversie, het eindpunttype en het probleem dat je oplost.
2. Verander één optie tegelijk.
3. Test verbindingsopbouw, authenticatie, certificaatvalidatie, pooling, failover, annulering en het uitvoeren van query's.
4. Meet verbindingslatentie, poolwachttijden en foutgetallen.
5. Bevestig de instelling op elke gedeployeerde instantie.

Een gewijzigde verbindingsreeks creëert een nieuwe pool. Tijdens een gefaseerde uitrol bestaan oude en nieuwe pools tegelijkertijd, waardoor het totale aantal fysieke verbindingen met de server kan stijgen.

Verwante onderwerpen

• Verbindingsreeksen
• Opbouwfuncties voor verbindingsreeksen
• Verbind met een databron
• SQL Server verbindingspooling
• Versleuteling en certificaatvalidatie