Microsoft. Data.SqlClient för SQL Server

Ladda ned ADO.NET

Microsoft. Data.SqlClient är den stödda .NET-dataleverantören för SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL Database in Microsoft Fabric och Warehouse i Microsoft Fabric. Det distribueras som ett NuGet-paket, utvecklas oberoende av .NET-runtimen och ersätter System.Data.SqlClient för ny utveckling. Använd den för att öppna anslutningar, utföra kommandon, bearbeta resultat, hantera transaktioner, ladda in data i bulk och använda SQL Server-specifika funktioner från .NET-applikationer.

Välj startpunkt

Produktionsbaslinje för Azure SQL

Använd detta utdrag som utgångspunkt för en produktionsorienterad Azure SQL-dataåtkomstväg. Den läser server- och databasnamnen från IConfiguration, så värdena kommer från de konfigurationsleverantörer som värden konfigurerar, såsom appsettings.json, miljövariabler, Azure App Configuration och Key Vault-stödda inställningar. Konfigurationen kombinerar dessa funktioner:

  • Transport Layer Security (TLS).
  • Hanterad identitet.
  • Inaktiva anslutningars motståndskraft.
  • Försök till inledande anslutning via konfigurerbar återförsökslogik (CRL), med strukturerad loggning.
  • Omförsök på kommandonivå för tillfälliga fel som uppstår under en pågående fråga.
  • Snabb återställning av failover group.
  • Asynkrona anrop som tar en avbrottstoken.

För högre säkerhet och för att stödja konfiguration över miljöer, håll anslutningsinformationen utanför din kod. I produktion, lagra anslutningsinformation i applikationens konfigurationssystem och använd Azure Key Vault för känsliga värden. Mer information finns i Skydda anslutningsinformation.

C#-utdraget i denna artikel utelämnar using direktiv och klassomslag för korthetens skull.

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

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

Detta kodfragment riktar sig till valfri SQL Database Engine-slutpunkt som har konfigurerats för Microsoft Entra-autentisering: Azure SQL Database, Azure SQL Managed Instance, SQL Database i Microsoft Fabric och SQL Server 2022 och senare versioner på virtuella Azure-datorer eller som aktiverats med Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict väljer TDS 8.0-kryptering. Det kräver Microsoft. Data.SqlClient 5.0 och senare versioner samt en server som stödjer TDS 8.0 (SQL Server 2022 och senare versioner, Azure SQL Database, Azure SQL Managed Instance och SQL database i Microsoft Fabric). Gå tillbaka till SqlConnectionEncryptOption.Mandatory när du ansluter till äldre servrar.

ConnectRetryCount och ConnectRetryInterval gäller vid initial anslutningsetablering och återställning av inaktiva anslutningar. När ConnectRetryCount är större än noll försöker föraren om kvalificera transientfel under Open(). När Open() har lyckats använder drivrutinen också dessa inställningar för att återansluta en bruten inaktiv anslutning vid nästa kommando. Den openRetry leverantör som tilldelats SqlConnection.RetryLogicProvider lägger till en konfigurerbar exponentiell backoff-policy runt Open(). Ta hänsyn till båda lagren för omförsök när du ställer in antalet omförsök och timeout för anslutningen. Drivrutinen avbryter sina interna återförsök när ConnectTimeout går ut, så varje leverantörsförsök tar högst några ConnectTimeout sekunder. Med dessa värden är det värsta scenariot innan OpenAsync kastar ett undantag fem försök på upp till 30 sekunder vardera, plus leverantörens backoff-fördröjningar.

Snippet skapar återförsöksleverantörerna vid varje anrop för att hålla exemplet fristående. I en applikation skapar du dem en gång och återanvänder dem för varje anslutning och kommando. Metoden fångar inga undantag. När leverantörerna har uttömt sina omförsök eller stött på ett icke-övergående fel, propageras undantaget till anroparen, som loggar det en gång tillsammans med resten av begärans kontext. När en leverantör uttömmer sina återförsök kastar den AggregateException, som innehåller undantaget från varje försök. Ett bestående fel propagerar som det ursprungliga undantaget.

Snipet använder de asynkrona metoderna och skickar med en CancellationToken. Avbokning stoppar leverantörens väntan mellan återförsöken. Det avbryter inte förarens egen ConnectRetryInterval väntan inom ett enskilt Open försök. För mer information, se Asynkron programmering.

ActiveDirectoryManagedIdentityfungerar endast där en hanterad identitet är tillgänglig, såsom Azure App Service, Azure Functions eller en virtuell Azure-maskin. För lokal utveckling, använd SqlAuthenticationMethod.ActiveDirectoryDefault, som försöker flera källor för autentiseringsuppgifter, inklusive Azure CLI och Visual Studio-inloggning. Håll ActiveDirectoryDefault borta från produktion eftersom avsökning av varje autentiseringsuppgiftskälla saktar ned anslutningen. För mer information, se Använd standardautentisering.

