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. Het biedt verbindingen, commando's, resultaatverwerking, transacties, bulkkopieën en SQL Server-specifieke functies aan .NET-applicaties.

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 een database te maken waarmee verbinding kan worden gemaakt, zie de vereisten in 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.

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 aansluit, zoals appsettings.json, omgevingsvariabelen, Azure App Configuration en Key Vault-ondersteunde instellingen. De configuratie combineert deze kenmerken:

• Transport Layer Security (TLS).
• Beheerde identiteit.
• Herstelvermogen van inactieve verbindingen.
• Initial-connect retry via configureerbare retry-logica (CRL), met gestructureerde logregistratie.
• Commando-niveau herpoging voor tijdelijke fouten die halverwege een query optreden.
• Snel herstel van de failovergroep.
• Asynchrone aanroepen die een annuleringstoken accepteren.

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.

Het fragment gaat uit van een project dat zich richt op .NET 8 of latere versies en verwijst naar de Microsoft.Data.SqlClient en Microsoft.Data.SqlClient.Extensions.Azure 7.1.1-pakketten. De host, zoals de .NET Generic Host of ASP.NET Core, levert de ILogger en de IConfiguration, en configuratie levert de servernaam in Sql:Server en de databasenaam in Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

De methode geeft de naam terug van de database waarmee hij is verbonden en logt Connected to database <database>. Wanneer er een herpoging plaatsvindt, wordt er ook één waarschuwing per herpoging geregistreerd, met de exceptie die dit heeft veroorzaakt.

Hoe elk deel van het fragment werkt:

• Doelitems: Elke SQL Database Engine-endpoint die 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-versleuteling. Het vereist SQL Server 2022 en latere versies, Azure SQL Database, Azure SQL Managed Instance, of SQL database in Microsoft Fabric. Gebruik SqlConnectionEncryptOption.Mandatory voor oudere servers.
• ActiveDirectoryManagedIdentity: Werkt alleen waar een beheerde identiteit beschikbaar is, zoals Azure App Service, Azure Functions of een Azure virtuele machine. Voor lokale ontwikkeling gebruik je SqlAuthenticationMethod.ActiveDirectoryDefault, dat de Azure CLI, Visual Studio-aanmelding en andere referentiebronnen probeert. Houd het uit productie omdat het onderzoeken van elke bron de verbinding vertraagt. Zie Standaardverificatie gebruiken voor meer informatie.
• MultiSubnetFailover = true: Probeert TCP-verbindingen parallel te maken met alle opgeloste IP-adressen en gebruikt de eerste verbinding die slaagt, waardoor de trage sequentiële per-IP-wandeling wordt vermeden. Stel het in voor Azure SQL Database, Azure SQL Managed Instance, SQL-database in Microsoft Fabric, availability group listeners en failover cluster instances. Het is veilig op doelen met één IP-adres. Het wordt niet ondersteund voor benoemde instanties, protocollen anders dan TCP, instanties met meer dan 64 IP-adressen, of de verouderde functie databasespiegeling. Gebruik in plaats daarvan AlwaysOn-beschikbaarheidsgroepen. Voor meer informatie, zie Hoge beschikbaarheid en disaster recovery en Het uitschakelen van transparante IP-resolutie van netwerk.
• ConnectRetryCount = 3 en ConnectRetryInterval = 10: Het stuurprogramma probeert tijdelijke storingen die hiervoor in aanmerking komen tijdens Open() opnieuw, en maakt bij de volgende opdracht opnieuw verbinding met een verbroken inactieve verbinding. Het standaardaantal is 1. Drie pogingen met telkens 10 seconden ertussen overbruggen een langere herconfiguratie of failover. De driver verhoogt 1 tot 2 alleen wanneer de servernaam eindigt in een bekend Azure SQL-domein, zoals .database.windows.net, waardoor een aangepaste DNS-alias 1 krijgt.
• openRetry: Toegevoegd aan SqlConnection.RetryLogicProvider, voegt het exponentiële backoff toe rond Open(). De driver stopt zijn interne herhalingen wanneer ConnectTimeout verloopt, dus het ergste geval voordat OpenAsync een fout geeft is vijf pogingen van maximaal 30 seconden elk, plus backoff. Elke idle reconnect-poging draait ook de volledige openRetry policy, en wanneer die policy zijn nieuwe pogingen uitput, eindigt idle recovery.
• Serverless auto-pauze: Voor Azure SQL Database serverless, verhoog ConnectTimeout naar minstens 60 seconden. De eerste Open() kan falen met een fout 40613 terwijl de database wordt hervat en openRetry het opnieuw probeert. Een client-side timeout verschijnt als fout -2, die niet opnieuw wordt geprobeerd, dus elke connectpoging moet langer duren dan de hervatting. Raadpleeg Automatisch onderbreken en automatisch hervatten voor meer informatie.
• commandRetry: Koppel het alleen aan SqlCommand.RetryLogicProvider wanneer het herhalen van het commando veilig is: reads, MERGE bewaakt door een natuurlijke sleutel, upserts door een opgeslagen procedure en andere idempotente bewerkingen. Het slaat herpogingen binnen een transactie over, dus applicatiecode moet multi-statement transacties opnieuw proberen. ExecuteReader en ExecuteScalar proberen alleen fouten opnieuw die zijn geretourneerd voordat de eerste resultatenset begint. ExecuteNonQuery probeert de hele aanroep opnieuw.
• Tijdelijke foutlijst: De instelling TransientErrors vervangt de ingebouwde lijst. Om het in plaats daarvan uit te breiden, gebruik je SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 en later).
• Retrying Gebeurtenis: Retrying wordt geactiveerd vóór elke nieuwe poging met het aantal nieuwe pogingen, de volgende vertraging en de uitzonderingen tot nu toe. Route het naar ILogger of je telemetriepijplijn.
• Uitzonderingen: De methode vangt geen uitzonderingen. Een uitgeputte provider gooit AggregateException met de uitzondering van elke poging. Een niet-tijdelijke fout wordt doorgegeven als de oorspronkelijke exceptie. De beller registreert het één keer met de rest van de verzoekcontext.
• Annuleren: Dit CancellationToken stopt het wachten van de provider tussen herhalingen. Het onderbreekt het wachten van de chauffeur binnen één enkele poging ConnectRetryIntervalOpen niet. Voor meer informatie, zie Asynchrone programmering.
• Levensduur van provider: Het fragment maakt de herkansingsproviders bij elke aanroep om op zichzelf staand te blijven. Maak ze één keer aan in een applicatie en gebruik ze opnieuw.

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

