Anslutningssträngar för Microsoft.Data.SqlClient

En Microsoft.Data.SqlClient-anslutningssträng är en lista av keyword=value-par separerade med semikolon. Skicka den till SqlConnection eller SqlConnectionStringBuilder:

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

En reťazec pripojenia besvarar fyra frågor:

1. Vilken server och databas använder applikationen?
2. Vilken identitet körs applikationen som?
3. Hur validerar klienten servercertifikatet?
4. Vilket anslutningsmönster behöver arbetsbelastningen?

Den här artikeln täcker dessa val och de regler som drivrutinen använder för att läsa texten. För varje nyckelord, dess synonymer och dess standardvärde, se Anslutningsalternativ. För att skapa och ändra anslutningssträngar i kod, se Connection string builders.

Välj ett autentiseringsmönster

Använd det mönster som passar driftsättningen. Byt ut varje platshållare, såsom <server>, med ditt värde.

Windows-integrerad autentisering ansluter med processens identitet. För en skrivbords- eller konsolapplikation är det vanligtvis den inloggade användaren. För en webbapplikation eller en Windows-tjänst är det applikationspoolen eller tjänstekontot. Personifiering kan förändra identiteten. Ge ett inloggningskonto och databasbehörigheter till den identitet som din applikation faktiskt använder.

Dessa tre former av Windows-integrerad autentisering är likvärdiga:

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

Om en sträng sätter Integrated Security=true och också sätter User ID och Password, använder drivrutinen Windows authentication och ignorerar användarnamn och lösenord.

Microsoft. Data.SqlClient 7.0 och senare versioner behöver det versionsanpassade Microsoft.Data.SqlClient.Extensions.Azure paketet för de drivrutinstillhandahållna autentiseringsmetoderna Microsoft Entra ID. Du behöver inte det paketet när applikationskoden tillhandahåller en åtkomsttoken eller en åtkomsttoken-callback.

För de accepterade Authentication värdena, se Autentiseringsalternativ. Autentisering kräver också databasanvändare, behörigheter och identitetskonfiguration på servern. För installationsstegen, se Microsoft Entra ID-autentisering och SQL Server-autentisering.

Ange servern och databasen

Server och Database är de mest läsbara nyckelordsnamnen. Byggaren skriver dem som deras kanoniska motsvarigheter, Data Source och Initial Catalog. Alla fyra namn fungerar i en reťazec pripojenia.

Sätt Server till en av följande former:

Använd tcp:, ett fullt kvalificerat värdnamn och en explicit port under produktion. Använd ett DNS-namn som matchar servercertifikatet, inte en IP-adress, eftersom certifikatvalidering jämför servernamnet i reťazec pripojenia med namnen i certifikatet.

När du ansluter till Azure SQL Database med SQL-autentisering och ett användarnamn i formen user@servername, måste delen servername matcha servern i Server.

För en tillgänglighetsgruppslyssnare eller en failover-klusterinstans, granska Multi Subnet Failover även i Anslutningsalternativ.

Konfigurera kryptering och certifikatvalidering

Nyckelordet Encrypt accepterar följande värden, oavsett versaler/gemener:

Använd Strict när servern stödjer TDS 8.0 och har ett certifikat som klienten kan validera. Azure SQL Database och SQL Database i Microsoft Fabric stöder detta. En LocalDB-anslutning är inte krypterad, även med Mandatory, och Strict misslyckas.

Värdena för Encrypt och Trust Server Certificate kombineras enligt följande:

Ställ inte in Trust Server Certificate=true för att åtgärda ett anslutningsfel i produktion. Den krypterar kanalen men bekräftar inte serverns identitet. Begränsa det till utvecklingsmiljöer där ett betrott certifikat inte finns tillgängligt.

När servernamnet i Data Source inte stämmer överens med certifikatet, ställ Host Name In Certificate in till namnet i certifikatet. SqlClient kontrollerar det bara när servernamnet inte stämmer, och det använder inte certifikatspinning. För att endast acceptera ett specifikt certifikat, ställ Server Certificate in på sökvägen för en PEM-, DER- eller CER-fil:

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

