Obor názvů Microsoft.Data.SqlClient a kompatibilita

Obor názvů Microsoft.Data.SqlClient obsahuje podporovaného poskytovatele dat .NET pro databáze kompatibilní se SQL Server. Vznikl jako fork System.Data.SqlClient a zachovává známý programovací model ADO.NET, a zároveň přináší nové funkce SQL Serveru nezávisle na runtime .NET.

Použijte Microsoft.Data.SqlClient pro nový vývoj.

Nainstalujte a importujte jmenný prostor

Přidejte balíček NuGet:

dotnet add package Microsoft.Data.SqlClient

Importujte jmenný prostor:

using Microsoft.Data.SqlClient;

Většina aplikací používá SqlConnection, SqlCommand, SqlParameter, SqlDataReader a SqlTransaction. Úplné veřejné rozhraní API najdete v dokumentaci Microsoft.Data.SqlClient API reference.

Vztah k ADO.NET

ADO.NET je model přístupu k datům zabudovaný v .NET. Definuje abstrakce nezávislé na poskytovateli v oboru názvů System.Data.Common a Microsoft.Data.SqlClient poskytuje konkrétní implementace.

Abstrakce ADO.NET Typ SqlClient Purpose
DbConnection SqlConnection Otevírá logické spojení s jednou databází.
DbCommand SqlCommand Provádí Transact-SQL (T-SQL) text nebo uloženou proceduru.
DbParameter SqlParameter Odesílá napsanou hodnotu odděleně od textu příkazu.
DbDataReader SqlDataReader Streamuje řádky výsledků ze serveru.
DbTransaction SqlTransaction Sdružuje příkazy do jedné transakce, která se jako jednotka potvrdí nebo vrátí zpět.
DbDataAdapter SqlDataAdapter Vyplňuje a aktualizuje odpojené objekty DataSet a DataTable.
DbBatch SqlBatch Odesílá více příkazů v jedné dávce pro podporované cílové frameworky.

Microsoft. Data.SqlClient také poskytuje API specifická pro SQL Server, například:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Podpora autentizace, šifrování a datových typů specifických pro SQL Server

Programujte proti abstrakcím ADO.NET, když knihovna musí podporovat více poskytovatelů databází. Používejte typy SqlClient, když aplikace cílí na SQL Server a potřebuje specifické funkce pro poskytovatele, jako je autentizace Microsoft Entra, Always Encrypted, hromadné kopírování, tabulkové parametry nebo konfigurovatelná logika opakovaných pokusů. Pokud musí zbytek aplikace zůstat nezávislý na poskytovateli, ponechte kód specifický pro poskytovatele za hranicí přístupu.

Přístup v připojeném a odpojeném režimu

Připojený režim přístupu udržuje spojení otevřené, zatímco se příkaz provádí a aplikace čte jeho výsledky. Typická žádost probíhá v tomto pořadí:

  1. Vytvořte SqlConnection z připojovací řetězec a otevřete ho.
  2. Vytvořte SqlCommand a přidejte hodnoty SqlParameter.
  3. Spusťte příkaz .
  4. Zpracujte skalární hodnotu, počet ovlivněných řádků nebo SqlDataReader.
  5. Uvolněte čtečku, příkaz a připojení.

Používejte připojený přístup pro většinu webových API, služeb, pracovníků a příkazových aplikací. SqlDataReaderstreamuje řádky a obvykle využívá méně paměti než načítání celého výsledku do .DataSet

Přístup bez připojení používá SqlDataAdapter ke kopírování dat do v paměti umístěného objektu DataSet nebo DataTable. Aplikace může připojení uzavřít během čtení nebo změny dat v paměti a poté se znovu připojit a odesílat aktualizace. Používejte ho pro datovou vazbu, relace a omezení v paměti, offline úpravy, které později sladíte, nebo pro existující aplikaci postavenou na DataAdapterech. Pro nové služby orientované na požadavky začněte s SqlCommand a SqlDataReader.

Životnost objektu a souběžnost