Leer de kerntaken voor data-toegang

Gebruik na het verbinden deze artikelen in volgorde:

1. Voer een commando uit om een resultvorm te kiezen en voer Transact-SQL (T-SQL) uit.
2. Configureer parameters zodat ze overeenkomen met het databasecontract.
3. Haal data op met SqlDataReader om rijen en meerdere resultaten te verwerken.
4. Pas data aan met opgeslagen procedures om outputparameters en retourwaarden te gebruiken.
5. Gebruik asynchrone programmering en annulering om annuleringen door de aanroeper en begrensde time-outs toe te voegen.
6. Behandel fouten en berichten voordat je nieuwe pogingen of productiediagnostiek toevoegt.

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 TDS 8.0-encryptie.
• 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.
• Verbindingspooling: Standaard aan. Een opt-in V2-pool is in evaluatie.
• 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.
• Applicatie-identiteit: Stel SqlConnection.RegisteredApplication in om uw bibliotheek of hulpprogramma te identificeren bij SQL Server (Microsoft.Data.SqlClient 7.1 en later).

Get started

Configureren en verbinding maken

Authenticeren en beveiligen

Gegevens ophalen en bijwerken

Gegevenstypen

Betrouwbaarheid en diagnostiek

SQL Server functies

Naslaginformatie en hulpmiddelen

Verzoeken om een functie toe te voegen

Om een functie aan te vragen, open je een issue in de Microsoft. Data.SqlClient GitHub-repository.

Verwante onderwerpen

• Microsoft. Data.SqlClient op GitHub
• Microsoft. Data.SqlClient op NuGet
• Opmerkingen bij de release
• ADO.NET overzicht
• Microsoft SQL-stuurprogramma’s en frameworks