Händelsen Retrying hos varje provider utlöses före varje återförsök och innehåller antalet återförsök, fördröjningen före nästa försök och de undantag som har observerats hittills. Dirigera den till ILogger eller din telemetripipeline för att hålla omförsöksslingan synlig i produktion.

Sätt MultiSubnetFailover = true när målet är Azure SQL Database, Azure SQL Managed Instance, SQL-databas i Microsoft Fabric, en tillgänglighetsgruppslyssnare eller en failover-klusterinstans. Den väljer en kodväg för parallella anslutningar som försöker upprätta TCP-anslutningar till alla matchande IP-adresser parallellt och använder den första som lyckas, vilket undviker den långsamma sekventiella genomgången av IP-adresserna en i taget som annars kan fördröja anslutningarna. För mål med en enda IP-adress är inställningen säker. MultiSubnetFailover stöds inte när du ansluter till en namngiven instans, via ett annat protokoll än TCP, eller till en instans konfigurerad med fler än 64 IP-adresser. Du kan inte heller använda det med databasspegling, som är föråldrad i alla stödda versioner av SQL Server. Använd AlwaysOn-tillgänglighetsgrupper i stället. För mer information, se Hög tillgänglighet och katastrofåterställning samt Inaktivera transparent IP-upplösning i nätverket.

Om målet är Azure SQL Database serverless med autopaus aktiverat, höj ConnectTimeout till minst 60 sekunder. En automatiskt pausad databas återaktiveras vid den första Open(), och den första Open() kan misslyckas med fel 40613 medan databasen återaktiveras. Felet 40613 finns i den inbyggda listan över övergående fel, så openRetry försök igen. Tidsgränser på klientsidan yttrar sig som felet -2, som inte finns med i den listan, så openRetry inte räddar ett Open() som överskrider tidsgränsen mitt under återupptagningen. Försöket till individuell kontakt måste vara tillräckligt långt för att täcka CV:t. Mer information finns i Automatisk paus och automatisk återupptagning.

Återförsök på kommandonivå avgörs av anroparen för varje kommando. Knyt commandRetry till SqlCommand.RetryLogicProvider endast när det är säkert att köra kommandot igen: läsningar, MERGE skyddade av en naturlig nyckel, upserts via en lagrad procedur och andra idempotenta operationer. Den inbyggda kommandoleverantören hoppar över återförsök när en transaktion är aktiv, så flersats-transaktioner måste försökas om av applikationskod som kan öppna transaktionen igen. Inställning TransientErrors ersätter drivrutinens inbyggda fellista; för att utöka den inbyggda baslinjen istället, använd SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 och senare).

Mer information om varje del av den här konfigurationen finns i:

Lär dig de centrala aktiviteterna för dataåtkomst

Efter att du har anslutit, använd dessa artiklar i ordning:

  1. Kör ett kommando för att välja en resultatform och kör Transact-SQL (T-SQL).
  2. Konfigurera parametrar för att matcha databaskontraktet.
  3. Hämta data med SqlDataReader för att bearbeta rader och flera resultat.
  4. Modifiera data med lagrade procedurer för att använda utdataparametrar och returnera värden.
  5. Använd asynkron programmering och avbrytning för att lägga till avbrytning av anrop och begränsade tidsgränser.
  6. Hantera fel och meddelanden innan du lägger till omförsök eller produktionsdiagnostik.

Viktiga funktioner

  • Modern .NET-stöd: Körs på nuvarande versioner av .NET och .NET Framework. För uppdelningen per version, se Supportlivscykel.
  • Krypterade som standard: TLS-krypterade anslutningar med Encrypt=true som standard. Ange Encrypt=Strict för TDS 8.0-kryptering i Microsoft.Data.SqlClient 5.0 och senare.
  • Autentisering med Microsoft Entra ID: Lösenordslösa anslutningar med hanterad identitet, tjänsthuvudnamn, interaktiva, integrerade, standardkedjan för autentiseringsuppgifter och flöden för åtkomsttoken.
  • Kerberos och NTLM: Integrerad Windows authentication för lokálna služba Active Directory och äldre scenarier.
  • Always Encrypted: Kryptering på klientsidan för känsliga kolumner, med valfria säkra enklaver för åtgärder på plats.
  • Masskopiering: Infogningar med hög genomströmning med SqlBulkCopy.
  • Anslutningstålighet: Inbyggda återförsök för anslutningar (ConnectRetryCount och ConnectRetryInterval) samt valbar, konfigurerbar återförsökslogik för anslutningar och kommandon.
  • Rika SQL Server-datatyper: datetimeoffset, sql_variant, JSON, vektor, rumslig, XML och tabellvärda parametrar.
  • Diagnostik: Händelsekällspårning, diagnostiska räknare, leverantörsstatistik och en dedikerad felsökningsguide.

Get started