Otevřete a zlikvidujte SqlConnection pro každou jednotku práce. Poolování spojení znovu využívá základní fyzické spojení, takže nenechávejte jedno globální spojení otevřené po celou dobu existence aplikace. Zlikvidujte spojení, příkazy, čtečky, transakce a hromadně kopírujte objekty okamžitě. V asynchronním kódu použijte await using pro typy, které implementují IAsyncDisposable na cílové platformě, například SqlConnection a SqlDataReader na platformě .NET, a běžné using pro typy, které implementují pouze IDisposable, například SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader, a SqlTransaction nepodporují současné použití z více vláken. Každé souběžné operaci přiřaďte vlastní připojení a využijte sdružování připojení. Multiple Active Result Sets (MARS) umožňuje více než jednu aktivní sadu výsledků na spojení, ale nečiní objekty SqlClient bezpečnými pro vlákna.

Vztah k System.Data.SqlClient

System.Data.SqlClientje starší poskytovatel, který je dodáván s .NET Framework a staršími verzemi .NET. Microsoft.Data.SqlClient používá mnoho stejných typových názvů, ale má odlišné balíčky, jmenné prostory, výchozí nastavení, funkce a zásady podpory.

Neodkazujte na oba poskytovatele v novém aplikačním kódu. Typy se stejným názvem z obou balíčků nejsou zaměnitelné. Například System.Data.SqlClient.SqlConnection nelze předat tam, kde je vyžadováno Microsoft.Data.SqlClient.SqlConnection.

Migrace obvykle začíná přidáním balíčku Microsoft.Data.SqlClient a změnou odkazů na obor názvů, ale musíte také zkontrolovat šifrování spojení, parametry, konfiguraci, tranzitivní závislosti a chování za běhu. Postupujte podle migrace ze System.Data.SqlClient na Microsoft.Data.SqlClient před nasazením.

Kompatibilita verzí

Verze balíčku ovladačů je nezávislá na .NET verzi aplikace a verzi databázového enginu. Zkontrolujte všechny tři:

Component Co ověřit
Microsoft.Data.SqlClient Řada vydání je podporována a obsahuje funkce, které vaše aplikace používá.
.NET nebo .NET Framework Aplikace cílí na runtime podporované tímto vydáním ovladače.
Databáze kompatibilní se SQL Server Verze ovladače podporuje databázovou verzi a server podporuje jakoukoli požadovanou protokolovou funkci, například TDS 8.0.

Pro aktuální matice viz životní cyklus podpory ovladačů SqlClient.

Změny specifické pro verzi

Verze ovladačů mohou přidávat API, přesouvat volitelné závislosti a měnit bezpečné výchozí nastavení. Před každou menší nebo větší aktualizací si projděte změny.

Mezi příklady patří:

  • Ve verzi 4.0 bylo výchozí nastavení Encrypt změněno na true.
  • Verze 5.0 zavedla SqlConnectionEncryptOption a Encrypt=Strict pro TDS 8.0.
  • Verze 5.2 zavedla SqlBatch na podporovaných moderních cílech .NET.
  • Verze 7.0 přesunula autentizaci Microsoft Entra poskytovanou ovladačem do Microsoft.Data.SqlClient.Extensions.Azure.

Podívejte se na Co je nového v Microsoft.Data.SqlClient k odkazům na poznámky k vydání a shrnutí upgradu.

Některé funkce používají typy mimo hlavní jmenný prostor nebo volitelné balíčky.

Jmenný prostor nebo balíček Purpose
Microsoft.Data.SqlClient.Server Implementace SqlClient pro SqlDataRecord a SqlMetaData.
Microsoft.Data.SqlTypes Typy specifické pro SqlClient, jako jsou SqlFileStream, SqlJson a SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Silně typované datové části diagnostických událostí.
Microsoft.Data.SqlClient.Extensions.Azure Ovladačem poskytovaná autentizace Microsoft Entra pro verzi 7.0 a novější.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Azure Key Vault integration for Always Encrypted.

Neodvozujte požadavky na balíček jen z oboru názvů. Postupujte podle hlavního článku a informací o závislostech balíčku NuGet pro verzi ovladače, kterou používáte.

Související obsah

  • Poslední aktualizace v