Připojovací řetězce pro Microsoft.Data.SqlClient

Microsoft. Data.SqlClient připojovací řetězec je seznam keyword=value dvojic oddělených středníky. Předejte ji SqlConnection nebo SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

připojovací řetězec odpovídá na čtyři otázky:

  1. Jaký server a databázi aplikace používá?
  2. Pod jakou identitou aplikace běží?
  3. Jak klient ověřuje certifikát serveru?
  4. Jaké chování připojení pracovní zátěž vyžaduje?

Tento článek se zabývá těmito volbami a pravidly, která řidič používá při čtení textu. Pro každé klíčové slovo, jeho synonyma a výchozí nastavení viz Možnosti připojení. Pro vytváření a změnu spojovacích řetězců v kódu viz Tvůrci připojovacích řetězců.

Vyberte autentizační vzor

Použijte vzor, který odpovídá nasazení. Nahraďte každý zástupný symbol, například <server>, svou hodnotou.

Environment Pattern Připojovací řetězec
SQL Server na Windows s doménou nebo lokální identitou Windows Integrované ověřování systému Windows Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Application hostovaná v Azure a připojení k Azure SQL spravovaná identita Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Vývojářská pracovní stanice připojená k Azure SQL Microsoft Entra ID výchozí řetězec přihlašovacích údajů Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Pracovní stanice pro vývojáře připojující se k SQL databázi v Microsoft Fabric Microsoft Entra ID výchozí řetězec přihlašovacích údajů Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Interaktivní desktopový nástroj připojující se k Azure SQL Interaktivní autentizace Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
Prostředí, které vyžaduje SQL autentizaci Uživatelské jméno a heslo z tajného úložiště Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

Integrovaná autentizace ve Windows se připojuje jako identita procesu. U desktopové nebo konzolové aplikace je to obvykle přihlášený uživatel. U webové aplikace nebo služby Windows je to aplikační pool nebo servisní účet. Předstírání může změnit identitu. Udělte přihlašovací a databázová oprávnění k identitě, kterou vaše aplikace skutečně používá.

Tyto tři formy integrované autentizace ve Windows jsou ekvivalentní:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Pokud řetězec nastaví Integrated Security=true a také nastaví User ID a , Passwordovladač používá Windows authentication a ignoruje uživatelské jméno a heslo.

Microsoft. Data.SqlClient 7.0 a novější verze potřebují balíček s verzní shodou Microsoft.Data.SqlClient.Extensions.Azure pro autentizační metody Microsoft Entra ID poskytované ovladačem. Tento balíček nepotřebujete, když aplikační kód poskytuje přístupový token nebo callback přístupového tokenu.

Pro přijímané Authentication hodnoty viz Možnosti autentizace. Autentizace také vyžaduje uživatele databáze, oprávnění a konfiguraci identity na serveru. Pro kroky nastavení viz Microsoft Entra ID autentizace a SQL Server autentizace.

Specifikujte server a databázi

Server a Database jsou nejčitelnější názvy klíčových slov. Sestavovač je zapisuje jako jejich kanonické ekvivalenty, Data Source a Initial Catalog. Všechny čtyři názvy fungují v připojovacím řetězci.

Nastavte Server na jednu z těchto forem:

Form Example Využití
Název hostitele Server=sql.example.com Výchozí instance na portu 1433.
Název hostitele a port Server=tcp:sql.example.com,1433 Specifický TCP port. Port oddělte čárkou, ne dvojtečkou.
Pojmenovaná instance Server=sql.example.com\SALES Pojmenovaná instance. Ovladač žádá službu SQL Server Browser na UDP portu 1434 o číslo portu.
Lokální server Server=(local) nebo Server=. Výchozí instance na lokálním počítači.
LocalDB Server=(localdb)\MSSQLLocalDB SQL Server Express LocalDB na Windows. Připojení není zašifrované, ani s Encrypt=Mandatory, a Encrypt=Strict selže.
Pojmenovaný kanál Server=np:\\sql.example.com\pipe\sql\query Připojení k pojmenované rouře ve Windows.

