SqlConnectionStringBuilder 類別

定義

命名空間:

Microsoft.Data.SqlClient

組件:

Microsoft.Data.SqlClient.dll

套件:

Microsoft.Data.SqlClient v7.1.0

提供簡單的方法來建立和管理 SqlConnection 類別所使用的連接字串內容。

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

繼承

DbConnectionStringBuilder

SqlConnectionStringBuilder

屬性

TypeConverterAttribute

範例

下列主控台應用程式會建置 SQL Server 資料庫的連接字串。 程式碼使用一個SqlConnectionStringBuilder類別來建立 連接字串，然後將實例的SqlConnectionStringBuilder屬性傳給ConnectionString該連接類別的建構子。 範例同時解析已存在的 連接字串，並示範操作該 連接字串 內容的各種方法。

Note

這個範例包含密碼，用來示範如何 SqlConnectionStringBuilder 處理連線字串。 我們建議您在應用程式中使用 Windows 認證。 如果必須使用密碼，請不要在申請中加入硬編碼密碼。

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password=********;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "********";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

備註

連接字串產生器可讓開發人員使用 類別的屬性和方法，以程式設計方式建立語法正確的連接字串，以及剖析和重建現有的連接字串。 連接字串產生器提供強型別屬性，對應至 SQL Server 所允許的已知索引鍵/值組。 需要在應用程式中建立連接字串的開發者，可以使用此 SqlConnectionStringBuilder 類別來建構和修改連接字串。 類別也可讓您輕鬆地管理儲存在應用程式組態檔中的連接字串。

它 SqlConnectionStringBuilder 會檢查有效的鍵值對。 因此，您無法使用此類別來建立無效的連接字串;嘗試新增無效的配對將會擲回例外狀況。 類別會維護一組固定的同義字，而且可以從同義字轉譯為對應的已知索引鍵名稱。

例如，當你使用 Item 屬性來取得一個值時，你可以指定包含任何你需要的鍵值同義詞的字串。 例如，當你使用任何需要包含該鍵名稱字串的成員時，可以在 連接字串 中指定「Network Address」、「addr」或其他可接受的同義詞，例如 Item 屬性或Remove方法。 如需可接受的同義字完整清單，請參閱 ConnectionString 屬性。

Item 屬性處理嘗試插入惡意條目。 例如，以下程式碼使用預設的 Item 屬性（C# 中的索引器）正確逃逸巢狀的鍵值對：

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

結果是下列連接字串，會以安全的方式處理無效的值：

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

建構函式

名稱	Description
SqlConnectionStringBuilder()	初始化 SqlConnectionStringBuilder 類別的新執行個體。
SqlConnectionStringBuilder(String)	初始化 SqlConnectionStringBuilder 類別的新執行個體。 提供的連接字串會提供實例內部連接信息的數據。

屬性

