Anslutningssträngbyggare i Microsoft.Data.SqlClient

Använd SqlConnectionStringBuilder för att skapa och redigera anslutningssträngar via typade egenskaper. Den ärver från DbConnectionStringBuilder. Använd det när din kod lägger till eller ändrar ett värde, istället för att slå ihop strängar.

Byggaren:

Exponerar varje nyckelord som en typad egenskap, såsom ConnectTimeout som int och Encrypt som en SqlConnectionEncryptOption.
Förkastar okända nyckelord och många värden utanför intervallet med ArgumentException när du anger dem.
Avbildar synonymer som Server och uid till kanoniska nyckelord som Data Source och User ID.
Sätter citationstecken runt värden som innehåller semikolon, citattecken eller inledande eller avslutande blanksteg.

För sökordslistan, se Anslutningsalternativ. För textformatet, se Parsing-reglerna.

Varje prov är ett komplett program. .NET Framework-flikarna använder C# 7.3. För att skapa ett projekt som kör exemplen, se Skapa projektet.

Förhindra reťazec pripojenia injection

När din kod infogar opålitlig text i en reťazec pripojenia kan ett semikolon i den texten lägga till ett nyckelord eller ersätta ett tidigare, eftersom det sista värdet vinner. Byggaren lagrar hela värdet i en egenskap och sätter citattecken runt det, så texten kan inte bli ett nytt nyckelord.

Detta program sätter InitialCatalog till ett värde som försöker stänga av pooling:

.NET
.NET Framework

using Microsoft.Data.SqlClient;

// Simulates a value that came from a user or another untrusted source.
string databaseFromUser = "Orders;Pooling=false";

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = databaseFromUser,
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Strict,
};

Console.WriteLine(builder.ConnectionString);
Console.WriteLine($"Pooling: {builder.Pooling}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Simulates a value that came from a user or another untrusted source.
        string databaseFromUser = "Orders;Pooling=false";

        var builder = new SqlConnectionStringBuilder
        {
            DataSource = "tcp:sql.example.com,1433",
            InitialCatalog = databaseFromUser,
            IntegratedSecurity = true,
            Encrypt = SqlConnectionEncryptOption.Strict,
        };

        Console.WriteLine(builder.ConnectionString);
        Console.WriteLine($"Pooling: {builder.Pooling}");
    }
}

Resultatet är:

Data Source=tcp:sql.example.com,1433;Initial Catalog="Orders;Pooling=false";Integrated Security=True;Encrypt=Strict
Pooling: True

Byggaren citerar värdet och Pooling stannar Truekvar. Drivrutinen Orders;Pooling=false skickar databasens namn till servern.

Citering stoppar nyckelordsinjektion. Den avgör inte om ett värde är tillåtet. Kontrollera opålitlig input mot en lista över tillåtna servrar eller databaser innan du använder den.

Fullborda en bas-reťazec pripojenia

Lagra de delar av en reťazec pripojenia som inte ändras, såsom servern och databasen, i konfigurationen. Lägg till de hemliga och arbetsbelastningsspecifika värdena vid körning. Skicka bassträngen till byggarkonstruktören och sätt sedan egenskaper.

Detta program läser en bassträng och ett lösenord från separata miljövariabler, ansluter till SQL-autentisering och bekräftar att lösenordet inte är synligt efter att anslutningen öppnats.

.NET
.NET Framework

using Microsoft.Data.SqlClient;

// The base string holds no secret. The password comes from a separate secret source.
string baseConnectionString =
    Environment.GetEnvironmentVariable("SQL_BASE_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_BASE_CONNECTION_STRING environment variable.");
string password =
    Environment.GetEnvironmentVariable("SQL_PASSWORD")
    ?? throw new InvalidOperationException(
        "Set the SQL_PASSWORD environment variable.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    Password = password,
    ApplicationName = "Orders.Worker",
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");

var opened = new SqlConnectionStringBuilder(connection.ConnectionString);
Console.WriteLine($"Password visible after open: {opened.ContainsKey("Password") && opened.Password.Length > 0}");

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        // The base string holds no secret. The password comes from a separate secret source.
        string baseConnectionString =
            Environment.GetEnvironmentVariable("SQL_BASE_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_BASE_CONNECTION_STRING environment variable.");
        string password =
            Environment.GetEnvironmentVariable("SQL_PASSWORD")
            ?? throw new InvalidOperationException(
                "Set the SQL_PASSWORD environment variable.");

        var builder = new SqlConnectionStringBuilder(baseConnectionString)
        {
            Password = password,
            ApplicationName = "Orders.Worker",
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
            }

            var opened = new SqlConnectionStringBuilder(connection.ConnectionString);
            Console.WriteLine($"Password visible after open: {opened.ContainsKey("Password") && opened.Password.Length > 0}");
        }
    }
}

