Microsoft. Data.SqlClient for SQL Server

Stáhnout ADO.NET

Microsoft. Data.SqlClient je podporovaný poskytovatel .NET dat pro SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics a SQL database v Microsoft Fabric. Je distribuován jako balíček NuGet, vyvíjí se nezávisle na modulu runtime .NET a v novém vývoji nahrazuje System.Data.SqlClient. Používejte ho k otevírání spojení, provádění příkazů, zpracování výsledků, správě transakcí, hromadnému načítání dat a využívání specifických funkcí SQL Server z .NET aplikací.

Výběr výchozího bodu

Směrný plán výroby pro Azure SQL

Použijte tento úryvek jako výchozí bod pro produkčně orientovanou cestu přístupu k Azure SQL datům. Čte názvy serverů a databází z IConfiguration, takže hodnoty pocházejí od konfiguračních poskytovatelů, které host zapojuje (appsettings.json, proměnné prostředí, Azure App Configuration, nastavení podporovaná Key Vault a podobně). Konfigurace kombinuje zabezpečení transportní vrstvy (TLS), spravovanou identitu, odolnost při nečinnosti připojení, opakování pokusu o počáteční připojení pomocí konfigurovatelné logiky opakování (CRL) se strukturovaným protokolováním, opakování na úrovni příkazů pro přechodné chyby, které nastanou během provádění dotazu, a rychlé zotavení skupiny převzetí služeb při selhání.

Pro vyšší bezpečnost a podporu konfigurace napříč prostředími udržujte informace o spojení mimo svůj kód. V produkci ukládejte informace o připojení do konfiguračního systému vaší aplikace a používejte Azure Key Vault pro citlivé hodnoty. Další informace naleznete v tématu Ochrana informací o připojení.

Úryvek C# v tomto článku vynechává using směrnice a obvazy tříd kvůli stručnosti.

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

Tento fragment je určen pro jakýkoli koncový bod SQL Database Engine nakonfigurovaný pro ověřování pomocí Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, databáze SQL v Microsoft Fabric a SQL Server 2022 a novější verze na virtuálních počítačích Azure nebo s podporou Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict vybírá šifrování TDS 8.0. Vyžaduje to Microsoft. Data.SqlClient 5.0 a novějších verzí a server podporující TDS 8.0 (SQL Server 2022 a pozdější, Azure SQL Database, Azure SQL Managed Instance a SQL databáze v Microsoft Fabric). Použijte při připojení ke starším serverům SqlConnectionEncryptOption.Mandatory jako záložní možnost.

ConnectRetryCount a ConnectRetryInterval povolují odolnost nečinného připojení vůči výpadkům: po úspěšném dokončení Open() ovladač při dalším příkazu transparentně znovu naváže přerušené nečinné připojení. Nezkoušejí znovu počáteční Open(). Opakované pokusy o počáteční připojení pocházejí od poskytovatele openRetry, který je přiřazen k SqlConnection.RetryLogicProvider. Tyto dvě vlastnosti se doplňují.

Událost Retrying u každého poskytovatele se spustí před každým opakovaným pokusem a nese počet opakování, zpoždění před dalším pokusem a dosud pozorované výjimky. Směrujte to do ILogger nebo do svého telemetrického kanálu, aby byl cyklus opakovaných pokusů v produkci viditelný.

Nastavte MultiSubnetFailover = true cíl, kdy je cílem Azure SQL Database, Azure SQL Managed Instance, SQL databáze v Microsoft Fabric, naslouchač skupiny dostupnosti nebo instance failover clusteru. Vybere paralelní cestu v kódu, která se pokouší navázat TCP spojení ke všem přeloženým IP adresám současně a použije první úspěšně navázané spojení, čímž se vyhne pomalému sekvenčnímu zkoušení jednotlivých IP adres, které by jinak mohlo navazování těchto spojení zdržet. U cílů s jednou IP adresou je toto nastavení bezpečné. MultiSubnetFailover není podporováno, když se připojíte k pojmenované instanci, přes jiný protokol než TCP, nebo k instanci nakonfigurované s více než 64 IP adresami. Také ho nelze použít s databázovým zrcadlením, které je zastaralé ve všech podporovaných verzích SQL Server. Místo toho používejte skupiny dostupnosti AlwaysOn. Pro více informací viz Vysoká dostupnost a obnova po havárii a Vypínání transparentního síťového IP řešení.