Použijte v produkci jako plně kvalifikované hostitelské jméno tcp: a explicitní port. Použijte DNS jméno, které odpovídá serverovému certifikátu, nikoli IP adrese, protože ověřování certifikátů porovnává název serveru v připojovací řetězec s názvy v certifikátu.

Když se připojíte k Azure SQL Database pomocí SQL autentizace a uživatelského jména ve formuláři user@servername, musí část servername odpovídat serveru v Server.

Pro skupinový naslouchací proces dostupnosti nebo instanci clusteru s podporou převzetí služeb při selhání také zkontrolujte Multi Subnet Failover v možnostech připojení.

Konfigurace šifrování a ověřování certifikátů

Klíčové Encrypt slovo přijímá v každém případě následující hodnoty:

Value Hodnota konstruktoru Meaning
Strict Strict Používá TDS 8.0. Šifruje spojení před přihlášením a vždy ověřuje certifikát serveru.
Mandatory, true, yes True Šifruje spojení. Tato hodnota je výchozí.
Optional, false, no False Celé spojení šifruje pouze tehdy, když server vyžaduje šifrování. Když server podporuje šifrování, ale nevyžaduje ho, šifrujte pouze přihlašovací paket.

Použijte Strict , když server podporuje TDS 8.0 a má certifikát, který klient může ověřit. Azure SQL Database a SQL database in Microsoft Fabric to podporují. Připojení LocalDB není šifrováno, ani s Mandatory, a Strict selže.

Hodnoty Encrypt a Trust Server Certificate se kombinují následovně:

Šifrování Důvěřovat certifikátu serveru Result
Optional false Když server vyžaduje šifrování, celé spojení je zašifrováno a certifikát serveru musí být ověřen. Jinak spojení selže. Když server podporuje šifrování, ale nevyžaduje ho, je šifrován pouze přihlašovací paket a ovladač nevaliduje serverový certifikát, pokud spojení nepoužívá AccessToken nebo AccessTokenCallback. Když server nepodporuje šifrování, nic se nešifruje.
Optional true Když server vyžaduje šifrování, celé spojení je zašifrováno. Když server šifrování podporuje, ale nevyžaduje ho, zašifruje se pouze přihlašovací paket. Ovladač nevaliduje certifikát serveru.
Mandatory false Šifrování probíhá pouze tehdy, když se platnost serverového certifikátu úspěšně ověří. Jinak spojení selže.
Mandatory true Šifrování vždy probíhá, ale ovladač nevaliduje certifikát serveru.
Strict Ignored Šifrování vždy probíhá a certifikát serveru musí být ověřen. Jinak spojení selže.

Nenastavujte Trust Server Certificate=true opravu chyby připojení v produkci. Šifruje kanál, ale identitu serveru nepotvrzuje. Omezte to na vývojová prostředí, kde není dostupný důvěryhodný certifikát.

Když název serveru Data Source v neodpovídá certifikátu, nastavte Host Name In Certificate název v certifikátu. SqlClient to kontroluje jen tehdy, když se název serveru neshoduje, a nepřipíná certifikát. Chcete-li přijmout pouze jeden konkrétní certifikát, nastavte Server Certificate na cestu k souboru PEM, DER nebo CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Úplná validační pravidla najdete v Šifrování a ověřování certifikátů.

Používejte sdružování připojení

Pooling je zapnutý ve výchozím nastavení. Když otevřete , SqlConnectionovladač převezme fyzické spojení z poolu, který odpovídá spojení. Když spojení zavřete nebo uvolníte, fyzické spojení se vrací do poolu místo aby se uzavřelo. Opětovné otevření z poolu přeskočí síťové připojení, TLS handshake a přihlášení.

