System.Data
2.0.0.0
System.Data.Common.DbConnectionStringBuilder
System.ComponentModel.TypeConverter("System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")
System.ComponentModel.DefaultProperty("DataSource")
The connection string builder lets developers programmatically create syntactically correct connection strings, and parse and rebuild existing connection strings, using properties and methods of the class. The connection string builder provides strongly typed properties corresponding to the known key/value pairs allowed by SQL Server. Developers needing to create connection strings as part of applications can use the class to build and modify connection strings. The class also makes it easy to manage connection strings stored in an application configuration file.
The performs checks for valid key/value pairs. Therefore, you cannot use this class to create invalid connection strings; trying to add invalid pairs will throw an exception. The class maintains a fixed collection of synonyms and can translate from a synonym to the corresponding well-known key name.
For example, when you use the Item property to retrieve a value, you can specify a string that contains any synonym for the key you need. For example, you can specify "Network Address", "addr", or any other acceptable synonym for this key within a connection string when you use any member that requires a string that contains the key name, such as the Item property or the method. See the property for a full list of acceptable synonyms.
The Item property handles tries to insert malicious entries. For example, the following code, using the default Item property (the indexer, in C#) correctly escapes the nested key/value pair:
[Visual Basic]
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)
[C#]
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);
The result is the following connection string that handles the invalid value in a safe manner:
Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";
Integrated Security=True
Provides a simple way to create and manage the contents of connection strings used by the class.
Constructor
To be added.
Initializes a new instance of the class.
2.0.0.0
Constructor
The class provides a fixed internal collection of key/value pairs. Even if you supply only a small subset of the possible connection string values in the constructor, the object always provides default values for each key/value pair. When the ConnectionString property of the object is retrieved, the string contains only key/value pairs in which the value is not the default value for the item.
Initializes a new instance of the class. The provided connection string provides the data for the instance's internal connection information.
The basis for the object's internal connection information. Parsed into name/value pairs. Invalid key names raise .
2.0.0.0
Property
System.String
To be added.
This property corresponds to the "Application Name" and "app" keys within the connection string.
Gets or sets the name of the application associated with the connection string.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Application Name")
Property
System.Boolean
To be added.
This property corresponds to the "Asynchronous Processing" and "async" keys within the connection string. In order to take advantage of the asynchronous processing provided by the object, this key/value pair must be included within the connection string of the associated object.
Gets or sets a Boolean value that indicates whether asynchronous processing is allowed by the connection created by using this connection string.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Asynchronous Processing")
Property
System.String
To be added.
This property corresponds to the "AttachDBFilename", "extended properties", and "initial file name" keys within the connection string.
AttachDBFilename is only supported for primary data files with an .mdf extension.
An error will be generated if a log file exists in the same directory as the data file and the 'database' keyword is used when attaching the primary data file. In this case, remove the log file. Once the database is attached, a new log file will be automatically generated based on the physical path.
Gets or sets a string that contains the name of the primary data file. This includes the full path name of an attachable database.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("AttachDbFilename")
System.ComponentModel.Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
Method
System.Void
The method removes all key/value pairs from the , and resets all corresponding properties. This includes setting the property to 0, and setting the property to an empty string.
Clears the contents of the instance.
2.0.0.0
Property
System.Boolean
To be added.
This property corresponds to the "Connection Reset" key within the connection string, which has been removed from version 3.5 SP1 of the .NET Framework.
Obsolete. Gets or sets a Boolean value that indicates whether the connection is reset when drawn from the connection pool.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Connection Reset")
Property
System.Int32
To be added.
This property corresponds to the "Connect Timeout", "connection timeout", and "timeout" keys within the connection string.
When opening a connection to a Azure SQL Database, set the connection timeout to 30 seconds.
Gets or sets the length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Connect Timeout")
Method
System.Boolean
Because the contains a fixed-size collection of key/value pairs, the method determines only if a particular key name is valid.
Determines whether the contains a specific key.
true if the contains an element that has the specified key; otherwise, false.
The key to locate in the .
2.0.0.0
Property
2.0.0.0
System.ComponentModel.DisplayName("Context Connection")
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.Boolean
To be added.
This property corresponds to the "Context Connection" key within the connection string.
The property returns null if the connection string for the is "context connection=true".
Gets or sets a value that indicates whether a client/server or in-process connection to SQL Server should be made.
Property
System.String
To be added.
This property corresponds to the "Current Language" and "language" keys within the connection string.
Gets or sets the SQL Server Language record name.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Current Language")
Property
System.String
To be added.
This property corresponds to the "Data Source", "server", "address", "addr", and "network address" keys within the connection string. Regardless of which of these values has been supplied within the supplied connection string, the connection string created by the SqlConnectionStringBuilder will use the well-known "Data Source" key.
Gets or sets the name or network address of the instance of SQL Server to connect to.
2.0.0.0
System.ComponentModel.TypeConverter("System.Data.SqlClient.SqlConnectionStringBuilder+SqlDataSourceConverter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Data Source")
Property
System.Boolean
To be added.
This property corresponds to the "Encrypt" key within the connection string.
Gets or sets a Boolean value that indicates whether SQL Server uses SSL encryption for all data sent between the client and server if the server has a certificate installed.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Encrypt")
Property
System.Boolean
To be added.
This property corresponds to the "Enlist" key within the connection string.
Gets or sets a Boolean value that indicates whether the SQL Server connection pooler automatically enlists the connection in the creation thread's current transaction context.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Enlist")
Property
System.String
To be added.
To be added.
Gets or sets the name or address of the partner server to connect to if the primary server is down.
2.0.0.0
System.ComponentModel.TypeConverter("System.Data.SqlClient.SqlConnectionStringBuilder+SqlDataSourceConverter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Failover Partner")
Property
System.String
To be added.
This property corresponds to the "Initial Catalog" and "database" keys within the connection string.
Gets or sets the name of the database associated with the connection.
2.0.0.0
System.ComponentModel.TypeConverter("System.Data.SqlClient.SqlConnectionStringBuilder+SqlInitialCatalogConverter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Initial Catalog")
Property
System.Boolean
To be added.
This property corresponds to the "Integrated Security" and "trusted_connection" keys within the connection string.
Gets or sets a Boolean value that indicates whether User ID and Password are specified in the connection (when false) or whether the current Windows account credentials are used for authentication (when true).
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Integrated Security")
Property
System.Boolean
To be added.
To be added.
Gets a value that indicates whether the has a fixed size.
2.0.0.0
Property
System.Object
To be added.
To be added.
To be added.
To be added.
2.0.0.0
Property
System.Collections.ICollection
To be added.
The order of the values in the is unspecified, but it is the same order as the associated values in the returned by the property.
Gets an that contains the keys in the .
2.0.0.0
Property
System.Int32
To be added.
This property corresponds to the "Load Balance Timeout" and "connection lifetime" keys within the connection string.
Gets or sets the minimum time, in seconds, for the connection to live in the connection pool before being destroyed.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Load Balance Timeout")
Property
System.Int32
To be added.
This property corresponds to the "Max Pool Size" key within the connection string.
Gets or sets the maximum number of connections allowed in the connection pool for this specific connection string.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Max Pool Size")
Property
System.Int32
To be added.
This property corresponds to the "Min Pool Size" key within the connection string.
Gets or sets the minimum number of connections allowed in the connection pool for this specific connection string.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Min Pool Size")
Property
System.Boolean
To be added.
This property corresponds to the "MultipleActiveResultSets" key within the connection string.
When true, an application can maintain multiple active result sets (MARS). When false, an application must process or cancel all result sets from one batch before it can execute any other batch on that connection.
For more information, see Multiple Active Result Sets (MARS).
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("MultipleActiveResultSets")
Property
System.String
To be added.
This property corresponds to the "Network Library", "network", and "net" keys within the connection string.
Supported values for this property include dbnmpntw (Named Pipes), dbmsrpcn (Multiprotocol), dbmsadsn (AppleTalk), dbmsgnet (VIA), dbmslpcn (Shared Memory) and dbmsspxn (IPX/SPX), and dbmssocn (TCP/IP). The corresponding network DLL must be installed on the system to which you connect. If you do not specify a network and you use a local server (for example, "." or "(local)"), Shared Memory is used.
Gets or sets a string that contains the name of the network library used to establish a connection to the SQL Server.
2.0.0.0
System.ComponentModel.TypeConverter("System.Data.SqlClient.SqlConnectionStringBuilder+NetworkLibraryConverter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Network Library")
Property
System.Int32
To be added.
This property corresponds to the "Packet Size" key within the connection string.
Gets or sets the size in bytes of the network packets used to communicate with an instance of SQL Server.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Packet Size")
Property
System.String
To be added.
This property corresponds to the "Password" and "pwd" keys within the connection string.
If has not been set and you retrieve the value, the return value is . To reset the password for the connection string, pass null to the Item property.
Gets or sets the password for the SQL Server account.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.PasswordPropertyText(true)
System.ComponentModel.DisplayName("Password")
Property
System.Boolean
To be added.
This property corresponds to the "Persist Security Info" and "persistsecurityinfo" keys within the connection string.
Gets or sets a Boolean value that indicates if security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Persist Security Info")
Property
System.Boolean
To be added.
This property corresponds to the "Pooling" key within the connection string.
Gets or sets a Boolean value that indicates whether the connection will be pooled or explicitly opened every time that the connection is requested.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Pooling")
Method
System.Boolean
Because the Remove method returns a value that indicates its success, it is not required to look for a key before trying to remove the key/value pair from the instance. Because the maintains a fixed-size collection of key/value pairs, calling the method simply resets the value of the key/value pair back to its default value.
Because the collection of keys supported by the is fixed, every item within the collection has a known default value. The following table lists the keys, and the value for each when the is first initialized, or after the method has been called.
-
Key
Default value
-
Application Name
".Net SqlClient Data Provider"
-
Asynchronous Processing
False
-
AttachDBFilename
Empty string
-
Connection Timeout
15
-
Context Connection
False
-
Current Language
Empty string
-
Data Source
Empty string
-
Encrypt
False
-
Enlist
True
-
Failover Partner
Empty string
-
Initial Catalog
Empty string
-
Integrated Security
False
-
Load Balance Timeout
0
-
Max Pool Size
100
-
Min Pool Size
0
-
MultipleActiveResultSets
False
-
Network Library
Empty string
-
Packet Size
8000
-
Password
Empty string
-
Persist Security Info
False
-
Pooling
True
-
Replication
False
-
Transaction Binding
Implicit Unbind
-
User ID
Empty string
-
User Instance
False
-
Workstation ID
Empty string
Removes the entry with the specified key from the instance.
true if the key existed within the connection string and was removed; false if the key did not exist.
The key of the key/value pair to be removed from the connection string in this .
2.0.0.0
Property
System.Boolean
To be added.
This property corresponds to the "Replication" key within the connection string.
Gets or sets a Boolean value that indicates whether replication is supported using the connection.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Replication")
Method
System.Boolean
This method behaves identically to the method.
Indicates whether the specified key exists in this instance.
true if the contains an entry with the specified key; otherwise, false.
The key to locate in the .
2.0.0.0
Property
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("TrustServerCertificate")
System.Boolean
To be added.
When TrustServerCertificate is set to true, the transport layer will use SSL to encrypt the channel and bypass walking the certificate chain to validate trust. If TrustServerCertificate is set to true and encryption is turned on, the encryption level specified on the server will be used even if Encrypt is set to false. The connection will fail otherwise.
For more information, see "Encryption Hierarchy" and "Using Encryption Without Validation" in SQL Server Books Online.
Gets or sets a value that indicates whether the channel will be encrypted while bypassing walking the certificate chain to validate trust.
Method
System.Boolean
To be added.
To be added.
To be added.
To be added.
To be added.
2.0.0.0
Property
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Type System Version")
System.String
To be added.
The TypeSystemVersion property can be used to specify a down-level version of ssNoVersion for applications written against that version. This avoids possible problems with incompatible types in a newer version of ssNoVersion that may cause the application to break.
Gets or sets a string value that indicates the type system the application expects.
Property
System.String
To be added.
This property corresponds to the "User ID", "user", and "uid" keys within the connection string.
Gets or sets the user ID to be used when connecting to SQL Server.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("User ID")
Property
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("User Instance")
System.Boolean
To be added.
This property corresponds to the "User Instance" key within the connection string.
This feature is available only with the ssNoVersion Express Edition. For more information on user instances, see Working with User Instances and "User Instances for Non-Administrators" in ssNoVersion Books Online.
Gets or sets a value that indicates whether to redirect the connection from the default SQL Server Express instance to a runtime-initiated instance running under the account of the caller.
Property
System.Collections.ICollection
To be added.
The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. Because each instance of the always contains the same fixed set of keys, the property always returns the values corresponding to the fixed set of keys, in the same order as the keys.
Gets an that contains the values in the .
2.0.0.0
Property
System.String
To be added.
This property corresponds to the "Workstation ID" and "wsid" keys within the connection string.
Gets or sets the name of the workstation connecting to SQL Server.
2.0.0.0
System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
System.ComponentModel.DisplayName("Workstation ID")