Microsoft. Data.SqlClient for SQL Server

ADO.NET letöltése

A Microsoft.Data.SqlClient a támogatott .NET-adatszolgáltató az SQL Server, az Azure SQL Database, az Azure SQL Managed Instance, az Azure Synapse Analytics, a Microsoft Fabric SQL-adatbázisa és a Microsoft Fabric Warehouse számára. NuGet-csomagként kerül terjesztésre, a .NET-futtatókörnyezettől függetlenül fejlődik, és új fejlesztésekhez a System.Data.SqlClient helyébe lép. Kapcsolatokat, parancsokat, eredményfeldolgozást, tranzakciókat, tömeges másolást és SQL Server-specifikus funkciókat biztosít a .NET alkalmazások számára.

Válassza ki a kiindulási pontot

Azure SQL üzemi alapkonfigurációja

Használd ezt a snippetet kiindulópontként egy termelésorientált Azure SQL adathozzáférési útvonalhoz. A szerver- és adatbázisneveket a IConfiguration-ból olvassa, így az értékek a konfigurációs szolgáltatóktól származnak, amelyeket a host beköt, például appsettings.json, környezeti változók, Azure App Configuration és Key Vault-alapú beállítások. A konfiguráció ezeket a jellemzőket ötvözi:

  • Transport Layer Security (TLS).
  • Felügyelt identitás.
  • Inaktív kapcsolat rugalmassága.
  • A kezdeti csatlakozás újrapróbálása konfigurálható újrapróbálkozási logikán (CRL) keresztül, strukturált naplózással.
  • Parancsszintű újrapróbálkozás átmeneti hibák esetén, amelyek lekérdezés közben jelentkeznek.
  • A failovercsoport gyors helyreállítása.
  • Aszinkron hívások, amelyek elfogadnak egy megszakítási tokent.

A nagyobb biztonság és a különböző környezetek közötti konfiguráció támogatása érdekében tartsd a kapcsolati adatokat a kódon kívül. Gyártásban tárold a kapcsolati információkat az alkalmazásod konfigurációs rendszerében, és az Azure Key Vault-t használd az érzékeny értékekhez. További információ: Kapcsolati adatok védelme.

A cikkben szereplő C# részlet a using rövidség érdekében kihagyja az utasításokat és az osztályburkolatokat.

A snippet egy olyan projektet feltételez, amely a .NET 8 vagy újabb verziókat célozza meg, és hivatkozik a Microsoft.Data.SqlClient 7.1.1-es és Microsoft.Data.SqlClient.Extensions.Azure 7.1.1-es csomagokra. A hoszt, például a .NET Generic Host vagy az ASP.NET Core, biztosítja a ILogger-t és a IConfiguration-et, a konfiguráció pedig a szerver Sql:Server nevét és az adatbázis nevét a(z) Sql:Database elemben.

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

A metódus visszaadja annak az adatbázisnak a nevét, amelyhez csatlakozott, és naplózza a(z) Connected to database <database> elemet. Amikor újrapróbálkozás történik, minden próbálkozásnál egy figyelmeztetést is rögzít, azzal a kivétellel, amely kiváltotta.

