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, SQL database v Microsoft Fabric a Warehouse 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. Poskytuje spojení, příkazy, zpracování výsledků, transakce, hromadné kopírování a specifické funkce pro SQL Server pro .NET aplikace.

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é hostitel nastavuje, jako jsou appsettings.json, proměnné prostředí, Azure App Configuration a nastavení podporovaná Key Vault. Konfigurace kombinuje tyto vlastnosti:

  • Zabezpečení transportní vrstvy (TLS).
  • Spravovaná identita
  • Odolnost nečinného připojení.
  • Opakování počátečního připojení pomocí konfigurovatelné logiky opakovaných pokusů (CRL) se strukturovaným logováním.
  • Opakování na úrovni příkazu pro přechodné chyby, které se vyskytnou uprostřed dotazu.
  • Rychlé obnovení skupiny převzetí služeb při selhání.
  • Asynchronní volání, která přijímají token pro zrušení.

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.

Úryvek předpokládá projekt, který cílí na .NET 8 nebo novější verze a odkazuje na balíčky Microsoft.Data.SqlClient a Microsoft.Data.SqlClient.Extensions.Azure verze 7.1.1. Hostitel, například .NET Generic Host nebo ASP.NET Core, dodá ILogger a IConfiguration a konfigurace dodá název serveru v Sql:Server a název databáze v 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;
}

Metoda vrací název databáze, ke které se připojila, a loguje Connected to database <database>. Když dojde k opakování, zaznamená se také jedno varování při každém opakování spolu s výjimkou, která jej vyvolala.

Jak funguje každá část úryvku:

  • Cíle: Jakýkoli koncový bod SQL Database Engine nakonfigurovaný pro ověřování Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, SQL databáze v Microsoft Fabric a SQL Server 2022 a novější verze na Azure Virtual Machines nebo s podporou Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Zvolí šifrování TDS 8.0. Vyžaduje verze SQL Server 2022 a novější, Azure SQL Database, Azure SQL Managed Instance nebo SQL databázi v Microsoft Fabric. Použijte SqlConnectionEncryptOption.Mandatory pro starší servery.
  • ActiveDirectoryManagedIdentity: Funguje pouze tam, kde je dostupná spravovaná identita, například Azure App Service, Azure Functions nebo Azure virtuální stroj. Pro lokální vývoj použijte SqlAuthenticationMethod.ActiveDirectoryDefault, který zkouší Azure CLI, přihlášení do Visual Studio a další zdroje ověřovacích údajů. Nechte to mimo produkční prostředí, protože zkoumání každého zdroje zpomaluje připojení. Další informace viz Použít výchozí ověřování.
  • MultiSubnetFailover = true: Pokouší se o TCP spojení ke všem vyřešeným IP adresám paralelně a použije první úspěšné spojení, čímž se vyhne pomalému sekvenčnímu procházení jednotlivých IP adres. Nastavte ho pro Azure SQL Database, Azure SQL Managed Instance, SQL databázi v Microsoft Fabric, naslouchací procesy skupiny dostupnosti a instance clusteru s podporou převzetí služeb při selhání. Je to bezpečné na cílech s jednou IP adresou. Tato funkce není podporována pro pojmenované instance, protokoly jiné než TCP, instance s více než 64 IP adresami ani pro zrcadlení databází, které je již zastaralé. 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í.
  • ConnectRetryCount = 3 a ConnectRetryInterval = 10: Ovladač zopakuje pokus při způsobilých přechodných selháních během Open() a při dalším příkazu znovu připojí přerušené nečinné spojení. Výchozí počet je 1. Tři pokusy s desetisekundovým odstupem pokryjí i delší přenastavení nebo převzetí služeb při selhání. Ovladač zvýší hodnotu z 1 na 2 pouze tehdy, když název serveru končí známou doménou Azure SQL, například .database.windows.net, takže vlastní DNS alias zůstane na hodnotě 1.
  • openRetry: Přiřazeno k SqlConnection.RetryLogicProvider, přidává exponenciální odmlku kolem Open(). Driver zastaví své vnitřní pokusy po vypršení platnosti ConnectTimeout, takže v nejhorším případě předtím, než OpenAsync vyvolá výjimku, proběhne pět pokusů po dobu až 30 sekund, plus prodleva mezi pokusy. Každý pokus o opětovné připojení během nečinnosti také spustí celou openRetry zásadu, a když tato zásada vyčerpá své pokusy, obnovení po nečinnosti se ukončí.
  • Serverless auto-pause: Pro Azure SQL Database serverless zvyšte ConnectTimeout na alespoň 60 sekund. První Open() může selhat s chybou 40613, zatímco se databáze obnovuje, a openRetry to zkusí znovu. Timeout na straně klienta se objeví jako chyba -2, která se nezkouší znovu, takže každý pokus o připojení musí trvat déle než obnovení. Více informací naleznete v části Automatické pozastavení a automatické obnovení.
  • commandRetry: Připojte ho k SqlCommand.RetryLogicProvider pouze tehdy, když je bezpečné příkaz znovu přehrát: operace čtení, MERGE chráněné přirozeným klíčem, upserty prostřednictvím uložené procedury a další idempotentní operace. Přeskočí opakovaný pokus v rámci transakce, takže aplikační kód musí vícepříkazové transakce zkusit znovu. ExecuteReader a ExecuteScalar opakují pouze chyby vrácené před zahájením první sady výsledků. ExecuteNonQuery Zkusí celé volání znovu.
  • Seznam přechodných chyb: Nastavení TransientErrors nahrazuje vestavěný seznam. Pro rozšíření použijte SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 a novější).
  • Retrying Událost: Retrying spouští se před každým opakovaným pokusem s počtem opakování, dalším zpožděním a dosavadními výjimkami. Směrujte to do ILogger nebo svého telemetrického potrubí.
  • Výjimky: Metoda nezachytává výjimky. Vyčerpaný poskytovatel vyvolá AggregateException s výjimkou z každého pokusu. Netranzientní chyba se propaguje jako původní výjimka. Volající to zaznamená jednou spolu se zbytkem kontextu požadavku.
  • Zrušení: CancellationToken zastaví čekání poskytovatele mezi pokusy. Nepřeruší to čekání řidiče ConnectRetryInterval během jednoho Open pokusu o akci. Pro více informací viz Asynchronní programování.
  • Životnost poskytovatele: Úryvek vytváří poskytovatele opakovaných pokusů při každém volání, aby zůstali samostatní. V aplikaci je vytvořte jednou a znovu použijte.

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

