Verbindingsstrings voor Microsoft. Data.SqlClient

Een Microsoft. Data. SqlClient verbindingsreeks is een lijst van keyword=value paren gescheiden door puntkomma's. Geef het door aan SqlConnection of SqlConnectionStringBuilder:

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

Een verbindingsreeks beantwoordt vier vragen:

1. Welke server en database gebruikt de applicatie?
2. Met welke identiteit draait de applicatie?
3. Hoe valideert de client het servercertificaat?
4. Welk verbindingsgedrag heeft de workload nodig?

Dit artikel behandelt die keuzes en de regels die de bestuurder gebruikt om de tekst te lezen. Voor elk trefwoord, de synoniemen en de standaard, zie Verbindingsopties. Om verbindingsstrings in code te maken en te wijzigen, zie Connection string builders.

Kies een authenticatiepatroon

Gebruik het patroon dat past bij de inzet. Vervang elke tijdelijke aanduiding, zoals <server>, door je eigen waarde.

Windows-geïntegreerde authenticatie verbindt zich met de identiteit van het proces. Voor een desktop- of consoleapplicatie is dat meestal de ingelogde gebruiker. Voor een webapplicatie of een Windows-dienst is het de applicatiepool of serviceaccount. Impersonatie kan de identiteit veranderen. Verleen een inlog- en databaserechten aan de identiteit die je applicatie daadwerkelijk gebruikt.

Deze drie vormen van Windows-geïntegreerde authenticatie zijn equivalent:

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

Als een string en Integrated Security=true ook en instelt User ID , Passwordgebruikt de driver Windows authentication en negeert de gebruikersnaam en het wachtwoord.

Microsoft. Data.SqlClient 7.0 en latere versies hebben het versie-matched Microsoft.Data.SqlClient.Extensions.Azure pakket nodig voor de door de drivers geleverde Microsoft Entra ID-authenticatiemethoden. Je hebt dat pakket niet nodig wanneer applicatiecode een toegangstoken of een toegangstoken callback levert.

Voor de geaccepteerde Authentication waarden, zie Authenticatieopties. Authenticatie vereist ook databasegebruikers, permissies en identiteitsconfiguratie op de server. Voor de installatiestappen, zie Microsoft Entra ID-authenticatie en SQL Server-authenticatie.

Geef de server en de database op

Server en Database zijn de meest leesbare trefwoordnamen. De bouwer schrijft ze als hun canonieke equivalenten, Data Source en Initial Catalog. Alle vier de namen werken in een verbindingsreeks.

Zet Server op een van deze vormen:

Gebruik tcp:, een volledig gekwalificeerde hostnaam en een expliciete port in productie. Gebruik een DNS-naam die overeenkomt met het servercertificaat, niet met een IP-adres, omdat certificaatvalidatie de servernaam in de verbindingsreeks vergelijkt met de namen in het certificaat.

Wanneer je verbinding maakt met Azure SQL Database met SQL-authenticatie en een gebruikersnaam in de vorm user@servername, moet het servername-onderdeel overeenkomen met de server in Server.

Voor een availability group listener of een failover-cluster instance, bekijk Multi Subnet Failover ook in de Connection-opties.

Encryptie en certificaatvalidatie configureren

Het Encrypt trefwoord accepteert in elk geval de volgende waarden:

Gebruik Strict wanneer de server TDS 8.0 ondersteunt en een certificaat heeft dat de client kan valideren. Azure SQL Database en SQL Database in Microsoft Fabric ondersteunen dit. Een LocalDB-verbinding is niet versleuteld, zelfs niet met Mandatory, en Strict faalt.

De Encrypt en Trust Server Certificate waarden combineren als volgt:

Stel Trust Server Certificate=true niet in om een verbindingsfout in productie te herstellen. Het versleutelt het kanaal, maar bevestigt de identiteit van de server niet. Beperk het tot ontwikkelomgevingen waar geen vertrouwd certificaat beschikbaar is.

Wanneer de servernaam in Data Source niet overeenkomt met het certificaat, stel Host Name In Certificate in op de naam in het certificaat. SqlClient controleert het alleen als de servernaam niet overeenkomt en het geen certificaat vastzet. Om slechts één specifiek certificaat te accepteren, stel Server Certificate in op het pad naar een PEM-, DER- of CER-bestand:

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

Voor de volledige validatieregels, zie Versleuteling en certificaatvalidatie.

