Koppla upp dig mot en datakälla med Microsoft. Data.SqlClient

SqlConnectionrepresenterar en logisk anslutning till SQL Server, Azure SQL eller en annan stödd SQL Server-kompatibel endpoint. När objektet öppnas får man en fysisk anslutning från anslutningspoolen när en sådan är tillgänglig. Att stänga eller göra sig av med den återställer den fysiska kopplingen till poolen.

Använd kortlivade SqlConnection objekt för arbetsenheter. Håll inte en global anslutning öppen för applikationen.

Skapa anslutningskonfigurationen

Ladda en reťazec pripojenia från applikationens konfigurationssystem. Använd SqlConnectionStringBuilder när koden behöver validera eller lägga till inställningar:

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

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

Skapa SqlConnection från builder.ConnectionString. Koppla inte ihop användarens inmatning i strängen. För autentiseringsmönster, säker lagring och syntax, se Anslutningssträngar.

Öppna och avlägsna anslutningar

Anropa Open i synkron kod eller OpenAsync i asynkron kod. Öppna en ny logisk anslutning för varje oberoende operation:

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

Uttalandet await using avslutar anslutningen vid framgång, fel eller avbokning. När poolning är aktiverat återställs den fysiska anslutningen normalt och återförs till poolen i stället för att dess nätverkssocket stängs.

Frigör dataläsare och kommandon före anslutningen som äger dem. Lita inte på sophämtning eller en finalizer för att återföra anslutningar till poolen.

Använd asynkrona API:er

Använd asynkrona anrop för nätverksbundet databasarbete i webbservrar, tjänster, användargränssnitt och arbetare:

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

Du behöver inte Asynchronous Processing=true. Microsoft. Data.SqlClient 4.0 och senare versioner stöder inte det nyckelordet reťazec pripojenia.

Starta inte en ny operation på en anslutning, ett kommando eller en läsare innan den nuvarande asynkrona operationen är klar.

Använd annullering och tidsgränser

Skicka anroparens anrop CancellationToken genom varje asynkront databasanrop. Avbokning kräver att vårdgivaren stoppar det pågående arbetet, men slutförandet är inte garanterat omedelbart. Fortsätt använda begränsade anslutnings- och kommandotimeouts.

Dessa kontroller har olika omfattningar:

Att en tidsgräns överskrids eller en annullering sker innebär inte att servern återställde en åtgärd. Använd en transaktion när flera ändringar måste genomföras eller återställas som en enhet, och fatta beslut om återförsök utifrån operationens idempotens och transaktionens utfall.

Förstå anslutningstillstånd

Egenskapen State returnerar en ögonblicksbild från uppräkningen ConnectionState .

Använd det inte State som hälsokontroll före varje kommando. Nätverket kan gå sönder efter vilken kontroll som helst. Utför operationen och hantera det resulterande undantaget.

Föraren rapporterar normalt övergångar från stängt till öppet och öppet till stängt. Förlita dig inte på att observera Executing, Fetching, eller Broken som applikationens livscykelfaser.

Händelsen StateChange rapporterar tillståndsövergångar. Händelsen InfoMessage rapporterar informationsmeddelanden och servervarningar som inte resulterar i undantag. Använd dessa händelser för diagnostik, inte för att samordna samtidigt arbete.

Dela inte en anslutning samtidigt

SqlConnection, SqlCommand, SqlDataReader, och SqlTransaction stöder inte samtidig användning av flera trådar. Ge varje samtidig operation en egen anslutning och låt anslutningspooling återanvända de fysiska kopplingarna.

Multiple Active Result Sets (MARS) tillåter flera aktiva batcher på en anslutning i stödda scenarier. Det gör inte SqlClient-objekt trådsäkra, och det lägger till sessions- och transaktionsregler. Låt den vara avstängd om inte en operation specifikt behöver det.

Registrera inte en öppen SqlConnection som singleton i dependensinjektion. Registrera en anslutningssträng, ett oföränderligt alternativobjekt eller en fabrik som skapar en ny anslutning.

Använd transaktioner medvetet

En lokal transaktion tillhör dess anslutning. Varje kommando i transaktionen måste använda den anslutningen och sätta dess Transaction egenskap.

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

Om operationen misslyckas före CommitAsync, rullas transaktionen tillbaka när transaktionen kasseras. Håll transaktionerna korta. Gör inte nätverkssamtal, användarinteraktion eller orelaterad beräkning medan en databastransaktion håller lås.

När System.Transactions.Transaction.Current är aktiv, Open och OpenAsync anmäler sig automatiskt som standard. Ställ in Enlist=false endast när operationen måste ligga utanför den omgivande transaktionen.

Mät en logisk koppling

Sätt StatisticsEnabled till true för att samla in leverantörsstatistik för ett objekt SqlConnection :

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 ger en ögonblicksbild. ResetStatistics påbörjar en ny mätgräns. Ställ StatisticsEnabled=false in på att sluta samla in; de insamlade värdena hittills är fortfarande tillgängliga. Statistik är per anslutningsobjekt och lägger till overhead, så aktivera dem för riktad diagnos istället för varje produktionsförfrågan.

För processövergripande pool- och anslutningsmätningar, använd SqlClient-diagnostiska räknare.

Hantera anslutningsfel

Fånga SqlException vid en gräns som kan logga, translatera eller försöka om felet. Post:

• Number
• State
• Class
• ClientConnectionId
• Operationsnamnet samt konfigurerade server- och databasidentifierare

Logga inte anslutningssträngen, lösenordet, klienthemligheten eller åtkomsttokenen.

Gör dig av med en trasig anslutning. Poolen tar bort ogiltiga fysiska anslutningar när den upptäcker dem. Om en legitimation, token, certifikat, DNS-mål eller server har ändrats, korrigera konfigurationen innan du försöker igen.

Använd begränsad återförsökslogik endast för tillfälliga fel. Återförsök vid initial öppning, återställning av overksamma anslutningar och återförsök av kommandon är olika mekanismer. Se Konfigurerbar återförsökslogik.

Relaterat innehåll

• Använd Microsoft. Data.SqlClient i en .NET-app
• Anslutningssträngar
• Anslutningsalternativ.
• SQL Server anslutningspoolning
• Asynkron programmering
• Transaktioner och samtidighet