Microsoft. Data.SqlClient for SQL Server

ADO.NET letöltése

A Microsoft.Data.SqlClient az SQL Serverhez, az Azure SQL Database-hez, az Azure SQL Managed Instance-hez, az Azure Synapse Analyticshez és a Microsoft Fabric SQL-adatbázisához támogatott .NET-adatszolgáltató. 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. Használd kapcsolatok megnyitásához, parancsok végrehajtásához, eredmények feldolgozásához, tranzakciók kezelésére, adatok tömeges betöltésére, valamint az SQL Server-specifikus funkciók használatára a .NET alkalmazásokból.

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 olvasza ki , IConfigurationígy az értékek azoktól a konfigurációs szolgáltatóktól származnak, amelyeket a host beköt (appsettings.json, környezeti változók, Azure App Configuration, Key Vault-alapú beállítások stb.). A konfiguráció ötvözi a Transport Layer Securityt (TLS), a felügyelt identitást, a tétlen kapcsolatokkal szembeni ellenálló képességet, a kezdeti csatlakozás konfigurálható újrapróbálkozási logikán (CRL) keresztüli újrapróbálását strukturált naplózással, a lekérdezés közben fellépő átmeneti hibák esetén alkalmazott parancsszintű újrapróbálkozásokat, valamint a feladatátvételi csoport gyors helyreállítását.

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.

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

Ez a kódrészlet bármely, Microsoft Entra-hitelesítéshez konfigurált SQL Database Engine végpontjára vonatkozik: Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric SQL-adatbázis, valamint az Azure Virtual Machinesen futó vagy Azure Arc által engedélyezett SQL Server 2022 és újabb verziói.

Encrypt = SqlConnectionEncryptOption.Strict kiválasztja a TDS 8.0 titkosítást. A használatához a Microsoft.Data.SqlClient 5.0-s vagy újabb verziója, valamint egy olyan kiszolgáló szükséges, amely támogatja a TDS 8.0-t (SQL Server 2022 és újabb verziók, Azure SQL Database, Azure SQL Managed Instance és a Microsoft Fabric SQL-adatbázisa). Használd a(z) SqlConnectionEncryptOption.Mandatory elemet tartalékként, amikor régebbi szerverekhez csatlakozol.

ConnectRetryCount és ConnectRetryInterval lehetővé teszi a tétlen kapcsolat hibatűrését: a Open() sikeres végrehajtása után az illesztőprogram a következő parancs kiadásakor automatikusan újracsatlakoztat egy megszakadt tétlen kapcsolatot. Nem próbálják újra a kezdőbetűt Open(). A kezdeti csatlakozási újrapróbálkozások a SqlConnection.RetryLogicProvider-hez rendelt openRetry szolgáltatótól származnak. A két jellemző kiegészíti egymást.

Az Retrying egyes szolgáltatók eseménye minden újrapróbálkozás előtt aktiválódik, és tartalmazza az újrapróbálkozás számát, a következő próbálkozás előtti késleltetést, valamint az eddig megfigyelt kivételeket. Továbbítsd a(z) ILogger elemhez vagy a telemetriai adatfeldolgozási folyamatodba, hogy az újrapróbálkozási ciklus éles környezetben is látható maradjon.

Állítsa be a(z) MultiSubnetFailover = true értéket, ha a cél Azure SQL Database, Azure SQL Managed Instance, a Microsoft Fabricben található SQL-adatbázis, rendelkezésreállási csoport figyelője vagy feladatátvételi fürt példánya. Kiválaszt egy párhuzamos kód útvonalat, amely párhuzamosan próbál TCP-kapcsolatokat indítani az összes feloldott IP-címhez, és az első, sikeres kapcsolatot használja, elkerülve a lassú, IP-enkénti sétát, amely egyébként leállíthatja ezeket a kapcsolatokat. Egy-IP célpontokon a beállítás biztonságos. A(z) MultiSubnetFailover nem támogatott, ha elnevezett példányhoz csatlakozik, TCP-től eltérő protokollon keresztül csatlakozik, vagy olyan példányhoz csatlakozik, amely több mint 64 IP-címmel van konfigurálva. Adatbázis-tükrözéssel sem lehet használni, ami az összes támogatott SQL Server verzióban 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.