Sätt SQL_BASE_CONNECTION_STRING till ett värde såsom Server=tcp:<server>,1433;Database=<database>;User ID=<user>;Encrypt=true. Resultatet är:

APP_NAME(): Orders.Worker
Password visible after open: False

Persist Security Info standardinställningen till false, så drivrutinen tar bort lösenordet från SqlConnection.ConnectionString efter att anslutningen öppnats. Behåll standardinställningen.

Föredra en autentiseringsmetod som inte kräver något lösenord, såsom Windows-integrerad autentisering eller en Microsoft Entra ID-hanterad identitet. För mer information, se Microsoft Entra ID-autentisering och Skydda anslutningsinformation.

Läs och ändra värden

Byggaren fungerar också som en ordbok. Indexeraren, ContainsKey, Remove, och TryGetValue accepterar ett nyckelord eller någon av dess synonymer.

.NET
.NET-ramverket

using Microsoft.Data.SqlClient;

var b = new SqlConnectionStringBuilder("Server=sql.example.com;Database=Orders;uid=app_user;pwd=x");
b["server"] = "tcp:sql2.example.com,1433";
Console.WriteLine($"DataSource: {b.DataSource}");
Console.WriteLine($"ContainsKey(\"uid\"): {b.ContainsKey("uid")}");
Console.WriteLine($"Remove(\"pwd\"): {b.Remove("pwd")}");
Console.WriteLine($"TryGetValue: {b.TryGetValue("Database", out object? db)} {db}");
Console.WriteLine($"ShouldSerialize(\"Pooling\"): {b.ShouldSerialize("Pooling")}");
Console.WriteLine(b.ConnectionString);
try { b["Bogus"] = 1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
try { b.ConnectTimeout = -1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var b = new SqlConnectionStringBuilder("Server=sql.example.com;Database=Orders;uid=app_user;pwd=x");
        b["server"] = "tcp:sql2.example.com,1433";
        Console.WriteLine($"DataSource: {b.DataSource}");
        Console.WriteLine($"ContainsKey(\"uid\"): {b.ContainsKey("uid")}");
        Console.WriteLine($"Remove(\"pwd\"): {b.Remove("pwd")}");
        Console.WriteLine($"TryGetValue: {b.TryGetValue("Database", out object db)} {db}");
        Console.WriteLine($"ShouldSerialize(\"Pooling\"): {b.ShouldSerialize("Pooling")}");
        Console.WriteLine(b.ConnectionString);
        try { b["Bogus"] = 1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
        try { b.ConnectTimeout = -1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
    }
}

Resultatet är:

DataSource: tcp:sql2.example.com,1433
ContainsKey("uid"): True
Remove("pwd"): True
TryGetValue: True Orders
ShouldSerialize("Pooling"): False
Data Source=tcp:sql2.example.com,1433;Initial Catalog=Orders;User ID=app_user
ArgumentException: Keyword not supported: 'Bogus'.
ArgumentException: Invalid value for key 'Connect Timeout'.

ShouldSerialize returnerar false för ett nyckelord som inte finns i strängen. ContainsKey returnerar true för varje stödd nyckelord, oavsett om strängen sätter det eller inte. Egenskapen ConnectionString inkluderar endast de nyckelord du ställer in.

Förstå vad byggaren inte kontrollerar

Byggaren avvisar okända nyckelord och många ogiltiga värden, men kontrollerar inte alla värden. Till exempel accepterar den all text för Type System Version och Transaction Binding, och kontrollerar inte stränglängder. Den kontrollerar inte heller kombinationer av nyckelord, så den accepterar Authentication=služba Active Directory Default tillsammans med Integrated Security=true. SqlConnection förkastar den kombinationen med ArgumentException när du skickar strängen till den. För hela listan över regler, se Valideringsregler.

Byggaren skriver Authentication värden utan mellanrum, såsom Authentication=ActiveDirectoryDefault. Drivrutinen accepterar båda formerna.

Buildern skyddar inte heller ett lösenord efter att det kommit in i processens minne, och den bestämmer inte om en server-, identitets- eller certifikatinställning är säker.

Behåll en kanonisk anslutningssträng

Varje distinkt reťazec pripojenia får sin egen connection pool. Två handskrivna strängar som endast skiljer sig åt i nyckelordsordning eller synonymer skapar två pooler. Byggaren skriver kanoniska nyckelord i en konsekvent ordning, så Server=a;Database=d och Database=d;Server=a båda blir Data Source=a;Initial Catalog=d. Bygg reťazec pripojenia en gång vid uppstart och återanvänd builder.ConnectionStringden. Lägg inte till värden per begäran, såsom användarnamn eller begärande-ID:n. För mer vägledning om pooling, se Använd anslutningspooling.

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-10-28