Microsoft. Data.SqlClient voor SQL Server

ADO.NET downloaden

Microsoft. Data.SqlClient is de ondersteunde .NET-dataprovider voor SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics en SQL database in Microsoft Fabric. Het wordt gedistribueerd als een NuGet-pakket, evolueert onafhankelijk van de .NET-runtime en vervangt System.Data.SqlClient voor nieuwe ontwikkeling. Gebruik het om verbindingen te openen, commando's uit te voeren, resultaten te verwerken, transacties te beheren, data in bulk te laden en SQL Server-specifieke functies van .NET-applicaties te gebruiken.

Uw beginpunt kiezen

Productiebasislijn voor Azure SQL

Gebruik dit fragment als uitgangspunt voor een productiegerichte Azure SQL-datatoegangsroute. Het leest de server- en databasenamen uit IConfiguration, dus de waarden komen van de configuratieproviders die de host aanstuurt (appsettings.json, omgevingsvariabelen, Azure App Configuration, Key Vault-ondersteunde instellingen, enzovoort). De configuratie combineert Transport Layer Security (TLS), beheerde identiteit, veerkracht bij inactieve verbindingen, opnieuw proberen bij de eerste verbinding via configureerbare retry-logica (CRL) met gestructureerde logregistratie, opnieuw proberen op opdrachtniveau voor tijdelijke fouten die midden in een query optreden, en snel herstel van failovergroepen.

Voor hogere beveiliging en om configuratie over omgevingen heen te ondersteunen, houd de verbindingsinformatie buiten je code. In productie sla je verbindingsinformatie op in het configuratiesysteem van je applicatie en gebruik je Azure Key Vault voor gevoelige waarden. Zie Verbindingsgegevens beveiligenvoor meer informatie.

Het C#-fragment in dit artikel laat using richtlijnen en class wrappers weg voor de beknoptheid.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Dit fragment richt zich op elk SQL Database Engine-eindpunt dat is geconfigureerd voor Microsoft Entra-authenticatie: Azure SQL Database, Azure SQL Managed Instance, SQL database in Microsoft Fabric, en SQL Server 2022 en latere versies op Azure Virtuele Machines of ingeschakeld door Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict selecteert TDS 8.0-encryptie. Het vereist Microsoft. Data.SqlClient 5.0 en latere versies en een server die TDS 8.0 ondersteunt (SQL Server 2022 en latere versies, Azure SQL Database, Azure SQL Managed Instance en SQL database in Microsoft Fabric). Val terug op SqlConnectionEncryptOption.Mandatory wanneer je verbinding maakt met oudere servers.

ConnectRetryCount en ConnectRetryInterval activeren veerkracht van inactieve verbindingen: nadat Open() is geslaagd, herstelt het stuurprogramma transparant een verbroken inactieve verbinding bij de volgende opdracht. Ze proberen de eerste Open() niet opnieuw. Nieuwe pogingen voor de eerste verbinding zijn afkomstig van de provider die is toegewezen aan SqlConnection.RetryLogicProvideropenRetry. De twee kenmerken vullen elkaar aan.

De Retrying-gebeurtenis van elke provider wordt vóór elke nieuwe poging geactiveerd en bevat het aantal nieuwe pogingen, de vertraging vóór de volgende poging en de tot dan toe waargenomen excepties. Leid het naar ILogger of je telemetriepijplijn om de retrylus zichtbaar te houden in productie.

Stel in MultiSubnetFailover = true wanneer het doel Azure SQL Database, Azure SQL Managed Instance, SQL-database in Microsoft Fabric, een availability group listener of een failover-cluster instantie is. Het kiest een codepad voor parallelle verbindingen dat probeert TCP-verbindingen naar alle omgezette IP-adressen parallel tot stand te brengen en de eerste verbinding gebruikt die tot stand komt, zodat de trage sequentiële afhandeling per IP-adres wordt vermeden, waardoor die verbindingspogingen anders kunnen vastlopen. Bij single-IP-doelen is de instelling veilig. MultiSubnetFailover wordt niet ondersteund wanneer je verbinding maakt met een benoemde instantie, via een ander protocol dan TCP, of met een instantie die is geconfigureerd met meer dan 64 IP-adressen. Je kunt het ook niet gebruiken met databasemirroring, dat in alle ondersteunde versies van SQL Server verouderd is. Gebruik in plaats daarvan AlwaysOn-beschikbaarheidsgroepen. Voor meer informatie, zie Hoge beschikbaarheid en disaster recovery en Het uitschakelen van transparante IP-resolutie van netwerk.

