Maak verbinding met een databron met Microsoft. Data.SqlClient

SqlConnectionvertegenwoordigt één logische verbinding met SQL Server, Azure SQL, of een ander ondersteund SQL Server-compatibel eindpunt. Bij het openen van het object wordt een fysieke verbinding uit de verbindingspool verkregen wanneer er een beschikbaar is. Het sluiten of weggooien ervan geeft die fysieke verbinding met het zwembad terug.

Gebruik kortstondige SqlConnection objecten als werkeenheden. Houd niet één globale verbinding open voor de applicatie.

Bouw de verbindingsconfiguratie

Laad een verbindingsreeks uit het configuratiesysteem van de applicatie. Gebruik SqlConnectionStringBuilder wanneer code instellingen moet valideren of toevoegen:

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

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

Maak de SqlConnection op basis van builder.ConnectionString. Koppel gebruikersinvoer niet aan de string. Voor authenticatiepatronen, veilige opslag en syntaxis, zie Verbindingsstrings.

Verbindingen openen en sluiten

Roep Open aan in synchrone code of OpenAsync in asynchrone code. Open een nieuwe logische verbinding voor elke onafhankelijke bewerking:

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

De await using verklaring verwijdert de verbinding bij succes, fout of annulering. Als pooling is ingeschakeld, wordt bij het vrijgeven de fysieke verbinding normaal gesproken gereset en aan de pool teruggegeven, in plaats van de netwerksocket af te sluiten.

Geef readers en opdrachten vrij vóór de verbinding waartoe ze behoren. Vertrouw niet op de afvalinzameling of een finalizer om verbindingen met het zwembad terug te geven.

Asynchrone API's gebruiken

Gebruik asynchrone aanroepen voor netwerkgebonden databasewerk in webservers, services, gebruikersinterfaces en workers:

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

Je hebt Asynchronous Processing=true niet nodig. Microsoft. Data.SqlClient 4.0 en latere versies ondersteunen dat verbindingsreeks-zoekwoord niet.

Start geen nieuwe bewerking op een verbinding, commando of lezer voordat de huidige asynchrone bewerking is voltooid.

Annuleren en time-outs toepassen

Geef de CancellationToken van de aanroeper door aan iedere asynchrone databaseaanroep. Annulering vraagt de aanbieder om het lopende werk te stoppen, maar de voltooiing is niet gegarandeerd direct. Blijf begrensde verbinding en commando-timeouts gebruiken.

Deze bedieningselementen hebben aparte scopes:

Een time-out of annulering bewijst niet dat de server een operatie heeft teruggedraaid. Gebruik een transactie wanneer meerdere wijzigingen als één geheel moeten worden doorgevoerd of teruggedraaid, en baseer beslissingen over nieuwe pogingen op de idempotentie en de uitkomst van de transactie van de bewerking.

Begrijp de verbindingstoestand

De State eigenschap geeft een momentopname terug uit de ConnectionState enumeratie.

Gebruik het niet State als gezondheidscheck voor elk commando. Het netwerk kan na elke controle falen. Voer de bewerking uit en behandel de resulterende uitzondering.

Het stuurprogramma meldt normaal gesproken overgangen van gesloten naar open en van open naar gesloten. Vertrouw niet op observatie Executing, Fetching, of Broken als fasen van de applicatielevenscyclus.

Het StateChange evenement rapporteert toestandsovergangen. Het InfoMessage evenement rapporteert informatieve berichten en serverwaarschuwingen die geen uitzonderingen worden. Gebruik deze gebeurtenissen voor diagnostiek, niet voor het coördineren van gelijktijdig werk.

Deel geen verbinding tegelijk

SqlConnection, SqlCommand, SqlDataReader, en SqlTransaction ondersteunen geen gelijktijdig gebruik door meerdere threads. Geef elke gelijktijdige bewerking een eigen verbinding en laat verbindingspooling de fysieke verbindingen hergebruiken.

Multiple Active Result Sets (MARS) staat meerdere actieve batches op één verbinding toe in ondersteunde scenario's. Het maakt SqlClient-objecten niet thread-veilig en voegt sessie- en transactieregels toe. Laat het uitgeschakeld tenzij één operatie het specifiek nodig heeft.

Registreer een open SqlConnection niet als singleton in dependency injection. Registreer de verbindingsreeks, een immutable options-object, of een fabriek die een nieuwe verbinding aanmaakt.

Gebruik transacties bewust

Een lokale transactie is gekoppeld aan de verbinding. Elk commando in de transactie moet die verbinding gebruiken en de eigenschap ervan Transaction instellen.

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

Als de operatie vóór CommitAsyncmislukt, wordt het verwijderen van de transactie teruggerold. Houd transacties kort. Doe geen netwerkoproepen, gebruikersinteractie of niet-gerelateerde berekeningen terwijl een databasetransactie vergrendeld is.

Wanneer System.Transactions.Transaction.Current actief is, worden Open en OpenAsync standaard automatisch geregistreerd. Stel alleen in Enlist=false wanneer de bewerking buiten de omringende transactie moet blijven.

Meet één logische verbinding

Zet StatisticsEnabled op true om leveranciersstatistieken voor één SqlConnection object te verzamelen:

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 geeft een snapshot terug. ResetStatistics start een nieuwe meetgrens. Ingesteld StatisticsEnabled=false op stoppen met verzamelen; tot nu toe verzamelde waarden blijven beschikbaar. Statistieken worden per verbindingsobject gebruikt en voegen overhead toe, dus maak ze mogelijk voor gerichte diagnose in plaats van elke productieverzoek.

Voor procesbrede pool- en verbindingsmetingen gebruik je SqlClient diagnostische tellers.

Verbindingsfouten afhandelen

Vang SqlException op aan een grens die de fout kan loggen, vertalen of opnieuw proberen. Record:

• Number
• State
• Class
• ClientConnectionId
• De bewerkingsnaam en geconfigureerde server- en database-identificaties

Leg de verbindingsreeks, het wachtwoord, het client secret of het toegangstoken niet vast.

Verwijder een verbroken verbinding. De pool verwijdert ongeldige fysieke verbindingen wanneer ze worden gedetecteerd. Als een credential, token, certificaat, DNS-doel of server is veranderd, corrigeer dan de configuratie voordat je het opnieuw probeert.

Gebruik begrensde herprobeerlogica alleen voor tijdelijke storingen. Opnieuw proberen bij het initiële openen, herstel van inactieve verbindingen en opnieuw proberen van opdrachten zijn verschillende mechanismen. Zie Configureerbare herpogingslogica.

Verwante onderwerpen

• Gebruik Microsoft. Data.SqlClient in een .NET-app
• Verbindingsreeksen
• Aansluitingsopties.
• SQL Server verbindingspooling
• Asynchrone programmering
• Transacties en gelijktijdigheid