För fullständiga valideringsregler, se Kryptering och certifikatvalidering.

Använd anslutningspoolning

Pooling är påslagen som standard. När du öppnar en SqlConnection, tar drivrutinen en fysisk anslutning från en pool som motsvarar anslutningen. När du stänger eller kasserar anslutningen återvänder den fysiska anslutningen till poolen istället för att stängas. En återanvänd anslutning hoppar över nätverksanslutningen, TLS-handslaget och inloggningen.

Följ dessa regler:

• Öppna en anslutning precis innan du behöver den, och frigör den så snart du är klar, med using eller await using. En anslutning som inte frigörs förblir utlånad, och poolen kan ta slut.

• Skapa anslutningssträngen en gång vid uppstart och återanvänd den. Poolnyckeln innehåller exakt den texten i reťazec pripojenia, så en annan nyckelordsordning, en synonym eller ett per-request-värde som ett request-ID eller användarnamn skapar en separat pool. Byggaren skriver en kanonisk form. För mer information, se Behåll en kanonisk anslutningssträng.

• Räkna med en separat pool för varje Windows-identitet under integrerad autentisering, varje SqlCredential instans och varje AccessToken värde. Använd en drivrutinsbaserad Authentication metod eller en återanvänd AccessTokenCallback istället för att sätta AccessToken på varje anslutning.

• Leta efter anslutningar som inte har stängts innan du höjer Max Pool Size, vilket som standard är 100. När varje anslutning i en pool är i bruk, Open väntar den i upp till Connect Timeout och kastar sedan 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.
  

• Planera serverkapacitet för varje pool. Varje process, eller varje applikationsdomän på .NET Framework, har sina egna pooler. Anslutningarna till servern kan uppgå till Max Pool Size multiplicerat med poolerna i varje process och med antalet applikationsinstanser.

• Ställ inte in Pooling=false för att komma runt ett poolingproblem. Varje gång den öppnas utförs sedan en fullständig inloggning.

För att stänga poolade anslutningar som förblir inaktiva för länge, se Begränsa anslutningens vilotid. För poolnycklar, storlek, rensning och transaktioner, se anslutningspoolning i SQL Server.

Separata anslutnings- och kommandoinställningar

En reťazec pripojenia styr anslutningsetablering och sessionsbeteende. Ett kommando styr en SQL-operation.

En längre timeout är inte samma sak som återförsökslogik. En timeout begränsar en väntetid. Ett omförsök startar ett nytt försök, och det måste vara begränsat och säkert att upprepa.

Rapportera programmets identitet

Application Name sätter namnet som servern rapporterar genom APP_NAME(). Använd ett stabilt namn för varje distribuerad workload. Ramverk och verktyg som öppnar anslutningar för en applikation kan också rapportera sig själva via egenskapenRegisteredApplication, som inte har något reťazec pripojenia-nyckelord. För mer information, se Rapportera applikationens identitet.

Bygg anslutningssträngar säkert

Använd SqlConnectionStringBuilder när koden lägger till eller ändrar ett värde. Koppla inte ihop obetrodd text i en reťazec pripojenia, eftersom ett semikolon i den texten kan lägga till eller ersätta ett nyckelord. Byggaren validerar värden, kopplar synonymer till kanoniska nyckelord och citerar varje värde så att värdet inte kan lägga till nyckelord. Se Connection string builders för exempel.

Lagra anslutningsinformation utanför kod

Ladda anslutningssträngar från applikationens konfigurationssystem. .NET-applikationer använder ofta miljövariabler, användarhemligheter för lokal utveckling, Azure App Configuration och Azure Key Vault.

Följ dessa regler:

• Kommitta inte lösenord, klienthemligheter, åtkomsttokens eller produktionsanslutningssträngar.
• Föredra en autentiseringsmetod som inte kräver lösenord i reťazec pripojenia.
• Begränsa åtkomsten till konfigurationskällan.
• Rotera lagrade autentiseringsuppgifter och starta om eller uppdatera applikationer som cachelagrar dem.
• Skriv inte anslutningssträngar till loggar, undantag, spår eller telemetri.
• Låt Persist Security Info=false vara som standardvärde, så att en öppen anslutning inte exponerar lösenordet via egenskapen ConnectionString.

För .NET-konfigurationsleverantörer, se Konfiguration i .NET. För fler kontroller, se Skydda anslutningsinformation.

Parsningsregler

Föraren tillämpar dessa regler:

• Nyckelord är inte kasuskänsliga. DATABASE, Database, och database är samma nyckelord.
• Många nyckelord har synonymer. Server och Data Source anger samma värde. Artikeln Anslutningsalternativ listar synonymerna för varje nyckelord.
• När ett nyckelord förekommer mer än en gång vinner det sista värdet. Synonymer räknas som samma nyckelord.
• Drivrutinen ignorerar mellanrum runt nyckelord och runt ociterade värden.
• Ett efterföljande semikolon är valfritt.
• Ett nyckelord som föraren inte känner igen kastar ArgumentException med meddelandet Keyword not supported.

Värden kan vara kasuskänsliga, beroende på nyckelordet. Ett lösenord är skiftlägeskänsligt. Encrypt=STRICT och Encrypt=strict är likadana.

Detta program visar hur byggverktyget normaliserar nyckelord, löser en dubblett och citerar specialtecken. Fliken .NET Framework använder C# 7.3. För att skapa ett projekt som kör proverna, se Skapa projektet.

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

Resultatet är:

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

Den första raden visar varje synonym ersatt av sitt kanoniska nyckelord: User ID av timeout, Connect Timeout av uid, Initial Catalog av DATABASE och Data Source av server.

Sätt citattecken runt värden

Omslut ett värde med dubbla citationstecken (") eller enkla citattecken (') när det innehåller ett semikolon, börjar eller slutar med ett mellanslag, eller börjar eller slutar med ett citationstecken. Inuti ett citerat värde, skriv citattecknet två gånger.

Citeringsregler är lätta att missförstå. Sätt värden genom SqlConnectionStringBuilderegenskaper och låt byggaren sätta citationstecken runt dem. För mer information, se Bygg anslutningssträngar säkert.

Specificera booleska värden

Nyckelord som tar ett booleskt värde accepterar true, false, yes och no, oavsett skiftläge. Integrated Security accepterar också sspi, vilket betyder true. Byggaren skriver True eller False.

Använd nyckelord från andra förare

Microsoft. Data.SqlClient accepterar inte ODBC- eller OLE DB-nyckelord som Driver och Provider. Ta bort dessa nyckelord när du flyttar en reťazec pripojenia från en annan drivrutin. System.Data.SqlClientAnslutningssträngar fungerar i Microsoft.Data.SqlClient, med dessa skillnader:

• Encrypt är standardvärdet i Mandatory Microsoft.Data.SqlClient. En server utan ett betrott certifikat misslyckas med certifikatvalidering. Installera ett betrott certifikat på servern.
• Network Library, Connection Reset och Transparent Network IP Resolution stöds inte på .NET. Ta bort dem.
• Context Connection=true stöds inte.
• Asynchronous Processing är inte ett stödd nyckelord och kastar ArgumentException. Ta bort den. Asynkrona metoder fungerar utan detta.
• Type System Version=SQL Server 2000 stöds inte. När anslutningen skapas uppstår ArgumentException. Använd Latest, SQL Server 2008, SQL Server 2005 eller SQL Server 2012.

Relaterat innehåll

• Använd Microsoft. Data.SqlClient i en .NET-app
• Anslutningsalternativ
• Anslutningssträngsbyggare
• Koppla till en datakälla
• SQL Server anslutningspoolning
• Microsoft Entra ID-autentisering
• Kryptering och certifikatvalidering
• SQL Server Express-användarinstanser
• Supportlivscykel för SqlClient-drivrutin