Naučte se základní úkoly přístupu k datům

Po připojení používejte tyto články v pořadí:

  1. Proveďte příkaz pro výběr výsledného tvaru a spusťte Transact-SQL (T-SQL).
  2. Nastavte parametry tak, aby odpovídaly kontraktu databáze.
  3. Získávejte data pomocí SqlDataReader pro zpracování řádků a více výsledků.
  4. Upravujte data pomocí uložených procedur s využitím výstupních parametrů a návratových hodnot.
  5. Použijte asynchronní programování a zrušení k přidání zrušení volajícího a omezených časových limitů.
  6. Řešte chyby a zprávy ještě před tím, než přidáte opakované pokusy nebo produkční diagnostiku.

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.
  • 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.
  • Sdílení připojení: Ve výchozím nastavení zapnuto. Dobrovolný V2 pool je ve fázi hodnocení.
  • 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ů.
  • Identita aplikace: Nastavte SqlConnection.RegisteredApplication pro identifikaci vaší knihovny nebo nástroje pro SQL Server (Microsoft.Data.SqlClient 7.1 a novější).

Začínáme

Článek Description
Začněte s ovladačem SqlClient Nastavte projekt, vytvořte databázi, připojte se, dotazujte a přidejte odolnost spojení.
Nainstalujte, aktualizujte a nasazujte Microsoft. Data.SqlClient Nainstalujte balíčky NuGet, vyberte verzi, aktualizujte ovladač a připravte výstup z nasazení.
Životní cyklus podpory Prohlédněte si podporované verze ovladačů a data podpory.
Migrace ze System.Data.SqlClient na Microsoft. Data.SqlClient Aktualizujte odkazy na balíčky, jmenné prostory, konfiguraci a změněné chování ovladače.
Obor názvů Microsoft.Data.SqlClient a kompatibilita Pochopte, jak SqlClient implementuje ADO.NET a jak je kompatibilní se System.Data.SqlClient, .NET a SQL Server.
Co je nového v Microsoftu. Data.SqlClient Najdete aktuální vydání, zásadní změny při hlavních aktualizacích a poznámky k vydáním upstreamu.

Konfigurace a připojení

Článek Description
Připojte se ke zdroji dat Otevírejte a spravujte spojení a reagujte na změny stavu připojení.
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í.
Zpracování chyb a zpráv Zachycujte chyby a dostávejte informační zprávy.

Autentizace a zabezpečení

Článek Description
Osvědčené postupy v oblasti bezpečnosti pro Microsoft.Data.SqlClient 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
Vykonat příkaz 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.
Spouštějte více příkazů pomocí SqlBatch Pošlete uspořádanou sbírku příkazů a zpracujte jejich výsledky.
Streamovaná data Přenášejte velké binární, textové, XML a JSON hodnoty bez ukládání celé hodnoty do bufferu.
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.
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ů SQL Server Mapujte typy SQL Server na typy .NET a System.Data.SqlTypes.
JSON data Odesílejte a získávejte datový typ SQL Server json.
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.
Čítače událostí v SqlClient Sledujte aktivní spojení, spojená spojení a další metriky ovladačů.
Povolit sledování zdrojů událostí Zaznamenejte podrobné události ovladače pro účely diagnostiky.
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í.
Úložiště GitHub Microsoft.Data.SqlClient Přečtěte si zdrojový kód ovladače, poznámky k vydání a ukázky.
Microsoft.Data.SqlClient ukázky Prohlédněte si ukázky rozhraní API ovladačů v jazyce C#.
repozitář .NET runtime na GitHubu Přečtěte si zdroj pro knihovny modulu runtime .NET.

Žádost o funkci

Chcete-li požádat o novou funkci, vytvořte issue v repozitáři GitHubu Microsoft.Data.SqlClient.

Související obsah

  • Poslední aktualizace v