Připojte se ke zdroji dat s Microsoft. Data.SqlClient

SqlConnectionpředstavuje jedno logické spojení se SQL Server, Azure SQL nebo jiným podporovaným koncovým zařízením kompatibilním se SQL Server. Otevřením objektu se získá fyzické spojení z poolu, pokud je k dispozici. Jeho zavřením nebo uvolněním je toto fyzické připojení vráceno do poolu.

Používejte krátkodobé objekty SqlConnection jako jednotky práce. Nenechávejte otevřené jedno globální připojení pro aplikaci.

Sestavte konfiguraci spojení

Načte připojovací řetězec z konfiguračního systému aplikace. Použijte SqlConnectionStringBuilder , když je potřeba kód ověřit nebo přidat nastavení:

string configuredConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(configuredConnectionString)
{
    ApplicationName = "Orders.Api",
};

Vytvořte SqlConnection z builder.ConnectionString. Nespojujte uživatelský vstup do řetězce. Pro autentizační vzory, bezpečné úložiště a syntaxi viz Connection strings.

Otevřete a zlikvidujte spojení

V synchronním kódu volejte Open, v asynchronním kódu OpenAsync. Otevřete nové logické spojení pro každou nezávislou operaci:

public static async Task<string?> LoadOrderStatusAsync(
    string connectionString,
    int orderId,
    CancellationToken cancellationToken)
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellationToken);

    const string sql = """
        SELECT Status
        FROM Sales.Orders
        WHERE OrderId = @orderId;
        """;

    using var command =
        new SqlCommand(sql, connection) { CommandTimeout = 30 };
    command.Parameters.Add(
        new SqlParameter("@orderId", SqlDbType.Int) { Value = orderId });

    object? value =
        await command.ExecuteScalarAsync(cancellationToken);
    return value is null or DBNull ? null : (string)value;
}

Příkaz await using uvolní připojení při úspěchu, chybě nebo zrušení. Při zapnutí poolování se likvidace obvykle resetuje a fyzické připojení se obnoví místo uzavření síťové zásuvky.

Zbav se čtenářů a příkazů před spojením, které je vlastní. Nespoléhejte na sběr odpadu nebo finalizér pro návrat spojení do poolu.

Použití asynchronních rozhraní API

Používejte asynchronní volání pro práci s databázemi vázanými na síti na webových serverech, službách, uživatelských rozhraních a pracovnících:

  • OpenAsync(cancellationToken)
  • ExecuteNonQueryAsync(cancellationToken)
  • ExecuteReaderAsync(cancellationToken)
  • ExecuteScalarAsync(cancellationToken)
  • ReadAsync(cancellationToken)

Nepotřebujete Asynchronous Processing=true. Microsoft. Data.SqlClient 4.0 a novější verze nepodporují toto klíčové slovo připojovací řetězec.

Nespouštějte další operaci na spojení, příkazu nebo čtečce dříve, než skončí aktuální asynchronní operace.

Uplatněte zrušení a časové limity

Pošlete volající CancellationToken přes každý asynchronní databázový hovor. Zrušení žádá poskytovatele, aby zastavil probíhající práce, ale dokončení není zaručeno okamžité. Pokračujte v používání omezených časových limitů spojení a příkazů.

Tyto ovládací prvky mají samostatné rozsahy:

Ovládací prvek Scope
Connect Timeout Navázání spojení nebo čekání na spojení do skupiny
SqlCommand.CommandTimeout Provedení jednoho příkazu
CancellationToken Zrušení asynchronní operace na žádost volajícího

Vypršení časového limitu nebo zrušení neznamená, že server vrátil operaci zpět. Použijte transakci, když se musí více změn potvrdit nebo vrátit zpět jako jedna jednotka, a o opakování operace rozhodujte na základě její idempotence a výsledku transakce.

Pochopení stavu spojení

Vlastnost State vrací snímek z ConnectionState výčtu.

Kraj Meaning
Closed Logické spojení není otevřené.
Connecting Probíhá otevřená operace.
Open Logické spojení je otevřené.

Nepoužívejte State jako kontrolu stavu před každým příkazem. Síť může selhat po jakékoli kontrole. Proveďte operaci a zpracujte vzniklou výjimku.