Als het doel Azure SQL Database serverloos is met auto-pauze ingeschakeld, verhoog ConnectTimeout dan naar minstens 60 seconden. Een automatisch gepauzeerde database wordt hervat bij de eerste Open(), en die eerste Open() kan mislukken met fout 40613 terwijl de database wordt hervat. De fout staat in de ingebouwde lijst met tijdelijke fouten, dus openRetry probeer 40613 het opnieuw. Time-outs aan de clientzijde uiten zich als fout -2, die niet in die lijst staat, dus openRetry redt een Open() niet die tijdens het hervatten een time-out krijgt. De afzonderlijke verbindingspoging moet lang genoeg duren om de hervatting te kunnen voltooien. Raadpleeg Automatisch onderbreken en automatisch hervatten voor meer informatie.

Op commandoniveau wordt opnieuw proberen door de aanroeper bepaald, voor elk commando afzonderlijk. Koppel commandRetry alleen aan SqlCommand.RetryLogicProvider wanneer het herhalen van het commando veilig is: reads, MERGE bewaakt door een natuurlijke sleutel, upserts via een opgeslagen procedure, en andere idempotente bewerkingen. De ingebouwde commandoprovider slaat herpoging over wanneer een transactie actief is, dus multi-statement transacties moeten opnieuw worden geprobeerd door applicatiecode die de transactie opnieuw kan openen. Instellen TransientErrors vervangt de ingebouwde foutenlijst van de driver; om de ingebouwde basislijn uit te breiden, gebruik SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 en later).

Zie voor meer informatie over elk onderdeel van deze configuratie:

Belangrijkste kenmerken

  • Moderne .NET-ondersteuning: Draait op de huidige .NET- en .NET Framework-versies. Raadpleeg voor de uitsplitsing per versie ondersteuningslevenscyclus.
  • Versleuteld standaard: TLS-versleutelde verbindingen met Encrypt=true als standaard. Stel Encrypt=Strict in voor versleuteling met TDS 8.0 in Microsoft.Data.SqlClient 5.0 en hoger.
  • Microsoft Entra ID-authenticatie: wachtwoordloze verbindingen met beheerde identiteit, service-principal, interactieve, geïntegreerde, standaardketen van aanmeldingsgegevens en toegangstokenstromen.
  • Kerberos en NTLM: Geïntegreerde Windows-verificatie voor on-premises-Active Directory en legacy-scenario's.
  • Always Encrypted: Versleuteling aan de clientzijde voor gevoelige kolommen, met optionele beveiligde enclaves voor in-place bewerkingen.
  • Bulkkopie: Invoegsels met hoge doorvoer en SqlBulkCopy.
  • Verbindingsveerkracht: Ingebouwde verbindingsherhalingen (ConnectRetryCount en ConnectRetryInterval) plus opt-in configureerbare herpogingslogica voor verbindingen en commando's.
  • Uitgebreide SQL Server-datatypes: datetimeoffset, sql_variant, JSON, vectoren, ruimtelijke typen, XML en tabelparameters.
  • Diagnostiek: Gebeurtenisbrontracering, diagnostische tellers, zorgverlenerstatistieken en een speciale handleiding voor probleemoplossing.

Get started

Artikel Description
Aan de slag met het SqlClient-stuurprogramma Stel een project op, maak een database, verbind, zoek op en voeg verbindingsveerkracht toe.
Overzicht van het SqlClient-stuurprogramma Leer hoe Microsoft.Data.SqlClient binnen ADO.NET past.
Download Microsoft. Data.SqlClient Installeer het NuGet-pakket en zoek bronversies.
Ondersteuningslevenscyclus Bekijk de ondersteunde driverversies en ondersteuningsdata.
Microsoft. Data.SqlClient-naamruimte Migrer van System.Data.SqlClient en bekijk de verschillen in naamruimtes.

Configureren en verbinding maken