Pokud je cílovým serverem Azure SQL Database serverless s povoleným automatickým pozastavováním, zvyšte hodnotu ConnectTimeout alespoň na 60 sekund. Automaticky pozastavená databáze se obnoví při prvním Open() a tento první Open() může během obnovování databáze selhat s chybou 40613. Chyba 40613 je v vestavěném seznamu přechodných chyb, takže openRetry ji znovu zkoušíme. Časové limity na straně klienta se projeví jako chyba -2, která v daném seznamu není, takže openRetry nezachrání Open(), u něhož během obnovování vyprší časový limit. Individuální pokus o spojení by měl být dostatečně dlouhý, aby pokryl životopis. Více informací naleznete v části Automatické pozastavení a automatické obnovení.

Opakované zkusení na úrovni příkazu je rozhodnutím volajícího podle jednotlivých příkazů. Připojte commandRetry k SqlCommand.RetryLogicProvider pouze tehdy, když je bezpečné příkaz znovu přehrát: operace čtení, MERGE, které jsou chráněné přirozeným klíčem, operace upsert prostřednictvím uložené procedury a další idempotentní operace. Vestavěný poskytovatel příkazů přeskočí opakování, když je transakce aktivní, takže vícepříkazové transakce musí být znovu zkoušeny aplikačním kódem, který může transakci znovu otevřít. Nastavení TransientErrors nahradí integrovaný seznam chyb ovladače; pokud místo toho chcete rozšířit výchozí základ, použijte SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 a novější verze).

Další informace o jednotlivých částech této konfigurace najdete tady:

Klíčové funkce

  • Moderní podpora .NET: Běží na současných verzích .NET a .NET Framework. Pro rozdělení jednotlivých verzí viz životní cyklus podpory.
  • Ve výchozím nastavení jsou šifrovány: TLS-šifrované spojení s Encrypt=true výchozím nastavením. Nastavte Encrypt=Strict pro šifrování TDS 8.0 v Microsoft.Data.SqlClient 5.0 a vyšší.
  • ověřování Microsoft Entra ID: připojení bez hesla se spravovanou identitou, instančním objektem, interaktivním, integrovaným, výchozím řetězem přihlašovacích údajů a toky přístupového tokenu.
  • Kerberos a NTLM: Integrované ověřování systému Windows pro místní službu Active Directory a starší prostředí.
  • Always Encrypted: Šifrování na straně klienta pro citlivé sloupce s volitelnými zabezpečenými enklávy pro místní operace.
  • Hromadné kopírování: Vysokorychlostní vkládání s SqlBulkCopy.
  • Odolnost připojení: Vestavěné opakování pokusů o připojení (ConnectRetryCount a ConnectRetryInterval) a volitelná konfigurovatelná logika opakování pro připojení a příkazy.
  • Bohaté datové typy SQL Server: datetimeoffset, sql_variant, JSON, vektorové, prostorové, XML a tabulkové parametry.
  • Diagnostika: Sledování zdrojů událostí, diagnostické čítače, statistiky poskytovatelů a speciální průvodce řešením problémů.

Začínáme

Článek Description
Začínáme s ovladačem SqlClient Nastavte projekt, vytvořte databázi, připojte se, dotazujte a přidejte odolnost spojení.
Přehled ovladače SqlClient Zjistěte, jak Microsoft. Data.SqlClient zapadá do ADO.NET.
Stáhněte si Microsoft. Data.SqlClient Nainstalujte balíček NuGet a najděte zdrojová vydání.
Životní cyklus podpory Prohlédněte si podporované verze ovladačů a data podpory.
Obor názvů Microsoft.Data.SqlClient Přejděte ze System.Data.SqlClient a zkontrolujte rozdíly v oborech názvů.

