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 och SQL Database 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ärdprogrammet konfigurerar (appsettings.json, miljövariabler, Azure App Configuration, Key Vault-baserade inställningar och så vidare). Konfigurationen kombinerar Transport Layer Security (TLS), hanterad identitet, vilolägesresiliens, initiala anslutningsförsök via konfigurerbar återförsökslogik (CRL) med strukturerad loggning, kommandonivå-återförsök för tillfälliga fel som utlöses mitt under en fråga, samt snabb återställning av failover-grupper.

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

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 aktiverar motståndskraft hos inaktiva anslutningar: när Open() har lyckats återansluter drivrutinen automatiskt en avbruten inaktiv anslutning vid nästa kommando. De försöker inte igen med den initiala Open(). Initiala anslutningsförsök kommer från den openRetry leverantör som tilldelats SqlConnection.RetryLogicProvider. De två egenskaperna kompletterar varandra.

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:

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
Komma igång med SqlClient-drivrutinen Sätt upp ett projekt, skapa en databas, koppla upp, fråga och lägg till anslutningsresiliens.
Översikt över SqlClient-drivrutinen Lär dig hur Microsoft. Data.SqlClient passar in i ADO.NET.
Ladda ner Microsoft. Data.SqlClient Installera NuGet-paketet och hitta källkodsversioner.
Supportlivscykel Gå igenom stödda drivrutinsversioner och supportdatum.
Microsoft. Data.SqlClient-namnrymden Migrera från System.Data.SqlClient och granska skillnader i namnrymder.

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.
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.
Asynkron programmering Använd asynkrona anslutnings-, kommando- och dataoperationer.
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-datatypenjson.
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.

Relaterat innehåll

  • Last updated on