Így működnek a kódrészlet egyes részei:

  • Célpontok: Bármely SQL Database Engine végpont, amely Microsoft Entra-hitelesítéshez van konfigurálva: Azure SQL Database, Azure SQL Managed Instance, SQL-adatbázis a Microsoft Fabricben, és SQL Server 2022 és újabb verziók az Azure Virtual Machines szolgáltatásban vagy Azure Arc által engedélyezve.
  • Encrypt = SqlConnectionEncryptOption.Strict: A TDS 8.0 titkosítás kiválasztása. Ehhez SQL Server 2022 és újabb verziók, Azure SQL Database, Azure SQL Managed Instance vagy SQL database a Microsoft Fabric-ben szükséges. Régebbi szerverekhez használja a(z) SqlConnectionEncryptOption.Mandatory elemet.
  • ActiveDirectoryManagedIdentity: Csak akkor működik, ha kezelt identitás elérhető, például Azure App Service, Azure Functions vagy Azure virtuális gép. Helyi fejlesztéshez használd SqlAuthenticationMethod.ActiveDirectoryDefault, amely az Azure CLI-t, a Visual Studio bejelentkezést és más hitelesítőadat-forrásokat próbálja. Tartsd távol az éles környezettől, mert minden forrás vizsgálata lassítja a kapcsolatot. További információért lásd: Alapértelmezett hitelesítés használata.
  • MultiSubnetFailover = true: Megpróbál párhuzamosan TCP-kapcsolatokat létesíteni az összes feloldott IP-címhez, és az első sikeres kapcsolatot használja, elkerülve a lassú, IP-enkénti sétát. Állítsd be ehhez: Azure SQL Database, Azure SQL Managed Instance, SQL-adatbázis a Microsoft Fabricben, rendelkezésre állási csoport figyelői és feladatátvételi fürtpéldányok. Egy IP-című célpontokon biztonságos. Nem támogatott elnevezett példányok esetén, a TCP-től eltérő protokolloknál, 64-nél több IP-címmel rendelkező példányoknál, illetve adatbázis-tükrözés esetén, amely elavult. Használja inkább az Always On rendelkezésre állási csoportokat. További információért lásd: Magas rendelkezésre állás és katasztrófa-helyreállítás és Átlátszó hálózati IP felbontás letiltása.
  • ConnectRetryCount = 3 és ConnectRetryInterval = 10: Az illesztőprogram a Open() során újra megpróbálja az újrapróbálható átmeneti hibákat, és a következő parancsnál újracsatlakoztatja a megszakadt tétlen kapcsolatot. Az alapértelmezett darabszám 1. A három, 10 másodpercenkénti próbálkozás tovább tart, mint egy hosszabb újrakonfigurálás vagy átállás. Az illesztőprogram csak akkor emeli az 1-et 2-re, ha a szerver neve egy ismert Azure SQL domainben végződik, például .database.windows.net, így egy egyedi DNS alias 1-et kap.
  • openRetry: A(z) SqlConnection.RetryLogicProvider-hoz rendelve exponenciális visszalépést ad hozzá a(z) Open() köré. Az illesztőprogram leállítja a belső újrapróbálkozásokat, amikor ConnectTimeout lejár, így a legrosszabb esetben OpenAsync kiváltása előtt legfeljebb öt próbálkozás történik, mindegyik akár 30 másodpercig is, plusz várakozási idő. Minden üresjárati újracsatlakozási kísérlet a teljes openRetry szabályzatot is lefuttatja, és amikor ez a szabályzat kimeríti az újrapróbálkozási lehetőségeit, az üresjárati helyreállítás véget ér.
  • Serverless auto-pause: Azure SQL Database serverless esetén emeld ConnectTimeout értékét legalább 60 másodpercre. Az első Open() meghiúsulhat 40613 hibával, miközben az adatbázis helyreáll, és openRetry újra próbálkozik. Az ügyféloldali időtúllépés hibaként -2 jelenik meg, amit nem próbálnak újra, így minden csatlakozási próbálkozásnak tovább kell tartania a folytatásnál. További információkért lásd: Automatikus szüneteltetés és automatikus folytatás.
  • commandRetry: Csak akkor csatold a(z) SqlCommand.RetryLogicProvider-hez, ha a parancs újrajátszása biztonságos: olvasások, a természetes kulccsal védett MERGE, upsertek tárolt eljáráson keresztül és egyéb idempotens műveletek. Kihagyja a tranzakción belüli újrapróbálkozást, így az alkalmazáskódnak újra kell próbálnia a több utasításból álló tranzakciókat. ExecuteReader és ExecuteScalar csak azokat a hibákat próbálja újra, amelyeket az első eredményhalmaz kezdete előtt ad vissza a rendszer. ExecuteNonQuery újrapróbálja a teljes hívást.
  • Átmeneti hibalista: A(z) TransientErrors beállítása lecseréli a beépített listát. A bővítéshez ehelyett használja a SqlConfigurableRetryFactory.BaselineTransientErrors elemet (Microsoft.Data.SqlClient 7.0 és újabb verziók).
  • Retrying Esemény: Retrying minden újrapróbálkozás előtt aktiválódik az újrapróbálkozás számával, a következő késleltetéssel és az eddigi kivételekkel. Irányítsd át a ILogger-ra vagy a telemetriai csővezetékre.
  • Kivételek: A módszer nem kezeli a kivételeket. Egy kimerült szolgáltató a AggregateException elemet dobja az egyes kísérletekből származó kivétellel. Egy nem átmeneti hiba az eredeti kivételként továbbterjed. A hívó fél egyszer naplózza a kérés többi kontextusával együtt.
  • Lemondás: A CancellationToken megállítja a szolgáltató várakozását az újrapróbálkozások között. Nem szakítja meg a sofőr ConnectRetryInterval várakozását egyetlen Open próbálkozáson belül. További információért lásd: Aszinkron programozás.
  • Szolgáltató élettartama: A snippet minden hívásnál létrehozza az újrapróbálkozási szolgáltatókat, hogy önállóak maradjanak. Egy alkalmazásban egyszer hozd létre őket, és használd újra.

A konfiguráció egyes részeivel kapcsolatos további információkért lásd:

Ismerd meg az alapvető adathozzáférési feladatokat

Miután csatlakoztál, használd ezeket a cikkeket a sorrendben:

  1. Végrehajtson egy parancsot, hogy kiválassza az eredmény alakját, és futtassa a Transact-SQL-t.
  2. Konfiguráld a paramétereket az adatbázis-szerződéshez igazodva.
  3. Adatok lekérése a SqlDataReaderrel, hogy feldolgozd a sorokat és több eredményt.
  4. Módosítsd az adatokat tárolt eljárásokkal kimeneti paraméterek és visszatérési értékek használatához.
  5. Használj aszinkron programozást és megszakítást, hogy a hívó általi megszakítást és a korlátozott időtúllépéseket támogasd.
  6. Kezeld a hibákat és üzeneteket, mielőtt újrapróbálkozást vagy gyártási diagnosztikát adnál hozzá.

Legfontosabb funkciók

  • Modern .NET támogatás: A jelenlegi .NET és .NET Framework verziókon fut. A verziónkénti bontásért lásd: Támogatási életciklus.
  • Alapértelmezés szerint titkosított: TLS-titkosított kapcsolatok alapértelmezettként Encrypt=true . A TDS 8.0 titkosításhoz állítsa be a(z) Encrypt=Strict értéket.
  • Microsoft Entra ID hitelesítés: Jelszó nélküli kapcsolatok felügyelt identitással, szolgáltatásnévvel, interaktív, integrált, alapértelmezett hitelesítőadat-lánccal és hozzáférési jogkivonat-folyamatokkal.
  • Kerberos és NTLM: Integrált Windows-hitelesítés helyszíni Active Directoryhoz és örökölt forgatókönyvekhez.
  • Always Encrypted: Ügyféloldali titkosítás bizalmas oszlopokhoz, opcionális biztonságos enklávékkal a helyszíni műveletekhez.
  • Tömeges másolás: Nagy átviteli sebességű beszúrások SqlBulkCopy.
  • Kapcsolatpoolozás: Alapértelmezés szerint be van kapcsolva. Egy opt-in V2 pool vizsgálat alatt áll.
  • Kapcsolati rugalmasság: Beépített kapcsolódási újrapróbálások (ConnectRetryCount és ConnectRetryInterval), valamint opt-in konfigurálható újrapróbálási logika a kapcsolatokhoz és parancsokhoz.
  • Gazdag SQL Server-adattípusok: datetimeoffset, sql_variant, JSON, vektor, térbeli, XML és táblázatértékű paraméterek.
  • Diagnosztika: Eseményforrás követés, diagnosztikai számlálók, szolgáltatói statisztikák és egy dedikált hibakeresési útmutató.
  • Alkalmazásidentitás: Állítsa be a(z) SqlConnection.RegisteredApplication értéket a könyvtár vagy eszköz az SQL Server számára történő azonosításához (Microsoft.Data.SqlClient 7.1 és újabb).

Első lépések

Cikk Leírás
Ismerkedés a SqlClient-illesztőprogrammal Állíts be egy projektet, hozz létre adatbázist, csatlakozz, kérdezzél, és növeld a kapcsolati rugalmasságot.
Telepítsd, frissítsd és telepítsd a Microsoft-ot. Data.SqlClient Telepítsd a NuGet csomagokat, válassz ki egy kiadást, frissítsd a drivert, és készítsd elő a telepítési kimenetet.
Támogatási életciklus Nézze át a támogatott illeszerverziókat és a támogatási dátumokat.
Migráció a System.Data.SqlClient-ről a Microsoft-ra. Data.SqlClient Frissítse a csomaghivatkozásokat, névtereket, konfigurációt és módosítsa az illesztőprogram viselkedését.
Microsoft. Data.SqlClient névtér és kompatibilitás Ismerd meg, hogyan valósítja meg az ADO.NET-et az SqlClient, és kompatibilitását a System.Data.SqlClienttal, a .NET-tel és a SQL Serverrel.
Újdonságok a Microsoft.Data.SqlClientben Találd meg a jelenlegi kiadásokat, jelentős frissítési változásokat és az előzménybeli megjelenési jegyzeteket.

Konfigurálás és csatlakoztatás

Cikk Leírás
Kapcsolódni egy adatforráshoz Nyisd meg és kezeld a kapcsolatokat, és reagálj a kapcsolati állapotváltozásokra.
Kapcsolati karakterláncok Konfiguráld szervert, adatbázist, hitelesítést, titkosítást és kapcsolati viselkedést.
Titkosítás és tanúsítvány ellenőrzése Titkosított kapcsolatok és szervertanúsítvány ellenőrzésének konfigurálása.
SQL Server connection pooling Hasznosítsd a fizikai kapcsolatokat hatékonyan.
Hibák és üzenetek kezelése Hibák észlelése és tájékoztató üzenetek fogadása.

