Opcje połączenia dla Microsoft. Data.SqlClient

Ten artykuł zawiera wszystkie słowa kluczowe parametry połączenia, które akceptuje Microsoft. Data.SqlClient. Każde słowo kluczowe ma również właściwość dopasowania SqlConnectionStringBuilder . Wstęp, wspólne wzorce i reguły parsowania można znaleźć w sekcji Strings Connection.

Słowa kluczowe i aliasy nie są rozróżniane na wielka literę. Gdy ustawiasz wartość przez nieruchomość budowniczego, deweloper wpisuje kanoniczne słowo kluczowe w kolumnie Słowo Kluczowe .

Ustaw opcje za pomocą SqlConnectionStringBuilder

Zacznij od podstawowego parametry połączenia, który zawiera serwer, bazę danych i ustawienia uwierzytelniania. Następnie ustaw opcje specyficzne dla obciążenia przez właściwości buildera. Zakładki .NET Framework używają C# 7.3. Aby stworzyć projekt, który uruchamia próbki, zobacz Utwórz projekt.

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

Dane wyjściowe to:

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

Nowy SqlCommand pobiera domyślny czas od Command Timeout słowa kluczowego swojego połączenia.

Sprawdź wartości domyślne

Nowy SqlConnectionStringBuilder raportuje domyślne ustawienia dla każdej opcji. Ten program drukuje domyślne dane, które większość aplikacji przegląda:

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

W .NET wyjście to:

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 to Mandatory opcja. W .NET Framework domyślna nazwa aplikacji to Framework Microsoft SqlClient Dostawca danych.

Opcje serwera i bazy danych

Opcje tożsamości aplikacji

Aby zgłosić, który framework lub narzędzie otworzyło połączenie, użyj RegisteredApplication tej właściwości. Nie ma słowa kluczowego parametry połączenia. Więcej informacji można znaleźć w artykule Zgłoś tożsamość aplikacji.

Opcje uwierzytelniania

Authentication akceptuje te wartości. Budownik zapisuje je bez spacji, takich jak ActiveDirectoryDefault, a parser akceptuje obie formy.

Metody Microsoft Entra ID wymagają pakietuMicrosoft.Data.SqlClient.Extensions.Azure. Aby uzyskać informacje o konfiguracji i przykładach, zobacz uwierzytelnianie Microsoft Entra ID oraz uwierzytelnianie SQL Server.

Opcje szyfrowania

Pełne reguły walidacji można znaleźć w artykule Szyfrowanie i walidacja certyfikatów.

Opcje zawsze szyfrowane

Opcje sieciowe

Przełącznik AppContext obejmujący cały proces może zmienić domyślne Multi Subnet Failover na .true Więcej informacji można znaleźć w artykule przełączniki AppContext w SqlClient.

Opcje timeoutu

Connect Timeout Nie ogranicza wykonywania zapytań. Command Timeout Nie ogranicza logowania ani oczekiwania na połączenie w grupie. Przekaż na połączenia asynchroniczne CancellationToken , aby dzwoniący mógł przestać czekać przed wygaśnięciem któregokolwiek z czasów.

Opcje odzyskiwania połączenia

Gdy Connect Retry Count jest 1, co jest domyślne, sterownik używa 2 dla punktów końcowych Azure SQL oraz 5 dla serwerowych punktów puli SQL bez serwera w Azure Synapse Analytics, gdy przywraca zerwane połączenie bezczynnościowe. Pierwsze otwarcie używa wartości ustawionej, więc domyślnie pozwala na ponowną próbę na każdym końcu końcowym. Sterownik używa dowolnej innej wartości ustawionej w obu przypadkach.

Te słowa kluczowe nie ponawiają polecenia, które zakończy się niepowodzeniem podczas wykonywania. Aby pominąć wbudowaną próbę powtórną dla jednego otwarcia, wywołaj Open przeciążenie z OpenWithoutRetry. Polityki niestandardowe znajdziesz w artykule Konfigurowalna logika powtórek. Powtórz polecenie tylko wtedy, gdy powtórzenie jest bezpieczne.

Opcje łączenia

Każdy odrębny parametry połączenia ma własną pulę. Dla kluczy puli, czyszczenia i czasu bezczynności, zobacz SQL Server pool połączeń.

Opcje transakcyjne i sesyjne

Opcje tylko w .NET Framework

Te słowa kluczowe są akceptowane wyłącznie w .NET Framework. Na .NET budowniczor rzuca i SqlConnection rzucaNotSupportedException.ArgumentException

Nieobsługiwane słowa kluczowe

Reguły walidacji

SqlConnectionStringBuilder Odrzuca nieznane słowa kluczowe i wiele nieprawidłowych wartości, gdy je ustawisz. SqlConnectionWykonuje więcej kontroli, gdy ustawiasz parametry połączenia, w tym pojedyncze wartości akceptowane przez kreator oraz kombinacje słów kluczowych. Ciąg znaków, który deweloper zaakceptuje, może nadal zawiódć po utworzeniu połączenia.

Budowniczy i połączenie odrzucają te wartości z :ArgumentException

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, lub Min Pool Size mniej niż 0.
• Max Pool Size mniej niż 1.
• Packet Size poza 512 do 32 768.
• Connect Retry Count poza 0 do 255.
• Connect Retry Interval na zewnątrz od 1 do 60.
• To słowo kluczowe, którego nie ma w tym artykule.

SqlConnection odrzuca także te wartości z ArgumentException, mimo że budowniczy je akceptuje:

• Type System Version poza Latest, SQL Server 2012, SQL Server 2008, lub SQL Server 2005.
• Transaction Binding poza Implicit Unbind lub Explicit Unbind.
• Wartość dłuższa niż limit TDS dla Application Name, Current Language, Data Source, Failover PartnerInitial Catalog, , Password, User ID, , Workstation ID, lub AttachDBFilename.

SqlConnection odrzuca także te kombinacje z ArgumentException:

• Min Pool Size większe niż Max Pool Size.
• Failover Partner bez Initial Catalog.
• Failover Partner z Multi Subnet Failover=true, User Instance=true, lub Application Intent=ReadOnly.
• Authentication za pomocą Integrated Security=true.
• Password z Active Directory Integrated, Active Directory Interactive, Active Directory Managed Identity, Active Directory MSI, , Active Directory Defaultlub Active Directory Workload Identity.
• User IDlub Password z .Active Directory Device Code Flow

Przejrzyj zmiany opcji

Zanim zmienisz opcję w produkcji:

1. Zanotuj aktualny parametry połączenia, wersję sterownika, typ endpointu oraz rozwiązany problem.
2. Zmieniaj jedną opcję na raz.
3. Testuj nawiązywanie połączenia, uwierzytelnianie, walidację certyfikatów, pulowanie, przełączanie awaryjne, anulowanie oraz wykonywanie zapytań.
4. Mierz opóźnienia połączenia, oczekiwania na pulę i liczby błędów.
5. Potwierdź to ustawienie na każdej wdrożonej instancji.

Zmieniony parametry połączenia tworzy nową pulę. Podczas etapowego wdrażania istnieją jednocześnie stare i nowe pule, więc łączna liczba fizycznych połączeń z serwerem może rosnąć.

Treści powiązane

• Parametry połączenia
• Konstruktorzy parametrów połączenia
• Połącz się ze źródłem danych
• SQL Server connection pooling
• Szyfrowanie i walidacja certyfikatów