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, SQL database in Microsoft Fabric en Warehouse 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

• Om een project op te zetten en je eerste query uit te voeren, begin je met Get Started with the SqlClient driver.
• Om de driver toe te voegen of bij te werken in een .NET-project, ga je naar Installeren, updaten en deployen Microsoft. Data.SqlClient.
• Om verbinding te maken met Azure SQL met wachtwoordloze authenticatie, begin je met Microsoft Entra-authenticatie- en Connection-strings.
• Om een bestaande applicatie bestand te maken tegen tijdelijke storingen, ga je naar Configureable retry logic en High availability and disaster recovery.
• Om grote datasets efficiënt te verplaatsen, ga je naar Bulk copy operations.
• Om te migreren vanSystem.Data.SqlClient, begin met Migreren van System.Data.SqlClient naar Microsoft. Data.SqlClient.
• Om een verbindings- of queryprobleem te diagnosticeren, ga naar de SqlClient probleemoplossingsgids en schakel eventbrontracering in.

Een database kiezen

Maak een database aan of maak verbinding met een bestaande database op een van de volgende platforms:

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
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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 gelden ConnectRetryInterval tijdens het initiële verbindingsherstel en het herstel van de idle verbinding. Wanneer ConnectRetryCount groter dan nul is, probeert de bestuurder opnieuw kwalificerende transiënte storingen tijdens Open(). Na Open() succes gebruikt de driver deze instellingen ook om een verbroken idle-verbinding opnieuw te verbinden bij het volgende commando. De openRetry aanbieder die is toegewezen voegt een SqlConnection.RetryLogicProvider configureerbaar exponentiële backoff-beleid toe rond Open(). Houd rekening met beide herpogingslagen wanneer je het aantal herpogingen en de verbindingstimeout instelt.

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:

• Verbindingsreeksen
• Microsoft Entra-authenticatie
• Versleuteling en certificaatvalidatie
• Configureerbare logica voor opnieuw proberen
• Hoge beschikbaarheid en herstel na noodgevallen

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

Configureren en verbinding maken

Authenticeren en beveiligen

Gegevens ophalen en bijwerken

Gegevenstypen

Betrouwbaarheid en diagnostiek

SQL Server functies

Naslaginformatie en hulpmiddelen

Verwante onderwerpen

• Microsoft. Data.SqlClient op GitHub
• Microsoft. Data.SqlClient op NuGet
• Opmerkingen bij de release
• ADO.NET overzicht
• Verbindingsmodules voor Microsoft SQL Database-