Artikel Description
Verbind met een databron Open en beheer verbindingen met SQL Server en Azure SQL.
Verbindingsreeksen Configureer server-, database-, authenticatie-, encryptie- en verbindingsgedrag.
Versleuteling en certificaatvalidatie Configureer versleutelde verbindingen en validatie van servercertificaten.
SQL Server verbindingspooling Hergebruik fysieke verbindingen efficiënt.
Verbindingsevenementen Reageer op verbindingsstatus- en informatieberichten.

Authenticeren en beveiligen

Artikel Description
SQL Server-beveiliging Bekijk authenticatie-, autorisatie- en applicatiebeveiligingsrichtlijnen.
Microsoft Entra-authenticatie Maak verbinding met beheerde identiteit, service principal, wachtwoord en interactieve stromen.
Bescherm verbindingsinformatie Houd inloggegevens en verbindingsinstellingen buiten de applicatiecode.
Altijd versleuteld Bescherm gevoelige kolomwaarden van het databasesysteem.
Always Encrypted met beveiligde enclaves Voer rijke bewerkingen uit op versleutelde data met een veilige enclave.

Gegevens ophalen en bijwerken

Artikel Description
Opdrachten en parameters Voer geparametriseerde SQL-statements en opgeslagen procedures uit.
DataAdapters en DataReaders Stream resultaatsets of vul niet-verbonden datastructuren in.
Transacties en gelijktijdigheid Gebruik lokale en verspreide transacties en gelijktijdigheidscontroles.
Haal databaseschema-informatie op Ontdek schema-verzamelingen en beperkingen.
Bewerkingen voor bulkkopiëren Laad grote datasets efficiënt met SqlBulkCopy.
Parameters met tabelwaarde Stuur meerdere rijen naar een geparametriseerde instructie of opgeslagen procedure.
Asynchrone programmering Gebruik asynchrone verbindings-, commando- en databewerkingen.
Meerdere actieve resultatensets (MARS) Verwerk meerdere batches afwisselend via één verbinding.

Gegevenstypen

Artikel Description
ADO.NET-toewijzingen van gegevenstypen Koppel veelvoorkomende taal-runtimetypes aan provider- en SQL Server-types.
SQL Server datatypen Werk met SQL Server-specifieke waarden en System.Data.SqlTypes types.
JSON-gegevens Stuur en haal het SQL Server-datatype json op.
Vectorgegevens Verzend en haal vectorwaarden op.
XML-gegevens Lees, schrijf en parametriseer XML-waarden.
Binaire en grootwaardegegevens Binaire gegevens, FILESTREAM-gegevens en gegevens met grote waarden streamen en bijwerken.

Betrouwbaarheid en diagnostiek

Artikel Description
Configureerbare logica voor opnieuw proberen Probeer tijdelijke verbindings- en opdrachtfouten opnieuw met beleid met limieten.
Hoge beschikbaarheid en herstel na noodgevallen Verbind met luisteraars van de beschikbaarheidsgroep en failoverpartners.
Diagnostische tellers Monitor actieve verbindingen, gepoolde verbindingen en andere driver-metrics.
Schakel tracering van gebeurtenisbronnen in Leg gedetailleerde bestuurdersgebeurtenissen vast voor diagnose.
Datatracing Volg ADO.NET-operaties en gegevenstoegang.
Probleemoplossingsgids voor SqlClient Diagnoseer veelvoorkomende verbindings- en driverproblemen.
Querymeldingen Ontvang meldingen wanneer zoekresultaten veranderen.

SQL Server functies

Artikel Description
SQL Server-functies en ADO.NET Bekijk SQL Server-specifieke functies die beschikbaar zijn via SqlClient.
LocalDB Verbind met SQL Server Express LocalDB-instanties.
Gegevensdetectie en -classificatie Lees gevoeligheidsclassificatiemetadata uit resultatensets.

Naslaginformatie en hulpmiddelen

Artikel Description
Microsoft. Data.SqlClient API-referentie Bekijk de .NET API-referentie voor de driver.
AppContext-schakelaars Configureer compatibiliteit en beveiligingsgedrag.
Vind aanvullende SqlClient-informatie Vind broncode, ondersteuning en communitybronnen.

Verwante onderwerpen

  • Last updated on