Ha a cél a(z) Azure SQL Database kiszolgáló nélküli, és az automatikus szüneteltetés engedélyezve van, emeld meg a(z) ConnectTimeout értékét legalább 60 másodpercre. Az automatikusan szüneteltetett adatbázis az első Open() hatására újraindul, és az első Open() meghiúsulhat 40613 hibával, miközben az adatbázis újraindul. A(z) 40613 hiba szerepel a beépített átmeneti hibák listájában, ezért a(z) openRetry újrapróbálja. Az ügyféloldali időtúllépések -2 hibaként jelennek meg, ami nem szerepel ebben a listában, így a openRetry nem nyújt védelmet egy olyan Open() esetén, amelynek az időtúllépése a folytatás közben következik be. Az egyéni kapcsolati kísérletnek elég hosszúnak kell lennie ahhoz, hogy lefedje az önéletrajzot. További információkért lásd: Automatikus szüneteltetés és automatikus folytatás.

A parancsszintű újrapróbálkozásról parancsonként a hívó dönt. Csak akkor rendelje hozzá a(z) commandRetry elemet a(z) SqlCommand.RetryLogicProvider elemhez, ha a parancs újrajátszása biztonságos: olvasási műveletek, természetes kulccsal védett MERGE, tárolt eljáráson keresztül végzett upsertek és egyéb idempotens műveletek. A beépített parancsszolgáltató kihagyja az újrapróbálkozást, amikor egy tranzakció aktív, ezért a többmondatú tranzakciókat újra kell próbálni egy alkalmazáskóddal, amely újra megnyithatja a tranzakciót. A TransientErrors beállítás lecseréli az illesztőprogram beépített hibalistáját; ha ehelyett a beépített alapértelmezett listát szeretné bővíteni, használja a SqlConfigurableRetryFactory.BaselineTransientErrors beállítást (Microsoft.Data.SqlClient 7.0 és újabb).

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

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 . Állítsa be a(z) Encrypt=Strict értéket a TDS 8.0 titkosításhoz a Microsoft.Data.SqlClient 5.0-s és újabb verzióiban.
  • 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.
  • 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ó.

Első lépések

Cikk Leírás
Az SqlClient-illesztő használatának első lépései Állíts be egy projektet, hozz létre adatbázist, csatlakozz, kérdezzél, és növeld a kapcsolati rugalmasságot.
Az SqlClient-illesztőprogram áttekintése Ismerje meg, hogyan működik a Microsoft. Data.SqlClient illeszkedik az ADO.NET-be.
Töltse le a Microsoft.Data.SqlClient fájlt Telepítsd a NuGet csomagot, és keresd meg a forráskiadásokat.
Támogatási életciklus Nézze át a támogatott illeszerverziókat és a támogatási dátumokat.
Microsoft.Data.SqlClient névtér Migrálj a System.Data.SqlClient-ről, és nézd át a névtér különbségeit.

Konfigurálás és csatlakoztatás

Cikk Leírás
Kapcsolódni egy adatforráshoz Nyisd meg és kezeld a SQL Server és Azure SQL kapcsolatokat.
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.
Kapcsolati események Válaszolj a kapcsolati állapotra és az információs üzenetekre.

Hitelesítés és biztonság

Cikk Leírás
AZ SQL Server biztonsága 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
Parancsok és paraméterek 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.
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.
Aszinkron programozás Használj aszinkron kapcsolatot, parancsot és adatműveleteket.
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
ADO.NET adattípus-leképezések A közös nyelvi futóidős típusokat a szolgáltató és SQL Server típusokhoz képezzük.
SQL Server adattípusok Dolgozz SQL Server-specifikus értékekkel és System.Data.SqlTypes típusokkal.
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.
Diagnosztikai számlálók 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.
Adatkövetés Kövesse az ADO.NET műveleteket és az adathozzáférést.
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.
További SqlClient információk Keress forráskódot, támogatást és közösségi forrásokat.

Kapcsolódó tartalom

  • Last updated on