Kapcsolati sztringek a Microsoft.Data.SqlClienthez

A Microsoft.Data.SqlClient kapcsolati karakterlánc egy keyword=value párok listája, amelyeket pontosvessző választ el. Add át a(z) SqlConnection vagy SqlConnectionStringBuilder számára:

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

A kapcsolati karakterlánc négy kérdésre válaszol:

1. Melyik szervert és adatbázist használja az alkalmazás?
2. Melyik azonosítóval fut az alkalmazás?
3. Hogyan validálja az ügyfél a szerver tanúsítványt?
4. Milyen kapcsolati viselkedésre van szükség a munkaterhelésnek?

Ez a cikk azokat a választásokat és azokat a szabályokat tárgyalja, amelyeket az illesztőprogram a szöveg olvasásához használ. Minden kulcsszóhoz, szinonimájához és alapértelmezett értékéhez lásd a Kapcsolati opciókat. A kapcsolati sztringek létrehozásához és módosításához a kódban lásd: Kapcsolatisztring-készítők.

Válassz hitelesítési mintát

Használd azt a tervezési mintát, ami illeszkedik az üzembe helyezéshez. Cseréld le minden helykitöltőt, például <server>-t, a saját értékeddel.

Environment	Pattern	Csatlakozási karakterlánc
SQL Server Windows rendszeren tartományi vagy helyi Windows-identitással	Integrált Windows-hitelesítés	Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Az alkalmazás Azure-ban hosztolt és Azure SQL-hez csatlakozik	Microsoft Entra ID felügyelt identitás	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Fejlesztői munkaállomás kapcsolódása az Azure SQL-hez	Microsoft Entra ID alapértelmezett hitelesítőadat-lánca	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Fejlesztői munkaállomás csatlakozik SQL adatbázishoz a Microsoft Fabric-ben	Microsoft Entra ID alapértelmezett hitelesítőadat-lánca	Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Azure SQL-hez csatlakozó interaktív asztali eszköz	Microsoft Entra ID interaktív hitelesítés	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
Olyan környezet, amely SQL hitelesítést igényel	Felhasználónév és jelszó egy titkos áruházból	Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

A Windows integrált hitelesítés a folyamat identitásával csatlakozik. Egy asztali vagy konzolos alkalmazás esetén általában a bejelentkezett felhasználó az. Webalkalmazásnál vagy Windows szolgáltatásnál ez az alkalmazáspool vagy szolgáltatásfiók. A megszemélyesítés megváltoztathatja az identitást. Biztosíts bejelentkezési és adatbázis-jogosultságot annak az identitásnak, amit az alkalmazásod valójában használ.

Ez a három Windows integrált hitelesítési forma egyenértékű:

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

Ha egy string beállít Integrated Security=true és beállítja User ID és Password, az illesztőprogram Windows authentication-t használ, és figyelmen kívül hagyja a felhasználónevet és jelszót.

Microsoft. Data.SqlClient 7.0 és újabb verziókhoz a driver-által biztosított Microsoft Entra ID hitelesítési módszerekhez verziópárosított Microsoft.Data.SqlClient.Extensions.Azure csomagra van szükség. Nincs szükség erre a csomagra, amikor az alkalmazáskód hozzáférési tokent vagy hozzáférési token-visszahívást biztosít.

Az elfogadott Authentication értékeket lásd: Hitelesítési opciók. A hitelesítéshez adatbázis-felhasználók, jogosultságok és identitáskonfiguráció is szükséges a szerveren. A beállítási lépésekért lásd: Microsoft Entra ID hitelesítés és SQL Server hitelesítés.

Határozd meg a szervert és az adatbázist

Server és Database a legolvashatóbb kulcsszónevek. Az építő ezeket kanonikus megfelelőikként, Data Source és Initial Catalog formában írja fel. Mind a négy név működik egy kapcsolati karakterlánc-ben.

Állítsuk Server be az alábbi formák egyikére:

Form	Example	Használat
Hoszt neve	Server=sql.example.com	Az alapértelmezett példány a 1433-as porton.
Állomásnév és port	Server=tcp:sql.example.com,1433	Egy konkrét TCP port. A portot vesszóval választd el, ne kettősponttal.
Megnevezett példány	Server=sql.example.com\SALES	Egy elnevezett példány. Az illesztőprogram lekérdezi a portot az UDP 1434-es porton futó SQL Server böngésző szolgáltatástól.
Helyi szerver	Server=(local) vagy Server=.	A helyi számítógép alapértelmezett példánya.
LocalDB	Server=(localdb)\MSSQLLocalDB	SQL Server Express LocalDB Windows rendszeren. A kapcsolat nincs titkosítva, még a -vel Encrypt=Mandatorysem, és Encrypt=Strict meghibásodik.
Elnevezett cső	Server=np:\\sql.example.com\pipe\sql\query	Egy nevelt csőkapcsolat Windows-on.

Használj tcp:, egy teljesen minősített hosztnevet és explicit portot éles környezetben. Használj DNS-nevet, amely megegyezik a szerver tanúsítványával, ne IP-címet, mert a tanúsítvány érvényesítése összehasonlítja a kapcsolati karakterlánc szervernevét a tanúsítványban szereplő nevekkel.

Amikor SQL-hitelesítéssel és user@servername formátumú felhasználónévvel csatlakozol az Azure SQL Database-hez, a servername résznek meg kell egyeznie a Server szerverrel.

Elérhetőségi csoport figyelője vagy feladatátvevő fürtpéldány esetén tekintse át a elemet a Multi Subnet Failover című részben is.

Titkosítás és tanúsítvány ellenőrzés konfigurálása

A Encrypt kulcsszó mindenesetre a következő értékeket fogadja el:

Value	Építő érték	Meaning
Strict	Strict	TDS 8.0-t használ. Titkosítja a kapcsolatot a bejelentkezés előtt, és mindig érvényesíti a szerver tanúsítványt.
\, \, \	True	Titkosítja a kapcsolatot. Ez az alapértelmezett érték.
\, \, \	False	Az egész kapcsolatot csak akkor titkosítja, ha a szerver titkosítást igényel. Ha a szerver támogatja a titkosítást, de nem követeli meg, csak a bejelentkezési csomagot titkosítja.

Akkor használd, Strict amikor a szerver támogatja a TDS 8.0-t, és rendelkezik egy tanúsítvánnyal, amit az ügyfél ellenőrizhet. Az Azure SQL Database és az SQL adatbázis a Microsoft Fabricben támogatják ezt. Egy LocalDB kapcsolat nincs titkosítva, még a -vel Mandatorysem, és Strict meghibásodik.

Az Encrypt és Trust Server Certificate értékek a következőképpen kombinálódnak:

Titkosítás	Megbízhatósági kiszolgáló tanúsítványa	Result
Optional	false	Ha a szerver titkosítást igényel, az egész kapcsolat titkosított, és a szerver tanúsítványának érvényesnek kell lennie. Ellenkező esetben a kapcsolat meghibásodik. Amikor a szerver támogatja a titkosítást, de nem követeli meg, csak a bejelentkezési csomagot titkosítják, és az illesztőprogram nem érvényesíti a szerver tanúsítványát, hacsak a kapcsolat nem használ AccessToken vagy AccessTokenCallback. Ha a szerver nem támogatja a titkosítást, semmi sem titkosított.
Optional	true	Amikor a szerver titkosítást igényel, a teljes kapcsolat titkosított. Ha a szerver támogatja a titkosítást, de nem követeli meg, csak a bejelentkezési csomag van titkosítva. Az illesztőprogram nem érvényesíti a szerver tanúsítványt.
Mandatory	false	A titkosítás csak akkor történik meg, amikor a szerver tanúsítványának érvényesítése sikeres. Ellenkező esetben a kapcsolat meghibásodik.
Mandatory	true	Titkosítás mindig történik, de a meghajtó nem érvényesíti a szerver tanúsítványt.
Strict	Ignored	A titkosítás mindig megtörténik, és a szerver tanúsítványát érvényesíteni kell. Ellenkező esetben a kapcsolat meghibásodik.