Postupujte podle těchto pravidel:

  • Otevřete připojení těsně před tím, než ho potřebujete, a zlikvidujte ho hned, jakmile skončíte, s nebo usingawait using. Připojení, které není vyřazeno, zůstává vypnuté a bazén může dojít.

  • Vytvořte připojovací řetězec jednou při spuštění a znovu ho použijte. Klíč poolu obsahuje přesný text připojovací řetězec, takže jiný pořadí klíčových slov, synonymum nebo hodnota pro požadavek, jako je ID požadavku nebo uživatelské jméno, vytváří samostatný pool. Builder zapisuje jednu kanonickou formu. Pro více informací viz Keep one canonical připojovací řetězec.

  • Očekávejte samostatný pool pro každou identitu Windows pod integrovanou autentizací, každou SqlCredential instanci a každou AccessToken hodnotu. Použijte metodu dodanou Authentication ovladačem nebo znovu použitou metodu AccessTokenCallback místo nastavení AccessToken u každého připojení.

  • Hledejte spojení, která nejsou uvolněna, než zvýšíte Max Pool Size, což je výchozí hodnota 100. Když jsou všechna spojení v poolu v provozu, Open čeká maximálně Connect Timeout a pak vyvolá výjimku InvalidOperationException:

    Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

  • Plánujte kapacitu serverů pro každý pool. Každý proces, nebo každá aplikační doména v .NET Frameworku, má své vlastní pooly. Počet připojení k serveru může dosáhnout Max Pool Size násobeného počtem poolů v každém procesu a počtem instancí aplikace.

  • Nenastavujte Pooling=false kvůli obejití problému s poolingem. Při každém otevření se pak provede úplné přihlášení.

Pro uzavření spojení, která zůstávají příliš dlouho nečinná, viz Limit nečinnosti spojení. Pro klíče poolu, nastavení velikosti, clearing a transakce viz SQL Server connection pooling.

Samostatná nastavení připojení a příkazů

Připojovací řetězec řídí navázání připojení a chování relace. Příkaz ovládá jednu SQL operaci.

Requirement Konfigurace zapnutá
Čas vyhrazený na navázání spojení nebo získání spojení z poolu Connect Timeout klíčové slovo
Výchozí časový limit pro příkazy v rámci připojení Command Timeout klíčové slovo
Časový limit pro jeden příkaz CommandTimeout
Zrušení volajícím CancellationToken předaný asynchronním metodám
Politika opakování pro navázání spojení nebo spuštění příkazu Konfigurovatelná logika opakovaného pokusu pro SqlConnection nebo SqlCommand

Delší časový limit není totéž co logika opakovaných pokusů. Časový limit je jedno čekání. Opakovaný pokus spustí další pokus a musí mít jasně stanovené meze a být bezpečný pro opakování.

Uveďte identitu aplikace

Application Name nastavuje jméno, které server hlásí přes APP_NAME(). Pro každou nasazenou pracovní zátěž použijte jedno stabilní jméno. Frameworky a nástroje, které otevírají spojení pro aplikaci, se také mohou hlásit prostřednictvím vlastnosti RegisteredApplication, která nemá klíčové slovo připojovací řetězec. Pro více informací viz Nahlášení identity aplikace.

Bezpečně budujte spojovací řetězce

Použijte SqlConnectionStringBuilder , když kód přidá nebo změní hodnotu. Nespojujte nedůvěryhodný text do připojovací řetězec, protože středník v tomto textu může klíčové slovo přidat nebo nahradit. Builder ověřuje hodnoty, mapuje synonyma na kanonická klíčová slova a uzavírá každou hodnotu do uvozovek, aby hodnota nemohla přidat klíčová slova. Příklady viz Tvůrce připojovacích řetězců.

Ukládejte informace o spojení mimo kód

Načíst připojovací řetězce z konfiguračního systému aplikace. .NET aplikace běžně používají proměnné prostředí, uživatelská tajemství pro lokální vývoj, Azure App Configuration a Azure Key Vault.

Postupujte podle těchto pravidel:

  • Nepřikládejte hesla, klientská tajemství, přístupové tokeny ani produkční spojovací řetězce.
  • Upřednostněte autentizační metodu, která nevyžaduje heslo v připojovací řetězec.
  • Omezte přístup ke zdroji konfigurace.
  • Obměňte uložené tajné údaje a restartujte nebo znovu načtěte aplikace, které je ukládají do mezipaměti.
  • Nezapisujte spojovací řetězce do logů, výjimek, tras nebo telemetrie.
  • Nechte Persist Security Info=false výchozí, aby otevřené připojení nevystavovalo heslo prostřednictvím své vlastnosti ConnectionString.