Groepsgewijze verbinding gebruiken

Pooling staat standaard aan. Wanneer je een SqlConnection opent, neemt het stuurprogramma een fysieke verbinding uit een pool die overeenkomt met de verbindingsinstellingen. Wanneer je de verbinding sluit of vrijgeeft, keert de fysieke verbinding terug naar de pool in plaats van te sluiten. Een gepoolde open slaat de netwerkverbinding, de TLS-handdruk en de login over.

Volg deze regels:

• Open een verbinding net voordat je die nodig hebt, en sluit deze zodra je klaar bent, met using of await using. Een verbinding die niet wordt vrijgegeven, blijft in gebruik en de connectionpool kan uitgeput raken.

• Bouw de verbindingsreeks één keer bij het opstarten en hergebruik hem. De poolsleutel bevat de exacte tekst van de verbindingsreeks, dus een andere zoekwoordvolgorde, een synoniem of een per-verzoek waarde zoals een request-ID of gebruikersnaam creëert een aparte pool. De bouwer schrijft één canonieke vorm. Voor meer informatie, zie Behoud één canonieke verbindingsreeks.

• Verwacht een aparte pool voor elke Windows-identiteit onder geïntegreerde authenticatie, elke SqlCredential instantie en elke AccessToken waarde. Gebruik een door de driver geleverde Authentication-methode of een hergebruikte AccessTokenCallback-methode in plaats van AccessToken voor elke verbinding in te stellen.

• Zoek naar verbindingen die niet zijn verwijderd voordat je Max Pool Size verhoogt, wat standaard op 100 staat. Wanneer elke verbinding in een pool in gebruik is, wacht Open maximaal tot Connect Timeout en gooit dan 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.
  

• Plan de servercapaciteit voor elke pool. Elk proces, of elk applicatiedomein op .NET Framework, heeft zijn eigen pools. De verbindingen met de server kunnen oplopen tot Max Pool Size, vermenigvuldigd met de pools in elk proces en met het aantal applicatie-instanties.

• Stel Pooling=false niet in om een poolingprobleem te omzeilen. Telkens wanneer deze wordt geopend, wordt vervolgens een volledige login uitgevoerd.

Om gepoolde verbindingen te sluiten die te lang inactief blijven, zie Beperk de inactieve tijd van verbindingen. Voor poolsleutels, groottebepaling, clearing en transacties, zie SQL Server connection pooling.

Aparte verbindings- en commando-instellingen

Een verbindingsreeks regelt het opzetten van verbindingen en het gedrag van sessies. Een commando beheert één SQL-bewerking.

Een langere time-out is geen herkansingslogica. Een time-out beperkt één wachttijd. Een herpoging start een nieuwe poging, en deze moet beperkt zijn en veilig om te herhalen.

Rapporteer de applicatie-identiteit

Application Name stelt de naam in die de server rapporteert via APP_NAME(). Gebruik één stabiele naam voor elke gedeployeerde workload. Frameworks en tools die verbindingen openen voor een applicatie kunnen zichzelf ook rapporteren via de RegisteredApplication eigenschap, die geen verbindingsreeks-sleutelwoord heeft. Voor meer informatie, zie De toepassingsidentiteit rapporteren.

Maak veilig verbindingsreeksen

Gebruik SqlConnectionStringBuilder wanneer code een waarde toevoegt of verandert. Voeg onbetrouwbare tekst niet toe aan een verbindingsreeks, want een puntkomma in die tekst kan een trefwoord toevoegen of vervangen. De builder valideert waarden, koppelt synoniemen aan canonieke trefwoorden en citeert elke waarde zodat de waarde geen trefwoorden kan toevoegen. Voor voorbeelden, zie Connection string builders.

Verbindingsinformatie buiten de code opslaan

Laad verbindingsstrings uit het configuratiesysteem van de applicatie. .NET-applicaties gebruiken vaak omgevingsvariabelen, gebruikersgeheimen voor lokale ontwikkeling, Azure App Configuration en Azure Key Vault.

Volg deze regels:

• Commit nooit wachtwoorden, clientgeheimen, toegangstokens of verbindingsreeksen voor productie.
• Kies voor een authenticatiemethode die geen wachtwoord in de verbindingsreeks nodig heeft.
• Beperk de toegang tot de configuratiebron.
• Roteer opgeslagen geheimen en herstart of ververs applicaties die ze cachen.
• Schrijf geen verbindingsreeksen in logboeken, uitzonderingen, traceringen of telemetrie.
• Laat Persist Security Info=false, de standaard, zodat een geopende verbinding het wachtwoord niet via zijn ConnectionString eigenschap blootstelt.