Ne állítsa be az Trust Server Certificate=true-t az éles környezetbeli csatlakozási hiba javítására. Titkosítja a csatornát, de nem erősíti meg a kiszolgáló azonosságát. Korlátozd olyan fejlesztői környezetekre, ahol megbízható tanúsítvány nem érhető el.

Ha a(z) Data Source mezőben szereplő kiszolgálónév nem egyezik a tanúsítvánnyal, állítsd a(z) Host Name In Certificate értékét a tanúsítványban szereplő névre. Az SqlClient csak akkor ellenőrzi, ha a kiszolgáló neve nem egyezik, és nem alkalmaz tanúsítványrögzítést. Csak egy adott tanúsítvány elfogadásához állítsa a Server Certificate értékét egy PEM-, DER- vagy CER-fájl elérési útjára:

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

A teljes validációs szabályokért lásd: Titkosítás és tanúsítvány validálás.

Használjon kapcsolat-kötegelést

Alapértelmezés szerint be van kapcsolva. Amikor megnyitod az SqlConnection, a meghajtó egy fizikai kapcsolatot vesz fel egy olyan poolból, amely illeszkedik a kapcsolathoz. Amikor lezárod vagy eldobod a kapcsolatot, a fizikai kapcsolat visszatér a medencéhez a zárás helyett. A feltárt nyílás áthagyja a hálózati kapcsolatot, a TLS kézfogást és a bejelentkezést.

Kövesse az alábbi szabályokat:

• Nyiss egy kapcsolatot közvetlenül azelőtt, hogy szükséged lenne rá, és azonnal dobd el a cél után, vagy usingawait using. Az a kapcsolat, amely nincs felszabadítva, kikölcsönözve marad, és a kapcsolatkészlet kifogyhat.

• Egyszer építsd a kapcsolati karakterlánc-et az indításkor, és használd újra. A pool kulcs tartalmazza a kapcsolati karakterlánc pontos szövegét, így egy másik kulcsszósorrend, egy szinonim vagy egy kérésenkénti érték, például egy request ID vagy felhasználónév külön poolt hoz létre. Az építő egy kanonikus formát ír. További információért lásd: Keep one canonical kapcsolati karakterlánc.

• Számítson külön poolra minden Windows-identitáshoz integrált hitelesítés esetén, minden SqlCredential példányhoz és minden AccessToken értékhez. Használj egy driver-által biztosított Authentication módszert vagy egy újrahasznált AccessTokenCallback módszert ahelyett, hogy minden csatlakozásnál AccessToken állítanád be.

• Keresd azokat a kapcsolatokat, amelyeket nem kezelsz, mielőtt emeled Max Pool Size, ami alapértelmezettben 100-ra kerül. Amikor minden kapcsolat használatban van, Open legfeljebb Connect Timeout ideig vár, majd InvalidOperationException kivételt dob:

  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.
  

• Tervezd meg a szerver kapacitását minden poolnak. Minden folyamat vagy a .NET Framework minden alkalmazástartománya saját készletekkel rendelkezik. A szerverhez való csatlakozások száma elérheti a Max Pool Size értéket, megszorozva az egyes folyamatokban lévő poolokkal és az alkalmazáspéldányok számával.

• Ne próbálj Pooling=false megkerülni egy csoportosítási problémát. Minden megnyitáskor teljes bejelentkezés történik.

Ha túl sokáig üresen maradnak, a feloldott kapcsolatok lezárására lásd: Limit connection idle time. Pool kulcsok, méretezés, törlés és tranzakciók esetén lásd: SQL Server connection pooling.

Külön kapcsolati és parancsbeállítások

Egy kapcsolati karakterlánc szabályozza a kapcsolat létrehozását és a munkamenet viselkedését. Egy parancs irányít egy SQL műveletet.