Pro poskytovatele konfigurace .NET viz Konfigurace v .NET. Pro více kontrol, viz Ochrana informací o připojení.

Pravidla parsování

Řidič uplatňuje tato pravidla:

  • Klíčová slova nerozlišují velká a malá písmena. DATABASE, Database, a database jsou stejná klíčová slova.
  • Mnoho klíčových slov má synonyma. Server a Data Source mají nastavenou stejnou hodnotu. Článek Možnosti připojení uvádí synonyma pro každé klíčové slovo.
  • Když se klíčové slovo objeví vícekrát, vyhrává poslední hodnota. Synonyma se počítají jako stejné klíčové slovo.
  • Ovladač ignoruje mezery kolem klíčových slov a kolem necitovaných hodnot.
  • Závěrečný středník je volitelný.
  • Klíčové slovo, které ovladač nerozpozná, vyvolá ArgumentException se zprávou Keyword not supported.

Hodnoty mohou rozlišovat velikost písmen v závislosti na klíčovém slově. Heslo je citlivé na velikost písmen. Encrypt=STRICT a Encrypt=strict jsou stejné.

Tento program ukazuje, jak builder normalizuje klíčová slova, řeší duplicitu a uzavírá speciální znaky do uvozovek. Záložka .NET Framework používá C# 7.3. Informace o vytvoření projektu, který spouští ukázky, najdete v části Vytvoření projektu.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

Výstup je:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

První řádek ukazuje, že každé synonymum je nahrazeno jeho kanonickým klíčovým slovem: server , DATABASEData Source, User IDuidInitial Catalog, a .Connect Timeouttimeout

Hodnoty uvozovek

Uzavřete hodnotu do dvojitých uvozovek (") nebo jednoduchých uvozovek ('), pokud obsahuje středník, začíná nebo končí mezerou, nebo začíná či končí uvozovkami. Uvnitř uvedené hodnoty napište uvozovky dvakrát v přiložení.

Value Formulář připojovacího řetězce
a;b Password="a;b"
abc' Password="abc'"
say "hi" Password='say "hi"'
a;b'c"d Password="a;b'c""d"

Pravidla citování se snadno pokazí. Nastavte hodnoty prostřednictvím vlastností SqlConnectionStringBuilder a nechte builder, aby je uzavřel do uvozovek. Pro více informací viz Bezpečně vytvořit spojovací řetězce.

Specifikujte Booleovské hodnoty

Klíčová slova, která mají Booleovskou hodnotu, přijímají true, false, yesa , v nokaždém případě. Integrated Security také přijímá sspi, což znamená true. Builder píše True nebo False.

Používejte klíčová slova z jiných ovladačů

Microsoft. Data.SqlClient nepřijímá klíčová slova z ODBC nebo OLE DB jako Driver a Provider. Odstraňte tato klíčová slova, když přesouváte připojovací řetězec z jiného ovladače. System.Data.SqlClientSpojovací řetězce fungují v Microsoftu. Data.SqlClient, s těmito rozdíly:

  • Encrypt má ve výchozím nastavení hodnotu Mandatory v Microsoft.Data.SqlClient. Server bez důvěryhodného certifikátu neprojde ověřením certifikátu. Nainstalujte důvěryhodný certifikát na server.
  • Na .NET, Network Library, Connection Reset, a Transparent Network IP Resolution nejsou podporovány. Odstraňte je.
  • Context Connection=true není podporováno.
  • Asynchronous Processing není podporované klíčové slovo a hází ArgumentException. Odstraňte ho. Asynchronní metody fungují i bez něj.
  • Type System Version=SQL Server 2000 není podporováno. Vytvoření spojení vyvolá ArgumentException. Použijte Latest, SQL Server 2012, SQL Server 2008, nebo SQL Server 2005.

Související obsah

  • Poslední aktualizace v