Konfigurace a připojení

Článek Description
Připojte se ke zdroji dat Otevřete a spravujte připojení k SQL Server a Azure SQL.
Připojovací řetězce Nastavte server, databázi, autentizaci, šifrování a chování připojení.
Šifrování a ověřování certifikátů Konfigurujte šifrovaná připojení a validaci serverových certifikátů.
SQL Server connection pooling Efektivně znovu používejte fyzická spojení.
Spojovací události Reagujte na stav připojení a informační zprávy.

Autentizace a zabezpečení

Článek Description
Zabezpečení SQL Serveru Prostudujte si pokyny pro autentizaci, autorizaci a bezpečnost aplikací.
Ověřování Microsoft Entra Připojte se k spravované identitě, principálu služby, heslu a interaktivním tokům.
Chránit informace o připojení Nechte přihlašovací údaje a nastavení připojení mimo aplikační kód.
Vždy šifrované Chraňte citlivé sloupcové hodnoty před databázovým systémem.
Always Encrypted s využitím zabezpečených enkláv Provádějte bohaté operace na šifrovaných datech s zabezpečenou enklávou.

Získání a aktualizace dat

Článek Description
Příkazy a parametry Spouštějte parametrizované SQL příkazy a uložené procedury.
Datové adaptéry a čtečky dat Streamujte sady výsledků nebo doplňujte nesouvislé datové struktury.
Transakce a souběžnost Používejte lokální a distribuované transakce a řízení souběžnosti.
Získání informací o schématu databáze Objevte kolekce schémat a omezení.
Operace hromadného kopírování Efektivně načítejte velké datové sady pomocí SqlBulkCopy.
Parametry tabulkového typu Odesílejte více řádků do parametrizovaného příkazu nebo uložené procedury.
asynchronní programování Používejte asynchronní spojení, příkazy a datové operace.
Více aktivních sad výsledků (MARS) Propleťte více dávek na jednom připojení.

Datové typy

Článek Description
Mapování datových typů ADO.NET Mapování typů modulu Common Language Runtime (CLR) na typy zprostředkovatele a SQL Serveru.
Datové typy SQL Server Pracujte s hodnotami a System.Data.SqlTypes typy specifickými pro SQL Server.
JSON data Odesílejte a načítejte datový typ SQL Serverjson.
Vektorová data Odesílejte a získávejte vektorové hodnoty.
XML data Čtení, zápis a parametrizace XML hodnot.
Binární a velkohodnotová data Streamujte a aktualizujte binární, FILESTREAM a data s velkou hodnotou.

Spolehlivost a diagnostika

Článek Description
Konfigurovatelná logika opakování Opakujte přechodná selhání připojení a příkazů pomocí omezených zásad.
Vysoká dostupnost a zotavení po havárii Připojte se k skupinovým posluchačům dostupnosti a partnerům pro failover.
Diagnostické čítače Sledujte aktivní spojení, spojená spojení a další metriky ovladačů.
Povolit sledování zdrojů událostí Zaznamenejte podrobné události ovladače pro účely diagnostiky.
Sledování dat Sledujte operace ADO.NET a přístup k datům.
Průvodce odstraňováním potíží s SqlClient Diagnostikujte běžné problémy s připojením a ovladači.
Oznámení dotazů Přijímejte upozornění, když se výsledky dotazů změní.

funkce SQL Server

Článek Description
Funkce a ADO.NET SQL Serveru Prohlédněte si specifické funkce pro SQL Server dostupné prostřednictvím SqlClient.
Místní databáze Připojte se k instancím SQL Server Express LocalDB.
Zjišťování a klasifikace dat Čtení metadat klasifikace citlivosti ze sad výsledků.

Referenční informace a zdroje

Článek Description
Microsoft. Data SqlClient API reference Prohlédněte si referenční .NET API pro ovladač.
Přepínače AppContext Nastavte kompatibilitu a bezpečnostní chování.
Najděte další informace o SqlClient Najděte zdrojový kód, podporu a komunitní zdroje.

Související obsah

  • Last updated on