Követelmény	Konfigurálás:
Megengedett idő, hogy kapcsolatot teremtsünk vagy megszerezzünk a medencéből	Connect Timeout kulcsszó
A kapcsolaton lévő parancsok alapértelmezett időkorlátja	Command Timeout kulcsszó
Időkorlát egy parancsra	CommandTimeout
A hívó fél általi lemondás	CancellationToken átadva az aszinkron metódusoknak
Újrapróbálkozás szabályzata egy kapcsolat megnyitásához vagy parancs futtatásához	Konfigurálható újrapróbálkozási logika a(z) SqlConnection vagy SqlCommand esetén

A hosszabb időkorlát nem újrapróbálás logika. Egy időtúllépés egy várakozást korlátoz. Egy újrapróbálkozás újabb próbálkozást indít, és annak korlátnak kell lennie, és biztonságosan megismételhetjük.

Jelentse az alkalmazás azonosítóját

Application Name beállítja azt a nevet, amelyen keresztül a szerver jelent APP_NAME(). Használjon egy stabil nevet minden telepített munkaterheléshez. Az alkalmazás számára kapcsolatokat megnyitó keretrendszerek és eszközök is jelenthetik magukat a RegisteredApplication tulajdonságon keresztül, amelynek nincs kapcsolati karakterlánc kulcsszava. További információért lásd: Az alkalmazásidentitás jelentése.

Biztonságosan építsd a kapcsolati láncokat

Használd SqlConnectionStringBuilder , amikor a kód hozzáad vagy módosít egy értéket. Ne fűzzön be megbízhatatlan szöveget egy kapcsolati karakterláncba, mert az abban szereplő pontosvessző kulcsszót adhat hozzá vagy helyettesíthet. Az építő érvényesíti az értékeket, a szinonimákat kanonikus kulcsszavakhoz rendeli, és idézi minden értéket, hogy az érték ne tudjon kulcsszavakat hozzáadni. Például lásd: Kapcsolati stringépítők.

Tárolja a kapcsolati információkat a kódon kívül

Kapcsolódási láncok betöltése az alkalmazás konfigurációs rendszeréből. A .NET alkalmazások általában környezeti változókat, felhasználói titkokat használnak helyi fejlesztéshez, Azure App Configuration-t és Azure Key Vault-ot.

Kövesse az alábbi szabályokat:

• Ne kötelezz el jelszavakat, klienstitkokat, hozzáférési tokeneket vagy gyártási kapcsolati stringeket.
• Előnyben részesítek egy hitelesítési módszert, amelyhez nem kell jelszó a kapcsolati karakterlánc-ben.
• Korlátozd a konfigurációs forráshoz való hozzáférést.
• Forgatd a tárolt titkokat, és indítsd újra vagy frissítsd azokat az alkalmazásokat, amelyek gyorsítótárt tárolnak.
• Ne írj kapcsolati láncokat naplókhoz, kivételekhez, nyomokhoz vagy telemetriához.
• A Leave Persist Security Info=false, az alapértelmezett opció, hogy egy megnyitott kapcsolat ne tegye fel a jelszót a tulajdonságán keresztül ConnectionString .

.NET konfigurációs szolgáltatókról lásd: Konfiguráció a .NET-ben. További vezérlőkért lásd: Védelem a kapcsolati információk.

Elemzési szabályok

A sofőr ezeket a szabályokat alkalmazza:

• A kulcsszavak nem nagybetűérzékenyek. DATABASE, Database, és database ugyanaz a kulcsszó.
• Sok kulcsszónak vannak szinonimái. Server és Data Source ugyanazt az értéket állítja be. A Kapcsolati beállítások cikk felsorolja az egyes kulcsszavak szinonimáit.
• Ha egy kulcsszó többször is megjelenik, az utolsó érték nyer. A szinonimák ugyanaznak a kulcsszónak számítanak.
• A meghajtó figyelmen kívül hagyja a szószavak és idézettelen értékek körüli szóközöket.
• A mögöttes szemesköple opcionális.
• Egy kulcsszó, amelyet az illesztőprogram nem ismer fel, ArgumentException kivételt vált ki a következő üzenettel: Keyword not supported.