Artikel Description
Kom igång med SqlClient-drivrutinen Sätt upp ett projekt, skapa en databas, koppla upp, fråga och lägg till anslutningsresiliens.
ADO.NET-arkitektur med Microsoft. Data.SqlClient Lär dig hur Microsoft. Data.SqlClient implementerar ansluten åtkomst, frånkoppling och leverantörsoberoende ADO.NET-åtkomst.
Installera, uppdatera och distribuera Microsoft. Data.SqlClient Installera NuGet-paket, välj en release, uppdatera drivrutinen och förbered distributionsutdata.
Supportlivscykel Gå igenom stödda drivrutinsversioner och supportdatum.
Migrera från System.Data.SqlClient till Microsoft. Data.SqlClient Uppdatera paketreferenser, namnrymder, konfiguration och ändrat drivrutinsbeteende.
Microsoft. Data.SqlClient-namnrymd och kompatibilitet Förstå drivrutinens relation till ADO.NET, System.Data.SqlClient, .NET och SQL Server.
Vad är nytt i Microsoft. Data.SqlClient Hitta aktuella versioner, ändringar i större uppgraderingar och versionsinformation från upstream.

Konfigurera och ansluta

Artikel Description
Koppla till en datakälla Öppna och hantera anslutningar till SQL Server och Azure SQL.
Anslutningssträngar Konfigurera server-, databas-, autentiserings-, krypterings- och anslutningsbeteende.
Kryptering och certifikatvalidering Konfigurera krypterade anslutningar och validering av servercertifikat.
SQL Server anslutningspoolning Återanvänd fysiska anslutningar effektivt.
Anslutningshändelser Svara på anslutningstillstånd och informationsmeddelanden.

Autentisera och säkra

Artikel Description
SQL Server-säkerhet Gå igenom riktlinjer för autentisering, auktorisering och applikationssäkerhet.
Microsoft Entra-autentisering Koppla upp dig mot hanterad identitet, tjänsteprincip, lösenord och interaktiva flöden.
Skydda anslutningsinformation Håll inloggningsuppgifter och anslutningsinställningar borta från applikationskoden.
Alltid krypterad Skydda känsliga kolumnvärden från databassystemet.
Always Encrypted med säkra enklaver Kör rika operationer på krypterad data med en säker enklav.

Hämta och uppdatera data

Artikel Description
Kommandon och parametrar Kör parameteriserade SQL-satser och lagrade procedurer.
DataAdapters och DataReaders Strömma resultatmängder eller fyll frånkopplade datastrukturer med data.
Exekvera flera kommandon med SqlBatch Skicka en ordnad samling kommandon och bearbeta deras resultat.
Strömdata Överför stora binär-, text-, XML- och JSON-värden utan att buffra hela värdet.
Transaktioner och samtidighet Använd lokala och distribuerade transaktioner samt samtidighetskontroller.
Hämta databasschemainformation Upptäck schema-samlingar och begränsningar.
Masskopieringsoperationer Ladda stora datamängder effektivt med SqlBulkCopy.
Tabellvärdesparametrar Skicka flera rader till en parameteriserad sats eller lagrad procedur.
Flera aktiva resultatuppsättningar (MARS) Lägg ihop flera batcher på en och samma anslutning.

Datatyper

Artikel Description
ADO.NET-datatypmappningar Mappa typer i Common Language Runtime (CLR) mot leverantörs- och SQL Server-typer.
SQL Server-datatyper Arbeta med SQL Server-specifika värden och System.Data.SqlTypes typer.
JSON-data Skicka och hämta SQL Server json-datatypen.
Vektordata Skicka och hämta vektorvärden.
XML-data Läs, skriv och parametrisera XML-värden.
Binära och storvärdesdata Strömma och uppdatera binär, FILESTREAM och storvärdesdata.

Tillförlitlighet och diagnostik

Artikel Description
Konfigurerbar omprövningslogik Försök igen vid tillfälliga anslutnings- och kommandofel med begränsade principer.
Hög tillgänglighet och haveriberedskap Koppla upp dig till tillgänglighetsgrupper, lyssnare och failover-partners.
Diagnostiska räknare Övervaka aktiva anslutningar, poolade anslutningar och andra drivrutinsmått.
Aktivera händelsekällspårning Registrera detaljerade förarhändelser för diagnostik.
Dataspårning Spåra ADO.NET-operationer och dataåtkomst.
Felsökningsguide för SqlClient Diagnostisera vanliga anslutnings- och drivrutinsproblem.
Förfrågningsnotiser Ta emot notiser när sökresultaten ändras.

SQL Server funktioner

Artikel Description
SQL Server-funktioner och ADO.NET Bläddra bland SQL Server-specifika funktioner som finns tillgängliga via SqlClient.
LocalDB Koppla upp dig till SQL Server Express LocalDB-instanser.
Dataidentifiering och -klassificering Läs känslighetsklassificeringsmetadata från resultatuppsättningar.

Referens och resurser

Artikel Description
Microsoft. Data.SqlClient API-referens Bläddra i .NET API-referensen för drivrutinen.
AppContext-switchar Konfigurera kompatibilitet och säkerhetsbeteende.
Hitta ytterligare information om SqlClient. Hitta källkod, stöd och communityresurser.

Begär en funktion

För att begära en funktion, öppna ett problem i Microsoft. Data.SqlClient GitHub-arkiv.

Relaterat innehåll

  • Uppdaterades senast