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. Den tillhandahåller anslutningar, kommandon, resultatbehandling, transaktioner, bulkkopiering och SQL Server-specifika funktioner till .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.

Utdraget förutsätter ett projekt som riktar sig mot .NET 8 eller senare versioner och refererar till paketen Microsoft.Data.SqlClient och Microsoft.Data.SqlClient.Extensions.Azure 7.1.1. Värden, såsom .NET Generic Host eller ASP.NET Core, tillhandahåller ILogger och IConfiguration, och konfigurationen tillhandahåller servernamnet i Sql:Server och databasnamnet i 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;
}

Metoden returnerar namnet på databasen den anslutit sig till och loggar Connected to database <database>. När ett nytt försök sker loggas också en varning per omförsök med det undantag som utlöste det.

Hur varje del av utdraget fungerar:

  • Målplattformar: Alla SQL Database Engine-endpoints konfigurerade 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 aktiverade av Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Väljer TDS 8.0-kryptering. Den kräver SQL Server 2022 och senare versioner, Azure SQL Database, Azure SQL Managed Instance eller SQL database i Microsoft Fabric. SqlConnectionEncryptOption.Mandatory Använd för äldre servrar.
  • ActiveDirectoryManagedIdentity: Fungerar 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 autentisera med Azure CLI, Visual Studio-inloggning och andra autentiseringskällor. Håll det utanför produktion eftersom varje avsökning av varje källa saktar ner anslutningen. För mer information, se Använd standardautentisering.
  • MultiSubnetFailover = true: Försöker TCP-anslutningar till alla lösta IP-adresser parallellt och använder den första anslutningen som lyckas, vilket undviker den långsamma, sekventiella genomgången av varje IP-adress. Ställ in den för Azure SQL Database, Azure SQL Managed Instance, SQL-databas i Microsoft Fabric, lyssnare för tillgänglighetsgrupp och failover-klusterinstanser. Det är säkert för mål med en enda IP-adress. Det stöds inte för namngivna instanser, protokoll utöver TCP, instanser med fler än 64 IP-adresser, eller databasspegling, som är föråldrad. 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.
  • ConnectRetryCount = 3 och ConnectRetryInterval = 10: Drivrutinen försöker igen vid kvalificerande övergående fel under Open(), och återansluter en inaktiv anslutning som brutits vid nästa kommando. Standardantalet är 1. Tre försök med tio sekunders mellanrum räcker längre än en längre omkonfiguration eller failover. Drivrutinen ändrar 1 från 1 till 2 endast när servernamnet slutar i en känd Azure SQL-domän, såsom .database.windows.net, så ett anpassat DNS-alias får 1.
  • openRetry: Tilldelad till SqlConnection.RetryLogicProvider, lägger den till exponentiell backoff runt Open(). Drivrutinen stoppar sina interna försök när ConnectTimeout löper ut, så det värsta som kan hända innan OpenAsync utlöses är fem försök på upp till 30 sekunder vardera, plus backoff. Varje inaktivt återanslutningsförsök kör också hela openRetry policyn, och när policyn har uttömt sina omförsök upphör viloåterställningen.
  • Serverless auto-pause: För Azure SQL Database serverless, höj ConnectTimeout till minst 60 sekunder. Den första Open() kan misslyckas med fel 40613 medan databasen återhämtar sig och openRetry försöker igen. En timeout på klientsidan framträder som fel -2, som inte återförsöks, så varje anslutningsförsök måste vara längre än återupptagningen. Mer information finns i Automatisk paus och automatisk återupptagning.
  • commandRetry: Koppla den endast till SqlCommand.RetryLogicProvider när det är säkert att återuppspela kommandot: läsningar, MERGE skyddade av en naturlig nyckel, upserts genom en lagrad procedur och andra idempotenta operationer. Den hoppar över återförsök i en transaktion, så applikationskoden måste försöka igen med transaktioner med flera satser. ExecuteReader och ExecuteScalar försöker endast igen fel som returneras innan den första resultatuppsättningen börjar. ExecuteNonQuery försöker hela anropet igen.
  • Tillfällig fellista: Inställningen TransientErrors ersätter den inbyggda listan. För att utöka den istället, använd SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 och senare).
  • Retrying Händelse: Retrying utlöses före varje omförsök med omförsöksräkningen, nästa fördröjning och undantagen hittills. Skicka den till ILogger eller till din telemetripipeline.
  • Undantag: Metoden fångar inga undantag. En utmattad provider kastar AggregateException med undantaget från varje försök. Ett bestående fel propagerar som det ursprungliga undantaget. Anroparen loggar det en gång tillsammans med resten av begärandekontexten.
  • Avbokning: Det CancellationToken stoppar leverantörens väntan mellan återförsöken. Det avbryter inte förarens ConnectRetryInterval väntan inom ett enskilt Open försök. För mer information, se Asynkron programmering.
  • Leverantörens livslängd: Snippeten skapar providers för återförsök vid varje anrop för att förbli självständiga. I en applikation skapar du dem en gång och återanvänder dem.

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.
  • 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.
  • Anslutningspoolning: Aktiverad som standard. En opt-in V2-pool är under utvärdering.
  • 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.
  • Applikationsidentitet: Ange SqlConnection.RegisteredApplication för att identifiera ditt bibliotek eller verktyg till SQL Server (Microsoft.Data.SqlClient 7.1 och senare).

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.
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å hur SqlClient implementerar ADO.NET och dess kompatibilitet med 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, och svara på förändringar i anslutningstillstånd.
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.
Hantera fel och meddelanden Fånga fel och ta emot informationsmeddelanden.

Autentisera och säkra

Artikel Description
Bästa praxis för säkerhet för Microsoft.Data.SqlClient 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
Utför ett kommando 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
SQL Server-datatypmappningar Mappa SQL Server-typer till .NET 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.
Händelseräknare i SqlClient Övervaka aktiva anslutningar, poolade anslutningar och andra drivrutinsmått.
Aktivera händelsekällspårning Registrera detaljerade förarhändelser för diagnostik.
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.
Microsoft.Data.SqlClient GitHub-lagringsplats Läs drivrutinens källkod, versionsanteckningar och exempel.
Microsoft.Data.SqlClient-exempel Bläddra bland C#-exempel för drivrutins-API:er.
.NET runtime GitHub-lagringsplats Läs källkoden för .NET:s runtime-bibliotek.

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