Az értékek lehetnek kis- és kis- desszenciálosak, a kulcsszótól függően. A jelszó megkülönbözteti a kis- és nagybetűket. Encrypt=STRICT és Encrypt=strict ugyanazok.

Ez a program megmutatja, hogyan normalizálja a builder a kulcsszavakat, hogyan oldja fel a duplikációt, és hogyan idézi a speciális karaktereket. A .NET Framework fül a C# 7.3-at használja. Ha szeretnél létrehozni egy olyan projektet, amely a mintákat futtatja, lásd: A projekt létrehozása.

.NET

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

.NET-keretrendszer

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // 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}");
    }
}

A kimenet a következő:

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

Az első sor minden szinonimát a kanonikus kulcsszavakkal helyettesít: server , DATABASEData Source, Initial CataloguidUser ID, és .Connect Timeouttimeout

Idézetértékek

Zárj be egy értéket kétszeres idézőjelekkel (") vagy idézőjelekkel ('), ha az egy szóespult tartalmaz, szóközzel kezdődik vagy végződik, vagy idézőjelgel kezdődik vagy végződik. Egy idézett érték belsejében kétszer írd be a mellékelt idézőjelet.

Value	Kapcsolati sztring űrlap
a;b	Password="a;b"
abc'	Password="abc'"
say "hi"	Password='say "hi"'
a;b'c"d	Password="a;b'c""d"

Az idézési szabályokat könnyű elhibázni. Állítsd be az értékeket a(z) SqlConnectionStringBuilder tulajdonságain keresztül, és hagyd, hogy a builder idézőjelek közé tegye őket. További információért lásd: Biztonságosan építsünk kapcsolati karakterláncokat.

Meghatározni a Boole-értékeket

Azok a kulcsszavak, amelyek Boole-értéket vesznek fel, elfogadják true, false, yes és no értékeket, kis- és nagybetűtől függetlenül. Integrated Security szintén elfogadja sspi-t, ami azt jelenti, hogy true. Az építő írja True , vagy False.

Használj más tényezők kulcsszavait

Microsoft. Data.SqlClient nem fogad el ODBC vagy OLE DB kulcsszavakat, mint Driver és Provider. Ezeket a kulcsszavakat távolítsd el, amikor egy kapcsolati karakterlánc-et egy másik illesztőprogramból helyezel át. System.Data.SqlClient a kapcsolati karakterláncok működnek a Microsoft.Data.SqlClientben, ezekkel a különbségekkel:

• Encrypt alapértelmezés szerint Mandatory a Microsoft.Data.SqlClient-ben. A megbízható tanúsítvánnyal nem rendelkező szerver nem felel meg a tanúsítvány-ellenőrzésnek. Telepíts egy megbízható tanúsítványt a szerverre.
• A .NET-en Network Library, Connection Reset és Transparent Network IP Resolution nem támogatottak. Távolítsa el őket.
• Context Connection=true nem támogatott.
• Asynchronous Processing nem támogatott kulcsszó, és ArgumentException hibát eredményez. Távolítsa el. Az aszinkron módszerek nélküle működnek.
• Type System Version=SQL Server 2000 nem támogatott. A kapcsolat megteremtése a következőt eredményezi: ArgumentException Használd Latest, SQL Server 2012, SQL Server 2008, vagy SQL Server 2005.

Kapcsolódó tartalom

• Használd a Microsoft-ot. Data.SqlClient egy .NET alkalmazásban
• Kapcsolati beállítások
• Kapcsolati karakterlánc készítők
• Kapcsolódni egy adatforráshoz
• SQL Server connection pooling
• Microsoft Entra ID-hitelesítés
• Titkosítás és tanúsítvány ellenőrzése
• SQL Server Express felhasználói példányok
• Az SqlClient-illesztő támogatási életciklusa