Voor .NET-configuratieproviders, zie Configuratie in .NET. Voor meer controles, zie Verbindingsinformatie beschermen.

Parseerregels

De bestuurder past de volgende regels toe:

• Trefwoorden zijn niet hoofdlettergevoelig. DATABASE, Database, en database zijn hetzelfde sleutelwoord.
• Veel trefwoorden hebben synoniemen. Server en Data Source hebben dezelfde waarde. Het artikel Verbindingsopties vermeldt de synoniemen voor elk trefwoord.
• Wanneer een trefwoord meer dan eens voorkomt, wint de laatste waarde. Synoniemen tellen als hetzelfde trefwoord.
• Het stuurprogramma negeert spaties rond zoekwoorden en bij niet-aangehaalde waarden.
• Een afsluitende puntkomma is optioneel.
• Een trefwoord dat het stuurprogramma niet herkent, genereert Keyword not supported met het bericht ArgumentException.

Waarden kunnen hoofdlettergevoelig zijn, afhankelijk van het trefwoord. Een wachtwoord is hoofdlettergevoelig. Encrypt=STRICT en Encrypt=strict zijn hetzelfde.

Dit programma laat zien hoe de builder trefwoorden normaliseert, een duplicaat oplost en speciale tekens citeert. Het tabblad .NET Framework gebruikt C# 7.3. Om een project te maken dat de samples uitvoert, zie Het project maken.

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

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

De uitvoer is:

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

De eerste regel toont elk synoniem vervangen door zijn canonieke sleutelwoord: server door Data Source, DATABASE door Initial Catalog, uid door timeout, en User ID door Connect Timeout.

Waarden citeren

Sluit een waarde in dubbele aanhalingstekens (") of enkele aanhalingstekens (') wanneer deze een puntkomma bevat, begint of eindigt met een spatie, of begint of eindigt met een aanhalingsteken. Binnen een geciteerde waarde schrijf je het omsluitende aanhalingsteken twee keer.

Citaatregels kunnen gemakkelijk verkeerd worden toegepast. Stel waarden in via SqlConnectionStringBuilder eigenschappen en laat de builder deze tussen aanhalingstekens plaatsen. Voor meer informatie, zie Verbindingsstrings veilig bouwen.

Specificeer Booleaanse waarden

Trefwoorden die een Booleaanse waarde aannemen accepteren true, false, yes en no, ongeacht het gebruik van hoofdletters of kleine letters. Integrated Security accepteert sspiook , wat betekent true. De bouwer schrijft True of False.

Gebruik trefwoorden van andere stuurprogramma's

Microsoft.Data.SqlClient accepteert geen ODBC- of OLE DB-zoekwoorden zoals Driver en Provider. Verwijder deze trefwoorden wanneer je een verbindingsreeks van een andere driver verplaatst. System.Data.SqlClientVerbindingsstrings werken in Microsoft.Data.SqlClient, met de volgende verschillen:

• Encrypt is standaard ingesteld op Mandatory in Microsoft.Data.SqlClient. Een server zonder een vertrouwd certificaat faalt bij certificaatvalidatie. Installeer een vertrouwd certificaat op de server.
• Op .NET Network Libraryworden , Connection Reset, en Transparent Network IP Resolution niet ondersteund. Verwijder ze.
• Context Connection=true wordt niet ondersteund.
• Asynchronous Processing is geen ondersteund trefwoord en gooit ArgumentException. Verwijder het. Asynchrone methoden werken zonder dit.
• Type System Version=SQL Server 2000 wordt niet ondersteund. Bij het maken van de verbinding wordt ArgumentException opgeworpen. Gebruik Latest, SQL Server 2008, SQL Server 2005, of SQL Server 2012.

Verwante onderwerpen

• Gebruik Microsoft. Data.SqlClient in een .NET-app
• Verbindingsopties
• Opbouwfuncties voor verbindingsreeksen
• Verbind met een databron
• SQL Server verbindingspooling
• Microsoft Entra-ID-verificatie
• Versleuteling en certificaatvalidatie
• SQL Server Express-gebruikersexemplaren
• Ondersteuningslevenscyclus van SqlClient-stuurprogramma