Ovladač obvykle hlásí přechody z uzavřeného do otevřeného a z otevřeného do uzavřeného stavu. Nespoléhejte na pozorování Executing, Fetching, ani Broken jako fáze životního cyklu aplikace.

StateChange událost hlásí přechody stavů. Událost InfoMessage oznamuje informační zprávy a varování serveru, které se neprojeví jako výjimky. Tyto události používejte k diagnostice, ne k koordinaci souběžné práce.

Nesdílejte spojení současně

SqlConnection, SqlCommand, SqlDataReader, a SqlTransaction nepodporují současné použití více vláken. Každé souběžné operaci přiřaďte vlastní připojení a nechte sdružování připojení opakovaně využívat fyzická připojení.

Multiple Active Result Sets (MARS) umožňuje více aktivních dávek na jednom připojení v podporovaných scénářích. Nedělá to objekty SqlClient bezpečnými pro vlákna a přidává pravidla pro relace a transakce. Nechte to vypnuté, pokud to některá operace výslovně nevyžaduje.

Neregistrujte otevřenou službu SqlConnection jako singleton ve vkládání závislostí. Zaregistrujte připojovací řetězec, neměnný objekt možností nebo továrnu, která vytváří nové připojení.

Používejte transakce záměrně

Lokální transakce je vázána na své připojení. Každý příkaz v transakci musí toto spojení použít a nastavit jeho Transaction vlastnost.

await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync(cancellationToken);

await using SqlTransaction transaction =
    (SqlTransaction)await connection.BeginTransactionAsync(cancellationToken);

using var command = new SqlCommand(sql, connection, transaction);
command.Parameters.Add(
    new SqlParameter("@value", SqlDbType.Int) { Value = value });
await command.ExecuteNonQueryAsync(cancellationToken);

await transaction.CommitAsync(cancellationToken);

Pokud operace selže před CommitAsync, likvidace transakce ji vrátí zpět. Udržujte transakce krátké. Nedělejte síťové hovory, interakce s uživateli ani nesouvisející výpočty, dokud transakce v databázi drží zámky.

Když je System.Transactions.Transaction.Current aktivní, OpenAsync a Open se ve výchozím nastavení automaticky zaregistrují. Nastavte Enlist=false pouze tehdy, když operace musí zůstat mimo okolní transakci.

Změřte jedno logické spojení

Nastavte StatisticsEnabled na true sběr statistik poskytovatele pro jeden SqlConnection objekt:

await using var connection = new SqlConnection(connectionString)
{
    StatisticsEnabled = true,
};

await connection.OpenAsync(cancellationToken);
connection.ResetStatistics();

using var command = new SqlCommand(sql, connection);
await command.ExecuteNonQueryAsync(cancellationToken);

System.Collections.IDictionary statistics =
    connection.RetrieveStatistics();
long roundTrips =
    Convert.ToInt64(statistics["ServerRoundtrips"]);

RetrieveStatistics vrátí snímek. ResetStatistics označuje začátek nové hranice měření. Nastaveno StatisticsEnabled=false na zastavení sběru; hodnoty získané dosud zůstávají dostupné. Statistiky se vztahují ke každému objektu připojení a zvyšují režii, takže je povolujte pro cílenou diagnostiku, nikoli u každého produkčního požadavku.

Pro měření celých procesů poolu a připojení použijte diagnostické čítače SqlClient.

Řešení chyb připojení

Zachyťte SqlException na rozhraní, které může selhání zaznamenat, transformovat nebo opakovat. Záznam:

  • Number
  • State
  • Class
  • ClientConnectionId
  • Název operace a konfigurované identifikátory serverů a databází

Nezaznamenávejte připojovací řetězec, heslo, klientské tajemství ani access token.

Zlikvidujte přerušené spojení. Pool odstraní neplatné fyzické spojení, když je detekuje. Pokud se změní přihlašovací údaje, token, certifikát, DNS cíl nebo server, opravte konfiguraci před dalším pokusem.

Používejte omezenou logiku opakovaných pokusů pouze pro přechodné selhání. Opakování při počátečním otevření, obnovení nečinného připojení a opakování příkazu jsou různé mechanismy. Viz Konfigurovatelná logika opakovaných pokusů.

Související obsah

  • Last updated on