SqlConnectionStringBuilder 類別

定義

命名空間:

Microsoft.Data.SqlClient

組件:

Microsoft.Data.SqlClient.dll

套件:

Microsoft.Data.SqlClient v5.2.0

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

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

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

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

繼承

DbConnectionStringBuilder

SqlConnectionStringBuilder

範例

下列主控台應用程式會建置 SQL Server 資料庫的連接字串。 此程式碼會使用 SqlConnectionStringBuilder 類別建立連接字串，然後將 ConnectionString 執行個體的 SqlConnectionStringBuilder 屬性傳遞給連接類別的建構函式。 此範例也會剖析現有的連接字串，並示範操作連接字串內容的各種方式。

注意

這個範例包含了密碼，可示範 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= a!Pass113;initial catalog=AdventureWorks";

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

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

備註

連接字串產生器 (Builder) 可讓開發人員使用類別的屬性和方法，以程式設計方式建立語法正確的連接字串，以及剖析和重建現有的連接字串。 連接字串產生器提供強型別 (Strongly Typed) 屬性，這些屬性對應到 SQL Server 允許的已知索引鍵/值組。 必須建立連接字串做為應用程式一部分的開發人員可以使用 SqlConnectionStringBuilder 類別來建置及修改連接字串。 此類別也可讓您輕鬆管理儲存在應用程式組態檔內的連接字串。

SqlConnectionStringBuilder 會執行有效索引鍵/值組的檢查。 因此，您無法使用這個類別來建立無效的連接字串，嘗試加入無效的索引鍵/值組將會擲回例外狀況。 此類別會維護固定的同義資料表 (Synonym) 集合，且可從同義資料表轉譯為相對應的已知索引鍵名稱。

例如，當您使用 Item 屬性來擷取值時，您可以指定字串，其中包含所需索引鍵的任何同義字。 例如，當您使用任何需要包含索引鍵名稱之字串的成員時，可以在 連接字串 內指定 「網路位址」、「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  

建構函式

SqlConnectionStringBuilder()	初始化 SqlConnectionStringBuilder 類別的新執行個體。
SqlConnectionStringBuilder(String)	初始化 SqlConnectionStringBuilder 類別的新執行個體。 所提供的連接字串會提供執行個體內部連接資訊的資料。

屬性

