SqlConnectionStringBuilder 類別

定義

命名空間:

System.Data.SqlClient

組件:

System.Data.dll

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

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

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

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

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

繼承

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

屬性

TypeConverterAttribute

範例

下列主控台應用程式會建置 SQL Server 資料庫的連接字串。 程序代碼會使用 SqlConnectionStringBuilder 類別來建立連接字串。 然後，此範例會剖析連接字串，並示範各種操作其內容的方式。

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
builder.AsynchronousProcessing = true;

// 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($"Modified connection string: '{builder.ConnectionString}'");

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As New SqlConnectionStringBuilder(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine("Original connection string: " + builder.ConnectionString)

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine("Modified connection string: " + builder.ConnectionString)
    End Sub
End Module

備註

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

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

例如，當您使用 Item 屬性來擷取值時，您可以指定包含所需索引鍵之任何同義字的字串。 例如，當您使用任何需要包含索引鍵名稱的成員，例如 Item[String] 屬性或 Remove 方法等字串時，可以在連接字串中指定此密鑰的「網路位址」、「addr」或任何其他可接受的同義字。 如需可接受的同義字完整清單，請參閱 ConnectionString 屬性。

Item[String] 屬性會處理嘗試插入惡意專案。 例如，下列程式代碼會使用預設 Item 屬性（以 C# 表示索引器）正確地逸出巢狀索引鍵/值組：

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

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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	取得或設定與連接字串相關聯的應用程式名稱。
AsynchronousProcessing	取得或設定布爾值，這個值表示是否允許使用此連接字串建立的連接進行異步處理。
AttachDBFilename	取得或設定包含主要數據檔名稱的字串。 這包括可附加資料庫的完整路徑名稱。
Authentication	取得連接字串的驗證。
BrowsableConnectionString	取得或設定值，這個值表示Visual Studio設計工具中是否顯示 ConnectionString 屬性。 (繼承來源 DbConnectionStringBuilder)
ColumnEncryptionSetting	取得或設定連接字串產生器的數據行加密設定。
ConnectionReset	已淘汰. 過時。 取得或設定布爾值，指出從連接集區繪製時是否重設連接。
ConnectionString	取得或設定與 DbConnectionStringBuilder相關聯的連接字串。 (繼承來源 DbConnectionStringBuilder)
ConnectRetryCount	識別發生閑置連線失敗之後嘗試的重新連線次數。 這必須是介於 0 到 255 之間的整數。 預設值為 1。 設定為 0 以停用閑置連線失敗時的重新連線。 如果設定為允許範圍以外的值，則會擲回 ArgumentException。
ConnectRetryInterval	在識別發生閑置連線失敗之後，每個重新連線嘗試之間的時間量（以秒為單位）。 這必須是介於 1 到 60 之間的整數。 預設值為10秒。 如果設定為允許範圍以外的值，則會擲回 ArgumentException。
ConnectTimeout	取得或設定在終止嘗試併產生錯誤之前，等候伺服器連線的時間長度（以秒為單位）。
ContextConnection	取得或設定值，這個值表示是否應該建立與 SQL Server 的用戶端/伺服器或進程內連線。
Count	取得包含在 ConnectionString 屬性內的目前索引鍵數目。 (繼承來源 DbConnectionStringBuilder)
CurrentLanguage	取得或設定 SQL Server 語言記錄名稱。
DataSource	取得或設定要連線之 SQL Server 實例的名稱或網路位址。
EnclaveAttestationUrl	取得或設定要與記憶體保護區型 Always Encrypted 搭配使用的記憶體保護區證明 URL。
Encrypt	取得或設定布爾值，指出如果伺服器已安裝憑證，SQL Server 是否針對客戶端與伺服器之間傳送的所有數據使用 SSL 加密。
Enlist	取得或設定 Boolean 值，指出 SQL Server 連接共用器是否會在建立線程的目前交易內容中自動登記連接。
FailoverPartner	取得或設定當主伺服器關閉時要連線之夥伴伺服器的名稱或位址。
InitialCatalog	取得或設定與連接相關聯的資料庫名稱。
IntegratedSecurity	取得或設定布爾值，指出是否在連線中指定使用者標識碼和密碼（false時），或目前的 Windows 帳戶認證是否用於驗證（true時）。
IsFixedSize	取得值，這個值表示 SqlConnectionStringBuilder 是否有固定大小。
IsReadOnly	取得值，這個值表示 DbConnectionStringBuilder 是否為唯讀。 (繼承來源 DbConnectionStringBuilder)
Item[String]	取得或設定與指定索引鍵相關聯的值。 在 C# 中，此屬性是索引器。
Keys	取得 ICollection，其中包含 SqlConnectionStringBuilder中的索引鍵。
LoadBalanceTimeout	取得或設定在終結之前連接集區中生存的最小時間，以秒為單位。
MaxPoolSize	取得或設定這個特定連接字串之連接集區中允許的連線數目上限。
MinPoolSize	取得或設定這個特定連接字串之連接集區中允許的連線數目下限。
MultipleActiveResultSets	若為 true，應用程式可以維護多個作用中結果集 （MARS）。 若為 false，應用程式必須先處理或取消一個批次的所有結果集，才能在該連線上執行任何其他批次。 如需詳細資訊，請參閱 多個使用中結果集 （MARS）。
MultiSubnetFailover	如果您的應用程式連線到不同子網上的 AlwaysOn 可用性群組 （AG） 或 Always On 故障轉移叢集實例 （FCI），則設定 MultiSubnetFailover=true 可提供更快速的偵測和連線到 （目前） 作用中伺服器。 如需 AlwaysOn 功能之 SqlClient 支援的詳細資訊，請參閱 SqlClient 高可用性支援、災害復原。
NetworkLibrary	取得或設定字串，其中包含用來建立 SQL Server 連線的網路連結庫名稱。
PacketSize	取得或設定網路封包的大小，以位元組為單位，用來與 SQL Server 實例通訊。
Password	取得或設定 SQL Server 帳戶的密碼。
PersistSecurityInfo	取得或設定值，指出是否應該傳回安全性敏感性資訊，例如密碼或存取令牌，作為與這個 SqlConnectionStringBuilder 建立之連線上連接字串的一部分，之後該連接已處於開啟狀態。
PoolBlockingPeriod	連接集區的封鎖期間行為。
Pooling	取得或設定 Boolean 值，這個值表示每次要求連接時，是否要集區或明確開啟連接。
Replication	取得或設定布爾值，指出是否支援使用連接進行複寫。
TransactionBinding	取得或設定字串值，這個值表示連接如何維持其與登記 System.Transactions 交易的關聯。
TransparentNetworkIPResolution	當此機碼的值設定為 true時，應用程式必須擷取特定 DNS 專案的所有 IP 位址，並嘗試與清單中的第一個 IP 位址連線。 如果未在 0.5 秒內建立連線，應用程式會嘗試平行連線到所有其他專案。 第一次回答時，應用程式會建立與受訪者IP位址的連線。
TrustServerCertificate	取得或設定值，這個值表示通道是否會在略過憑證鏈結以驗證信任時加密。
TypeSystemVersion	取得或設定字串值，指出應用程式預期的型別系統。
UserID	取得或設定連接到 SQL Server 時要使用的使用者識別碼。
UserInstance	取得或設定值，這個值表示是否要將連接從預設 SQL Server Express 實例重新導向至呼叫端帳戶下執行的運行時間起始實例。
Values	取得 ICollection，其中包含 SqlConnectionStringBuilder中的值。
WorkstationID	取得或設定連接到 SQL Server 的工作站名稱。

方法

Add(String, Object)	將具有指定索引鍵和值的專案加入至 DbConnectionStringBuilder。 (繼承來源 DbConnectionStringBuilder)
Clear()	清除 SqlConnectionStringBuilder 實例的內容。
ClearPropertyDescriptors()	清除相關聯 DbConnectionStringBuilder上 PropertyDescriptor 物件的集合。 (繼承來源 DbConnectionStringBuilder)
ContainsKey(String)	判斷 SqlConnectionStringBuilder 是否包含特定索引鍵。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
EquivalentTo(DbConnectionStringBuilder)	比較這個 DbConnectionStringBuilder 物件中的連接資訊與所提供物件中的連接資訊。 (繼承來源 DbConnectionStringBuilder)
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetProperties(Hashtable)	填入提供的 Hashtable，其中包含此 DbConnectionStringBuilder之所有屬性的相關信息。 (繼承來源 DbConnectionStringBuilder)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
Remove(String)	從 SqlConnectionStringBuilder 實例中移除具有指定索引鍵的專案。
ShouldSerialize(String)	指出指定的索引鍵是否存在於這個 SqlConnectionStringBuilder 實例中。
ToString()	傳回與此 DbConnectionStringBuilder相關聯的連接字串。 (繼承來源 DbConnectionStringBuilder)
TryGetValue(String, Object)	從這個 SqlConnectionStringBuilder擷取對應至提供之索引鍵的值。

明確介面實作

ICollection.CopyTo(Array, Int32)	從特定 Array 索引開始，將 ICollection 的專案複製到 Array。 (繼承來源 DbConnectionStringBuilder)
ICollection.IsSynchronized	取得值，指出是否同步存取 ICollection （線程安全）。 (繼承來源 DbConnectionStringBuilder)
ICollection.SyncRoot	取得對象，這個物件可用來同步存取 ICollection。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()	傳回這個元件實例的自定義屬性集合。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	傳回元件之這個實例的類別名稱。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	傳回元件之這個實例的名稱。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	傳回元件這個實例的類型轉換器。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	傳回這個元件實例的預設事件。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	傳回這個元件實例的預設屬性。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	傳回這個元件實例之指定型別的編輯器。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	傳回元件這個實例的事件。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	使用指定的屬性陣組做為篩選，傳回元件之這個實例的事件。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	傳回元件之這個實例的屬性。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	使用屬性陣組做為篩選，傳回元件實例的屬性。 (繼承來源 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	傳回 物件，其中包含指定之屬性描述項所描述的屬性。 (繼承來源 DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	將具有所提供索引鍵和值的專案加入至 IDictionary 物件。 (繼承來源 DbConnectionStringBuilder)
IDictionary.Contains(Object)	判斷 IDictionary 物件是否包含具有指定索引鍵的專案。 (繼承來源 DbConnectionStringBuilder)
IDictionary.GetEnumerator()	傳回 IDictionary 物件的 IDictionaryEnumerator 物件。 (繼承來源 DbConnectionStringBuilder)
IDictionary.Item[Object]	取得或設定具有指定索引鍵的專案。 (繼承來源 DbConnectionStringBuilder)
IDictionary.Remove(Object)	從 IDictionary 物件中移除具有指定索引鍵的專案。 (繼承來源 DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	傳回逐一查看集合的列舉值。 (繼承來源 DbConnectionStringBuilder)

擴充方法

Cast<TResult>(IEnumerable)	將 IEnumerable 的項目轉換成指定的型別。
OfType<TResult>(IEnumerable)	根據指定的型別篩選 IEnumerable 的專案。
AsParallel(IEnumerable)	啟用查詢的平行處理。
AsQueryable(IEnumerable)	將 IEnumerable 轉換成 IQueryable。

另請參閱

• 連接字串 （ADO.NET）
• ADO.NET 概觀