名稱	Description
ApplicationIntent	連接到 SQL Server 可用性群組中的資料庫時，宣告應用程式工作負載類型。 您可以使用 ApplicationIntent來設定此屬性的值。 如需 SqlClient 支援 Always On 可用性群組的詳細資訊，請參閱 SqlClient 支援高可用性、災害復原。
ApplicationName	取得或設定與連接字串相關聯的應用程式名稱。
AttachDBFilename	取得或設定包含主要數據檔名稱的字串。 這包括可附加資料庫的完整路徑名稱。
AttestationProtocol	取得或設定認證協議的價值。
Authentication	取得或設定用於 Connect with Microsoft Entra 到 Azure SQL 資源的認證方法。
ColumnEncryptionSetting	取得或設定連接字串產生器的數據行加密設定。
CommandTimeout	終止嘗試執行命令並產生錯誤之前的預設等候時間 (以秒為單位)。 預設值為 30 秒。
ConnectionReset	已淘汰. 已過時。 取得或設定布爾值，指出從連接集區繪製時是否重設連接。
ConnectRetryCount	識別發生閑置連線失敗之後嘗試的重新連線次數。 這必須是介於 0 到 255 之間的整數。 非 Azure 端點的預設值為 1。 對於 Azure SQL 端點，預設是 2。 從版本 5.x 開始，對於 Azure SQL 無伺服器端點或按需端點，預設為 5，以提升與閒置或暫停實例連線的連線成功率。 設定為 0 以停用閑置連線失敗時的重新連線。 若設定值超出允許範圍，則會擲出 A ArgumentException 。
ConnectRetryInterval	在識別發生閑置連線失敗之後，每個重新連線嘗試之間的時間量（以秒為單位）。 這必須是介於 1 到 60 之間的整數。 預設值是 [10 秒]。
ConnectTimeout	取得或設定在終止嘗試併產生錯誤之前，等候伺服器連線的時間長度（以秒為單位）。
CurrentLanguage	取得或設定用於資料庫伺服器警告或錯誤訊息的語言。
DataSource	取得或設定要連線之 SQL Server 實例的名稱或網路位址。
EnclaveAttestationUrl	取得或設定 enclave 認證 URL 以搭配基於 enclave 的 Always Encrypted。
Encrypt	取得或設定 SqlConnectionEncryptOption 自版本 5.0 起的值，或 Boolean 早期版本的值，指示用戶端與伺服器間所有資料是否需要 TLS 加密。
Enlist	取得或設定一個布林值，指示 SQL Server 連線池是否自動在建立執行緒的當前交易情境中登錄該連線。
FailoverPartner	取得或設定當主伺服器關閉時要連線之夥伴伺服器的名稱或位址。
FailoverPartnerSPN	取得或設定該連線故障轉移夥伴的服務主體名稱（SPN）。
HostNameInCertificate	在驗證連線伺服器憑證時，取得或設定主機名稱。 若未指定，則會使用來自 的 Data Source 伺服器名稱進行憑證驗證。 （僅在 v5.0+ 版本中提供）
IdleTimeout	取得或設定連線在連接池中閒置（閒置）的最大時間（秒數），直到被丟棄。 預設值為 300 （5 分鐘）。
InitialCatalog	取得或設定與連接相關聯的資料庫名稱。
IntegratedSecurity	取得或設定一個布林值，指示連線中是否指定使用者 ID 與密碼（當 false ） 或是否使用目前的 Windows 帳號憑證進行認證（當 true ）。
IPAddressPreference	在建立 TCP 連線時，取得或設定 IP 位址家族偏好。
IsFixedSize	取得值，這個值表示 SqlConnectionStringBuilder 是否有固定大小。
Item[String]	取得或設定與指定索引鍵相關聯的值。 在 C# 中，這個屬性就是索引器。
Keys	取得 ICollection，其中包含 SqlConnectionStringBuilder中的索引鍵。
LoadBalanceTimeout	取得或設定在終結之前連接集區中生存的最小時間，以秒為單位。
MaxPoolSize	取得或設定這個特定連接字串之連接集區中允許的連線數目上限。
MinPoolSize	取得或設定這個特定連接字串之連接集區中允許的連線數目下限。
MultipleActiveResultSets	若為 true，應用程式可以維護多個作用中結果集 （MARS）。 若為 false，應用程式必須先處理或取消一個批次的所有結果集，才能在該連線上執行任何其他批次。 如需詳細資訊，請參閱多個使用中結果集 （MARS）。
MultiSubnetFailover	如果你的應用程式連接到不同子網路上的 AlwaysOn 可用性群組（AG），設定 MultiSubnetFailover=true 能更快偵測並連接到（目前）活躍的伺服器。 如需 SqlClient 支援 Always On 可用性群組的詳細資訊，請參閱 SqlClient 支援高可用性、災害復原。
NetworkLibrary	取得或設定字串，其中包含用來建立 SQL Server 連線的網路連結庫名稱。
PacketSize	取得或設定網路封包的大小，以位元組為單位，用來與 SQL Server 實例通訊。
Password	取得或設定 SQL Server 帳戶的密碼。
PersistSecurityInfo	取得或設定一個布林值，指示安全敏感資訊（如密碼或存取權杖）是否應作為該連線 SqlConnectionStringBuilder 連接字串 的一部分回傳，前提是該連線從未處於開放狀態。 這個屬性只有在你的應用程式有特定需求需要從已開啟的資料庫連線讀取密碼時才應該設定為 。true 預設值 false 為較安全的設定;使用此 true 屬性會使應用程式面臨安全風險，例如誤記或追蹤資料庫密碼。
PoolBlockingPeriod	連接集區的封鎖期間行為。
Pooling	取得或設定 Boolean 值，這個值表示每次要求連接時，是否要集區或明確開啟連接。
Replication	取得或設定布爾值，指出是否支援使用連接進行複寫。
ServerCertificate	取得或設定憑證檔案的路徑，以匹配 SQL Server 的 TLS/SSL 連線憑證。 接受的憑證格式為 PEM、DER 和 CER。 若指定，會透過驗證所提供的憑證是否ServerCertificate完全匹配來檢查 SQL Server 憑證。 （僅在 v5.1+ 中提供）
ServerSPN	取得或設定資料來源的服務主體名稱（SPN）。
TransactionBinding	取得或設定字串值，這個值表示連接如何維持其與登記 System.Transactions 交易的關聯。
TransparentNetworkIPResolution	已淘汰. 在 .NET 框架中，當此鍵值設為 true時，驅動程式會在 DNS 解析的 IP 位址上執行多輪連線，每次嘗試逾時逐漸增加，序列模式嘗試至少需 500 毫秒，直到連線成功或整體連線達標Connect Timeout。
TrustServerCertificate	取得或設定值，這個值表示通道是否會在略過憑證鏈結以驗證信任時加密。
TypeSystemVersion	取得或設定字串值，指出應用程式預期的型別系統。
UserID	取得或設定連接到 SQL Server 時要使用的使用者識別碼。
UserInstance	取得或設定值，這個值表示是否要將連接從預設 SQL Server Express 實例重新導向至呼叫端帳戶下執行的運行時間起始實例。
Values	得到 ICollection 包含 的 SqlConnectionStringBuilder 值的 。
WorkstationID	取得或設定連接到 SQL Server 的工作站名稱。

方法

名稱	Description
Clear()	清除實例內容 SqlConnectionStringBuilder 。
ContainsKey(String)	判斷是否 SqlConnectionStringBuilder 包含特定的鍵。
Remove(String)	從 SqlConnectionStringBuilder 實例中移除具有指定索引鍵的專案。
ShouldSerialize(String)	指出指定的索引鍵是否存在於這個 SqlConnectionStringBuilder 實例中。
TryGetValue(String, Object)	從此 SqlConnectionStringBuilder 中取得對應所提供金鑰的值。