ApplicationIntent	當連接到 SQL Server 可用性群組中的資料庫時，宣告應用程式工作負載類型。 您可以使用 ApplicationIntent 來設定這個屬性的值。 如需 AlwaysOn 可用性群組的 SqlClient 支援詳細資訊，請參閱高可用性、嚴重損壞修復的 SqlClient 支援。
ApplicationName	取得或設定與連接字串相關聯的應用程式名稱。
AttachDBFilename	取得或設定包含主要資料檔名稱的字串。 這包括可附加之資料庫的完整路徑名稱。
AttestationProtocol	取得或設定證明通訊協定的值。
Authentication	取得或設定用於使用 Azure Active Directory 驗證連線至 SQL Database 的驗證方法。
ColumnEncryptionSetting	取得或設定連接字串產生器的資料行加密設定。
CommandTimeout	在終止執行命令併產生錯誤之前，預設等候時間 (秒) 。 預設值為 30 秒。
ConnectRetryCount	在識別出閒置連線失敗後，已嘗試的重新連線次數。 此值必須是介於 0 到 255 之間的整數。 非 Azure 端點的預設值為 1。 針對 Azure SQL 端點，預設值為 2。 從 5.x 版開始，針對無伺服器或隨選端點 Azure SQL，預設值為 5，以改善連線連線到閑置或暫停實例的連接成功。 設定為 0 以停用閒置連線失敗的重新連線。 如果設為超出允許範圍的值，就會擲回 ArgumentException。
ConnectRetryInterval	在識別出閒置連線的失敗之後，每個重新連線嘗試之間的時間量 (以秒為單位)。 此值必須是介於 1 到 60 之間的整數。 預設值是 10 秒。
ConnectTimeout	取得或設定在終止嘗試並產生錯誤之前，要等待伺服器連接的時間長度 (以秒為單位)。
CurrentLanguage	取得或設定用於資料庫伺服器警告或錯誤訊息的語言。
DataSource	取得或設定要連接之 SQL Server 執行個體的名稱或網路位址。
EnclaveAttestationUrl	取得或設定要與記憶體保護區型 Always Encrypted 搭配使用的記憶體保護區證明 URL。
Encrypt	取得或設定 SqlConnectionEncryptOption 自 5.0 版以來的值，或 Boolean 舊版的值，指出客戶端與伺服器之間傳送之所有數據是否需要 TLS 加密。
Enlist	取得或設定布林值，指出 SQL Server 連接共用器是否在建立執行緒的目前異動內容中，自動登記連接。
FailoverPartner	取得或設定主要伺服器當機時，要連接之夥伴伺服器的名稱或位址。
FailoverPartnerSPN	取得或設定連線之故障轉移夥伴 (SPN) 的服務主體名稱。
HostNameInCertificate	取得或設定驗證連接之伺服器證書時要使用的主機名。 未指定時，會使用 中的 Data Source 伺服器名稱進行憑證驗證。 (僅適用於 v5.0+)
InitialCatalog	取得或設定與連接相關聯的資料庫名稱。
IntegratedSecurity	取得或設定布林值，指出是否在連接中指定使用者 ID 和密碼 (false 時) 或目前 Windows 帳戶認證是否用於驗證 (true 時)。
IPAddressPreference	取得或設定建立 TCP 連線時的 IP 位址系列喜好設定。
IsFixedSize	取得值，指出 SqlConnectionStringBuilder 是否有固定的大小。
Item[String]	取得或設定與指定之索引鍵相關聯的值。 在 C# 中，這個屬性是索引子 (Indexer)。
Keys	取得 ICollection 中包含索引鍵的 SqlConnectionStringBuilder。
LoadBalanceTimeout	取得或設定在遭到終結之前，連接在連接集區中存在的最短時間 (以秒為單位)。
MaxPoolSize	取得或設定連接集區中，針對這個特定的連接字串允許的最大連接數目。
MinPoolSize	取得或設定連接集區中，針對這個特定的連接字串允許的最小連接數目。
MultipleActiveResultSets	為 true 時，應用程式可以維護 Multiple Active Result Sets(MARS)。 為 false 時，應用程式必須處理或取消一個批次處理的所有結果集，才能在該連接上執行任何其他批次處理。 如需詳細資訊，請參閱 Multiple Active Result Sets (MARS)。
MultiSubnetFailover	如果您的應用程式連線至不同子網路上的 AlwaysOn 可用性群組 (AG)，設定 MultiSubnetFailover=true 可讓您更快地偵測並連線到 (目前) 使用中的伺服器。 如需 AlwaysOn 可用性群組的 SqlClient 支援詳細資訊，請參閱高可用性、嚴重損壞修復的 SqlClient 支援。
PacketSize	取得或設定用於與 SQL Server 執行個體通訊的網路封包大小 (以位元組為單位)。
Password	取得或設定 SQL Server 帳戶的密碼。
PersistSecurityInfo	取得或設定 Boolean 值，指出是否應該傳回安全性敏感性資訊，例如密碼或存取令牌，以在連接處於開啟狀態之後，於與這個 SqlConnectionStringBuilder 建立的連線上做為 連接字串 的一部分。 只有當您的應用程式有特定需要從已開啟的資料庫連線讀取密碼時，才應該將此屬性設定 true 為 。 的預設值 false 是更安全的設定;針對此屬性使用 true 會開啟您的應用程式，以產生安全性風險，例如不小心記錄或追蹤資料庫密碼。
PoolBlockingPeriod	連接集區封鎖期間的行為。
Pooling	取得或設定布林值，指出每次要求連接時，是要緩衝處理連接還是明確開啟連接。
Replication	取得或設定布林值，指出使用連接是否支援複寫。
ServerCertificate	取得或設定要與連線 SQL Server TLS/SSL 憑證相符的憑證檔案路徑。 接受的憑證格式為 PEM、DER 和 CER。 如果指定，則會檢查 SQL Server 憑證，方法是確認提供的 是否ServerCertificate完全相符。 (僅適用於 v5.1+)
ServerSPN	取得或設定數據源的SPN) (服務主體名稱。
TransactionBinding	取得或設定字串值，表示連接如何維護與已登記之 System.Transactions 交易的關聯。
TrustServerCertificate	取得或設定值，指出通道是否會加密，同時略過驗證信任的憑證鏈結查核。
TypeSystemVersion	取得或設定字串值，表示應用程式預期的型別系統。
UserID	取得或設定連接至 SQL Server 時要使用的使用者 ID。
UserInstance	取得或設定值，指出是否將連接從預設 SQL Server Express 執行個體，重新導向在呼叫端帳戶下執行之執行階段啟始的執行個體。
Values	取得包含 ICollection 中之值的 SqlConnectionStringBuilder。
WorkstationID	取得或設定連接至 SQL Server 的工作站名稱。

方法

Clear()	清除 SqlConnectionStringBuilder 執行個體的內容。
ContainsKey(String)	判斷 SqlConnectionStringBuilder 是否包含特定索引鍵。
Remove(String)	從 SqlConnectionStringBuilder 執行個體移除具有指定之索引鍵的項目。
ShouldSerialize(String)	指出這個 SqlConnectionStringBuilder 執行個體中，是否存在指定的索引鍵。
TryGetValue(String, Object)	從這個 SqlConnectionStringBuilder 擷取對應到所提供之索引鍵的值。