Hitelesítés és biztonság

Cikk Leírás
A Microsoft.Data.SqlClient biztonsági bevált gyakorlatai Tekintse át a hitelesítési, engedélyezési és alkalmazásbiztonsági útmutatót.
Microsoft Entra-hitelesítés Kapcsolódj menedzselt identitással, szolgáltatási alapokkal, jelszóval és interaktív folyamatokkal.
Kapcsolódási információk védelme Tartsd távol a hitelesítési adatokat és a csatlakozási beállításokat az alkalmazáskódtól.
Mindig titkosítva Védd meg az érzékeny oszlopértékeket az adatbázis rendszertől.
Mindig titkosított, biztonságos enklávékkal Összetett műveletek végrehajtása titkosított adatokon biztonságos enklávéban.

Adatok lekérése és frissítése

Cikk Leírás
Parancs végrehajtása Paraméterezett SQL utasításokat és tárolt eljárásokat hajtsd végre.
Adatadapterek és Adatolvasók Az eredményhalmazokat adatfolyamként kezelheti, vagy leválasztott adatstruktúrákat tölthet fel.
Több parancs végrehajtása a SqlBatch segítségével Küldj egy rendezett parancsgyűjteményt és dolgozd fel az eredményeket.
Adatfolyam Nagy bináris, szöveges, XML és JSON értékeket továbbítson anélkül, hogy a teljes értéket pufferelné.
Tranzakciók és egyidejűség Használj helyi és elosztott tranzakciókat, valamint egyidejű szabályozásokat.
Adatbázis-séma információk lekérése Fedezze fel a sémagyűjteményeket és korlátozásokat.
Tömeges másolási műveletek Nagy adatkészletek hatékony betöltése a(z) SqlBulkCopy használatával.
Táblaértékkel megadott paraméterek Több sort küldj egy paraméterezett utasításhoz vagy tárolt eljáráshoz.
Több aktív eredményhalmaz (MARS) Fűzzön össze több köteget egy kapcsolaton belül.

Adattípusok

Cikk Leírás
SQL Server adattípus-mappingek SQL Server-típusok megfeleltetése a .NET- és System.Data.SqlTypes típusoknak.
JSON adatok Küldd és kérd le az SQL Server json adattípusát.
Vektoradatok Küldj és kérd ki vektorértékeket.
XML adatok XML értékek olvasása, írása és paraméterezése.
Bináris és nagy értékű adatok Streamelj és frissítsd bináris, FILESTREAM és nagy értékű adatokat.

Megbízhatóság és diagnosztika

Cikk Leírás
Konfigurálható újrapróbálkozás logikája Próbáld meg újra a múló kapcsolatot és parancshibákat korlátozott szabályzatokkal.
Magas rendelkezésre állás és vészhelyreállítás Kapcsolódjon a rendelkezésre állási csoport figyelőihez és a feladatátvételi partnerekhez.
Eseményszámlálók az SqlClientben Figyeld az aktív kapcsolatokat, a csoportos kapcsolatokat és más driver mutatókat.
Engedélyezd az eseményforrás követését Rögzítse a részletes vezetői eseményeket a diagnózishoz.
Az SqlClient hibaelhárítási útmutatója Diagnosztizáld a gyakori kapcsolati és driver-problémákat.
Lekérdezési értesítések Értesítéseket kapsz, ha a lekérdezési eredmények változnak.

SQL Server funkciók

Cikk Leírás
AZ SQL Server funkciói és ADO.NET Böngésszük az SQL Server-specifikus funkciókat, amelyek elérhetők a SqlClient-en keresztül.
LocalDB Csatlakozz SQL Server Express LocalDB instance-okhoz.
Adatfelderítés és besorolás Olvasd el az érzékenységi osztályozás metaadatait eredményhalmazból.

Referencia és erőforrások

Cikk Leírás
Microsoft. Data.SqlClient API reference Böngéssze az illesztőprogram .NET API-referenciáját.
AppContext-kapcsolók Konfiguráld a kompatibilitást és a biztonsági viselkedést.
Microsoft.Data.SqlClient GitHub-adattár Olvasd el a meghajtó forráskódját, a kiadási jegyzeteket és a mintákat.
Microsoft.Data.SqlClient minták Böngésszük a C# mintákat illesztőprogram-API-khoz.
.NET runtime GitHub-adattár Olvassa el a .NET runtime könyvtárak forrását.

Szolgáltatás igénylése

Egy funkció igényléséhez nyisson egy issue-t a Microsoft.Data.SqlClient GitHub-adattárban.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: