From 0c63e52d708f91319693872dd3446388dbb7e382 Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 12:43:14 -0700 Subject: [PATCH 01/12] improve connection string docs --- .../RegisterCustomKeyStoreProvider_Example.cs | 4 +- .../SqlConnection.xml | 12 +- .../SqlConnectionStringBuilder.xml | 198 ++++++++++++++---- 3 files changed, 165 insertions(+), 49 deletions(-) diff --git a/doc/samples/RegisterCustomKeyStoreProvider_Example.cs b/doc/samples/RegisterCustomKeyStoreProvider_Example.cs index 6a7543a5cf..57d9c12484 100644 --- a/doc/samples/RegisterCustomKeyStoreProvider_Example.cs +++ b/doc/samples/RegisterCustomKeyStoreProvider_Example.cs @@ -5,8 +5,8 @@ class Program { - // Links a SqlColumnEncryptionKeyStoreProvider to some object that represents a user - static Dictionary providerByUser = new(); + // Links a SqlColumnEncryptionAzureKeyVaultProvider to some object that represents a user + static Dictionary providerByUser = new(); void ExecuteSelectQuery(object user, SqlConnection connection) { diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 5942a41959..e3eed7e41b 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -524,27 +524,27 @@ End Module |Addr|N/A|Synonym of **Data Source**.| |Address|N/A|Synonym of **Data Source**.| |App|N/A|Synonym of **Application Name**.| -|Application Name|N/A|The name of the application, or '.NET SQLClient Data Provider' if no application name is provided.

An application name can be 128 characters or less.| |Application Intent

-or-

ApplicationIntent|ReadWrite|Declares the application workload type when connecting to a server. Possible values are `ReadOnly` and `ReadWrite`. For example:

`ApplicationIntent=ReadOnly`

For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](/sql/connect/ado-net/sql/sqlclient-support-high-availability-disaster-recovery).| +|Application Name|N/A|The name of the application, or 'Core Microsoft SqlClient Data Provider' if no application name is provided.

An application name can be 128 characters or less.| |Asynchronous Processing

-or-

Async|'false'|This property is obsolete and should not used.

When `true`, enables asynchronous operation support. Recognized values are `true`, `false`, `yes`, and `no`.

This property is ignored beginning in .NET Framework 4.5. For more information about SqlClient support for asynchronous programming, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).| |AttachDBFilename

-or-

Extended Properties

-or-

Initial File Name|N/A|The name of the primary database file, including the full path name of an attachable database. AttachDBFilename is only supported for primary data files with an .mdf extension.

If the value of the AttachDBFileName key is specified in the connection string, the database is attached and becomes the default database for the connection.

If this key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection.

If this key is specified together with the AttachDBFileName key, the value of this key will be used as the alias. However, if the name is already used in another attached database, the connection will fail.

The path may be absolute or relative by using the DataDirectory substitution string. If DataDirectory is used, the database file must exist within a subdirectory of the directory pointed to by the substitution string. **Note:** Remote server, HTTP, and UNC path names are not supported.

The database name must be specified with the keyword 'database' (or one of its aliases) as in the following:

"AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase"

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.| |Attestation Protocol|N/A|Gets or sets the value of Attestation Protocol.

Valid values are:
`AAS`
`HGS`| -|Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, 'Active Directory Service Principal', 'Active Directory Device Code Flow', 'Active Directory Managed Identity', 'Active Directory MSI', 'Active Directory Default', `Sql Password`. Currently `Active Directory Integrated` and `Active Directory Interactive` modes of authentication are supported only for .NET Framework. | +|Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, `Sql Password`. Currently `Active Directory Integrated` and `Active Directory Interactive` modes of authentication are supported only for .NET Framework. | |Column Encryption Setting|N/A|Enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine?view=sql-server-2017) functionality for the connection.| |Command Timeout|30|The default wait time (in seconds) before terminating the attempt to execute a command and generating an error.

Valid values are greater than or equal to 0 and less than or equal to 2147483647.| -|Connect Timeout

-or-

Connection Timeout

-or-

Timeout|15|The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.

Valid values are greater than or equal to 0 and less than or equal to 2147483647.

When opening a connection to a Azure SQL Database, set the connection timeout to 30 seconds.| -|Connection Lifetime

-or-

Load Balance Timeout|0|When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime`. This is useful in clustered configurations to force load balancing between a running server and a server just brought online.

A value of zero (0) causes pooled connections to have the maximum connection timeout.| |Connect Retry Count

-or-

ConnectRetryCount|1|Controls the number of reconnection attempts after the client identifies an idle connection failure. Valid values are 0 to 255. The default is 1. 0 means do not attempt to reconnect (disable connection resiliency).

For additional information about idle connection resiliency, see [Technical Article - Idle Connection Resiliency](https://go.microsoft.com/fwlink/?LinkId=393996).| -|Connect Retry Interval

-or-

ConnectRetryInterval|10|Specifies the time between each connection retry attempt (ConnectRetryCount). Valid values are 1 to 60 seconds (default=10), applied after the first reconnection attempt. When a broken connection is detected, the client immediately attempts to reconnect; this is the first reconnection attempt and only occurs if ConnectRetryCount is greater than 0. If the first reconnection attempt fails and ConnectRetryCount is greater than 1, the client waits ConnectRetryInterval to try the second and subsequent reconnection attempts.

For additional information about idle connection resiliency, see [Technical Article - Idle Connection Resiliency](https://go.microsoft.com/fwlink/?LinkId=393996).| +|Connect Retry Interval

-or-

ConnectRetryInterval|10|Specifies the time between each connection retry attempt (`ConnectRetryCount`). Valid values are 1 to 60 seconds (default=10), applied after the first reconnection attempt. When a broken connection is detected, the client immediately attempts to reconnect; this is the first reconnection attempt and only occurs if `ConnectRetryCount` is greater than 0. If the first reconnection attempt fails and `ConnectRetryCount` is greater than 1, the client waits `ConnectRetryInterval` to try the second and subsequent reconnection attempts.

For additional information about idle connection resiliency, see [Technical Article - Idle Connection Resiliency](https://go.microsoft.com/fwlink/?LinkId=393996).| +|Connect Timeout

-or-

Connection Timeout

-or-

Timeout|15|The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.

Valid values are greater than or equal to 0 and less than or equal to 2147483647.

When opening a connection to a Azure SQL Database, set the connection timeout to 30 seconds.| |Current Language

-or-

Language|N/A|Sets the language used for database server warning or error messages.

The language name can be 128 characters or less.| |Data Source

-or-

Server

-or-

Address

-or-

Addr

-or-

Network Address|N/A|The name or network address of the instance of SQL Server to which to connect. The port number can be specified after the server name:

`server=tcp:servername, portnumber`

When specifying a local instance, always use (local). To force a protocol, add one of the following prefixes:

`np:(local), tcp:(local), lpc:(local)`

Beginning in .NET Framework 4.5, you can also connect to a LocalDB database as follows:

`server=(localdb)\\myInstance`

For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb).

**Data Source** must use the TCP format or the Named Pipes format.

TCP format is as follows:

- tcp:\\\
- tcp:\,\

The TCP format must start with the prefix "tcp:" and is followed by the database instance, as specified by a host name and an instance name. This format is not applicable when connecting to Azure SQL Database. TCP is automatically selected for connections to Azure SQL Database when no protocol is specified.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The instance name is used to resolve to a particular TCP/IP port number on which a database instance is hosted. Alternatively, specifying a TCP/IP port number directly is also allowed. If both instance name and port number are not present, the default database instance is used.

The Named Pipes format is as follows:

- np:\\\\\pipe\\

The Named Pipes format MUST start with the prefix "np:" and is followed by a named pipe name.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The pipe name is used to identify the database instance to which the .NET Framework application will be connected.

If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" should not be specified. **Note:** You can force the use of TCP instead of shared memory, either by prefixing **tcp:** to the server name in the connection string, or by using **localhost**.| -|Enclave Attestation Url|N/A|Gets or sets the enclave attestation Url to be used with enclave based Always Encrypted.| +|Enclave Attestation Url|N/A|Gets or sets the enclave attestation URL to be used with enclave based Always Encrypted.| |Encrypt|'false'|When `true`, SQL Server uses SSL encryption for all data sent between the client and server if the server has a certificate installed. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](/sql/connect/ado-net/connection-string-syntax).

Beginning in .NET Framework 4.5, when `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Accepted wildcards used by server certificates for server authentication](https://support.microsoft.com/kb/258858).| |Enlist|'true'|`true` indicates that the SQL Server connection pooler automatically enlists the connection in the creation thread's current transaction context.| |Failover Partner|N/A|The name of the failover partner server where database mirroring is configured.

If the value of this key is "", then **Initial Catalog** must be present, and its value must not be "".

The server name can be 128 characters or less.

If you specify a failover partner but the failover partner server is not configured for database mirroring and the primary server (specified with the Server keyword) is not available, then the connection will fail.

If you specify a failover partner and the primary server is not configured for database mirroring, the connection to the primary server (specified with the Server keyword) will succeed if the primary server is available.| |Initial Catalog

-or-

Database|N/A|The name of the database.

The database name can be 128 characters or less.| |Integrated Security

-or-

Trusted_Connection|'false'|When `false`, User ID and Password are specified in the connection. When `true`, the current Windows account credentials are used for authentication.

Recognized values are `true`, `false`, `yes`, `no`, and `sspi` (strongly recommended), which is equivalent to `true`.

If User ID and Password are specified and Integrated Security is set to true, the User ID and Password will be ignored and Integrated Security will be used.

is a more secure way to specify credentials for a connection that uses SQL Server Authentication (`Integrated Security=false`).| |IP Address Preference

-or-

IPAddressPreference|IPv4First|The IP address family preference when establishing TCP connections. If `Transparent Network IP Resolution` (in .NET Framework) or `Multi Subnet Failover` is set to true, this setting has no effect. Supported values include:

`IPAddressPreference=IPv4First`

`IPAddressPreference=IPv6First`

`IPAddressPreference=UsePlatformDefault`| +|Load Balance Timeout

-or-

Connection Lifetime|0|When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime`. This is useful in clustered configurations to force load balancing between a running server and a server just brought online.

A value of zero (0) causes pooled connections to have the maximum connection timeout.| |Max Pool Size|100|The maximum number of connections that are allowed in the pool.

Valid values are greater than or equal to 1. Values that are less than **Min Pool Size** generate an error.| |Min Pool Size|0|The minimum number of connections that are allowed in the pool.

Valid values are greater than or equal to 0. Zero (0) in this field means no minimum connections are initially opened.

Values that are greater than **Max Pool Size** generate an error.| |Multiple Active Result Sets

-or-

MultipleActiveResultSets|false|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.

Recognized values are `true` and `false`.

For more information, see [Multiple Active Result Sets (MARS)](/sql/connect/ado-net/sql/multiple-active-result-sets-mars).| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index e8075d81af..c9f505f3b2 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -87,19 +87,29 @@ Integrated Security=True Declares the application workload type when connecting to a database in an SQL Server Availability Group. You can set the value of this property with . For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](/sql/connect/ado-net/sql/sqlclient-support-high-availability-disaster-recovery). - Returns the current value of the property (a value of type ). - To be added. + Returns the current value of the property. + + + Overview of the SqlClient driver Gets or sets the name of the application associated with the connection string. - The name of the application, or ".NET SqlClient Data Provider" if no name has been supplied. + The name of the application, or "Core Microsoft SqlClient Data Provider" if no name has been supplied. To set the value to null, use . - Obsolete. Gets or sets a Boolean value that indicates whether asynchronous processing is allowed by the connection created by using this connection string. + This property is obsolete and should not used. Gets or sets a Boolean value that indicates whether asynchronous processing is allowed by the connection created by using this connection string. The value of the property, or if no value has been supplied. object, this key/value pair must be included within the connection string of the associated object. +This property is ignored beginning in .NET Framework 4.5. For more information about SqlClient support for asynchronous programming, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming). + ]]> @@ -144,9 +156,20 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security 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. - + + If the value of the AttachDBFileName key is specified in the connection string, the database is attached and becomes the default database for the connection. + + If this key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection. + + If this key is specified together with the AttachDBFileName key, the value of this key will be used as the alias. However, if the name is already used in another attached database, the connection will fail. + + The path may be absolute or relative by using the DataDirectory substitution string. If DataDirectory is used, the database file must exist within a subdirectory of the directory pointed to by the substitution string. **Note:** Remote server, HTTP, and UNC path names are not supported. + + The database name must be specified with the keyword 'database' (or one of its aliases) as in the following: + + `"AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase"` + 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. - ## Examples @@ -160,10 +183,21 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security Working with Connection Strings Overview of the SqlClient driver + + Gets or sets the value of Attestation Protocol. + Returns the attestation protocol. + - Gets the authentication of the connection string. - The authentication of the connection string. - To be added. + Gets or sets the authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities). + The authentication method of the connection string. + + + Clears the contents of the instance. @@ -185,8 +219,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security Gets or sets the column encryption settings for the connection string builder. - The column encryption settings for the connection string builder. - To be added. + The column encryption settings for the connection string builder.This property enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine?view=sql-server-2017) functionality for the connection. @@ -200,6 +233,8 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security ## Remarks This property corresponds to the "Command Timeout" key within the connection string. + + Valid values are greater than or equal to 0 and less than or equal to 2147483647. ]]> @@ -232,8 +267,9 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security - Amount of time (in seconds) between each reconnection attempt after identifying that there was an idle connection failure. This must be an integer between 1 and 60. The default is 10 seconds. An will be thrown if set to a value outside of the allowed range. + Amount of time (in seconds) between each reconnection attempt after identifying that there was an idle connection failure. This must be an integer between 1 and 60. The default is 10 seconds. Amount of time (in seconds) between each reconnection attempt after identifying that there was an idle connection failure. + Value is outside of the allowed range. connection string. +This value is applied after the first reconnection attempt. When a broken connection is detected, the client immediately attempts to reconnect; this is the first reconnection attempt and only occurs if `ConnectRetryCount` is greater than 0. If the first reconnection attempt fails and `ConnectRetryCount` is greater than 1, the client waits `ConnectRetryInterval` to try the second and subsequent reconnection attempts. + ]]> @@ -256,6 +294,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security When opening a connection to a Azure SQL Database, set the connection timeout to 30 seconds. + Valid values are greater than or equal to 0 and less than or equal to 2147483647. ## Examples @@ -314,13 +353,15 @@ False - Gets or sets the SQL Server Language record name. + Gets or sets the language used for database server warning or error messages.. The value of the property, or if no value has been supplied. @@ -335,7 +376,40 @@ False ## Remarks 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. - +The port number can be specified after the server name: `server=tcp:servername, portnumber`. + +When specifying a local instance, always use (local). To force a protocol, add one of the following prefixes:`np:(local), tcp:(local), lpc:(local)`. + +Beginning in .NET Framework 4.5, you can also connect to a LocalDB database as follows: `server=(localdb)\\myInstance`. For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb). +**Data Source** must use the TCP format or the Named Pipes format. TCP format is as follows: + +- tcp:\\\ +- tcp:\,\ + +The TCP format must start with the prefix "tcp:" and is followed by the database instance, as specified by a host name and an instance name. This format is not applicable when connecting to Azure SQL Database. TCP is automatically selected for connections to Azure SQL Database when no protocol is specified. + +The host name MUST be specified in one of the following ways: +- NetBIOSName +- IPv4Address +- IPv6Address + +The instance name is used to resolve to a particular TCP/IP port number on which a database instance is hosted. Alternatively, specifying a TCP/IP port number directly is also allowed. If both instance name and port number are not present, the default database instance is used. + +The Named Pipes format is as follows: +- np:\\\\\pipe\\ + +The Named Pipes format MUST start with the prefix "np:" and is followed by a named pipe name. + +The host name MUST be specified in one of the following ways: + +- NetBIOSName +- IPv4Address +- IPv6Address + +The pipe name is used to identify the database instance to which the .NET Framework application will be connected. + +If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" should not be specified. **Note:** You can force the use of TCP instead of shared memory, either by prefixing **tcp:** to the server name in the connection string, or by using **localhost**. + ## Examples The following example demonstrates that the class converts synonyms for the "Data Source" connection string key into the well-known key: @@ -346,26 +420,10 @@ False To set the value to null, use . - - Gets or sets the value of IP address preference. - Returns IP address preference. - - - - - Gets or sets the enclave attestation Url to be used with enclave based Always Encrypted. - The enclave attestation Url. - To be added. + Gets or sets the enclave attestation URL to be used with enclave based Always Encrypted. + The enclave attestation URL. - - Set/Get the value of Attestation Protocol. - Returns Attestation Protocol. - 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. The value of the property, or if none has been supplied. @@ -375,6 +433,8 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Encrypt" key within the connection string. +Beginning in .NET Framework 4.5, when `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Enable encrypted connections to the Database Engine](sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine#certificate-requirements).| + ]]> Working with Connection Strings @@ -395,8 +455,21 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. Gets or sets the name or address of the partner server to connect to if the primary server is down. The value of the property, or if none has been supplied. - To be added. To set the value to null, use . + + + To be added. @@ -412,7 +485,7 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Initial Catalog" and "database" keys within the connection string. - + The database name can be 128 characters or less. ## Examples The following example creates a simple connection string and then uses the class to add the name of the database to the connection string. The code displays the contents of the property, just to verify that the class was able to convert from the synonym ("Database") to the appropriate property value. @@ -432,6 +505,9 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Integrated Security" and "trusted_connection" keys within the connection string. + If User ID and Password are specified and Integrated Security is set to true, the User ID and Password will be ignored and Integrated Security will be used. + + is a more secure way to specify credentials for a connection that uses SQL Server Authentication (`Integrated Security=false`). ## Examples @@ -445,6 +521,18 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ]]> + + Gets or sets the IP address family preference when establishing TCP connections. + Returns the IP address preference. + + + + Gets a value that indicates whether the has a fixed size. @@ -507,6 +595,10 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Load Balance Timeout" and "connection lifetime" keys within the connection string. +When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime`. This is useful in clustered configurations to force load balancing between a running server and a server just brought online. + +A value of zero (0) causes pooled connections to have the maximum connection timeout. + ]]> @@ -556,7 +648,14 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. If your application is connecting to an AlwaysOn availability group (AG) on different subnets, setting MultiSubnetFailover=true provides faster detection of and connection to the (currently) active server. For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](/sql/connect/ado-net/sql/sqlclient-support-high-availability-disaster-recovery). Returns indicating the current value of the property. - To be added. + + + Gets or sets a string that contains the name of the network library used to establish a connection to the SQL Server. @@ -582,6 +681,8 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Packet Size" key within the connection string. +The packet size can be greater than or equal to 512 and less than or equal to 32768. + ]]> @@ -593,9 +694,12 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Password" and "pwd" keys within the connection string. + +Setting this property is not recommended. To maintain a high level of security, we strongly recommend that you use the `Integrated Security` or `Trusted_Connection` keyword instead. is a more secure way to specify credentials for a connection that uses SQL Server Authentication. 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. +The password must be 128 characters or less. ## Examples @@ -616,6 +720,8 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Persist Security Info" and "persistsecurityinfo" keys within the connection string. + Resetting the connection string resets all connection string values including the password. + ]]> @@ -645,6 +751,8 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. ## Remarks This property corresponds to the "Pooling" key within the connection string. +Connections are considered the same if they have the same connection string. Different connections have different connection strings. + ]]> @@ -663,7 +771,7 @@ If `Multi Subnet Failover` is set to `true`, this setting has no effect. |Key|Default value| |---------|-------------------| -|Application Name|".Net SqlClient Data Provider"| +|Application Name|"Core Microsoft SqlClient Data Provider"| |Asynchronous Processing(Obsolete)|False| |AttachDBFilename|Empty string| |Connection Timeout|15| @@ -741,7 +849,7 @@ Database = AdventureWorks Gets or sets a string value that indicates how the connection maintains its association with an enlisted transaction. - The value of the property, or if none has been supplied. + The value of the property, or `Implicit Unbind` if none has been supplied. Gets or sets a value that indicates whether the channel will be encrypted while bypassing walking the certificate chain to validate trust. - A . Recognized values are , , , and . + A boolean. The default is `false`. is a more secure way to specify credentials for a connection that uses SQL Server Authentication. + + The user ID must be 128 characters or less. + ]]> To set the value to null, use . @@ -926,7 +1040,9 @@ Unable to retrieve value for null key. ## Remarks This property corresponds to the "Workstation ID" and "wsid" keys within the connection string. - + + The ID must be 128 characters or less. + ]]> To set the value to null, use . From 644734a70d2b58f8cb39bb671f3a4ead2d1a34ca Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 12:44:41 -0700 Subject: [PATCH 02/12] Update RegisterCustomKeyStoreProvider_Example.cs --- doc/samples/RegisterCustomKeyStoreProvider_Example.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/samples/RegisterCustomKeyStoreProvider_Example.cs b/doc/samples/RegisterCustomKeyStoreProvider_Example.cs index 57d9c12484..334b1264c1 100644 --- a/doc/samples/RegisterCustomKeyStoreProvider_Example.cs +++ b/doc/samples/RegisterCustomKeyStoreProvider_Example.cs @@ -5,7 +5,7 @@ class Program { - // Links a SqlColumnEncryptionAzureKeyVaultProvider to some object that represents a user + // Maps a SqlColumnEncryptionAzureKeyVaultProvider to some object that represents a user static Dictionary providerByUser = new(); void ExecuteSelectQuery(object user, SqlConnection connection) From 32dd28bfc544fde8e6e5e9d96abbe2a2f74383ea Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 15:59:57 -0700 Subject: [PATCH 03/12] remove asynchronousprocessing --- ...ionStringBuilder_AsynchronousProcessing.cs | 88 ------------------- .../SqlConnectionStringBuilder.xml | 17 ---- .../Data/Common/DbConnectionStringCommon.cs | 4 - .../Data/SqlClient/SqlConnectionString.cs | 5 -- .../SqlClient/SqlConnectionStringBuilder.cs | 3 - .../netfx/ref/Microsoft.Data.SqlClient.cs | 5 -- .../Data/Common/DbConnectionStringCommon.cs | 5 -- .../Data/SqlClient/SqlConnectionString.cs | 5 -- .../SqlClient/SqlConnectionStringBuilder.cs | 33 ------- .../Data/SqlClient/SqlDependencyListener.cs | 3 - .../netfx/src/Resources/Strings.Designer.cs | 9 -- .../netfx/src/Resources/Strings.de.resx | 3 - 12 files changed, 180 deletions(-) delete mode 100644 doc/samples/SqlConnectionStringBuilder_AsynchronousProcessing.cs diff --git a/doc/samples/SqlConnectionStringBuilder_AsynchronousProcessing.cs b/doc/samples/SqlConnectionStringBuilder_AsynchronousProcessing.cs deleted file mode 100644 index b3706e86bd..0000000000 --- a/doc/samples/SqlConnectionStringBuilder_AsynchronousProcessing.cs +++ /dev/null @@ -1,88 +0,0 @@ -using System; -using System.Data; -// -using Microsoft.Data.SqlClient; -using System.Threading; - -class Program -{ - static void Main() - { - // Create a SqlConnectionStringBuilder instance, - // and ensure that it is set up for asynchronous processing. - SqlConnectionStringBuilder builder = - new SqlConnectionStringBuilder(GetConnectionString()); - // Asynchronous method calls won't work unless you - // have added this option, or have added - // the clause "Asynchronous Processing=true" - // to the connection string. - builder.AsynchronousProcessing = true; - - string commandText = - "UPDATE Production.Product SET ReorderPoint = ReorderPoint + 1 " + - "WHERE ReorderPoint IS NOT Null;" + - "WAITFOR DELAY '0:0:3';" + - "UPDATE Production.Product SET ReorderPoint = ReorderPoint - 1 " + - "WHERE ReorderPoint IS NOT Null"; - RunCommandAsynchronously(commandText, builder.ConnectionString); - - Console.WriteLine("Press any key 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 "Data Source=(local);Integrated Security=SSPI;" + - "Initial Catalog=AdventureWorks"; - } - - private static void RunCommandAsynchronously(string commandText, - string connectionString) - { - // Given command text and connection string, asynchronously execute - // the specified command against the connection. For this example, - // the code displays an indicator as it's working, verifying the - // asynchronous behavior. - using (SqlConnection connection = new SqlConnection(connectionString)) - { - try - { - int count = 0; - SqlCommand command = new SqlCommand(commandText, connection); - connection.Open(); - IAsyncResult result = command.BeginExecuteNonQuery(); - while (!result.IsCompleted) - { - Console.WriteLine("Waiting {0}.", count); - // Wait for 1/10 second, so the counter - // doesn't consume all available resources - // on the main thread. - Thread.Sleep(100); - count += 1; - } - Console.WriteLine("Command complete. Affected {0} rows.", - command.EndExecuteNonQuery(result)); - - } - catch (SqlException ex) - { - Console.WriteLine( - "Error {0}: Microsoft.Data.SqlClient.SqlConnectionStringBuilder", - ex.Number, ex.Message); - } - catch (InvalidOperationException ex) - { - Console.WriteLine("Error: {0}", ex.Message); - } - catch (Exception ex) - { - // You might want to pass these errors - // back out to the caller. - Console.WriteLine("Error: {0}", ex.Message); - } - } - } -} -// diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index c9f505f3b2..575d9eb599 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -129,23 +129,6 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security To set the value to null, use . - - This property is obsolete and should not used. Gets or sets a Boolean value that indicates whether asynchronous processing is allowed by the connection created by using this connection string. - The value of the property, or if no value has been supplied. - - object, this key/value pair must be included within the connection string of the associated object. - -This property is ignored beginning in .NET Framework 4.5. For more information about SqlClient support for asynchronous programming, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming). - - ]]> - - - - - Gets or sets a string that contains the name of the primary data file. This includes the full path name of an attachable database. The value of the property, or if no value has been supplied. diff --git a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs index 239e7e2715..f18f1af0bc 100644 --- a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs +++ b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs @@ -890,7 +890,6 @@ internal static partial class DbConnectionStringKeywords // SqlClient internal const string ApplicationIntent = "Application Intent"; internal const string ApplicationName = "Application Name"; - internal const string AsynchronousProcessing = "Asynchronous Processing"; internal const string AttachDBFilename = "AttachDbFilename"; internal const string CommandTimeout = "Command Timeout"; internal const string ConnectTimeout = "Connect Timeout"; @@ -939,9 +938,6 @@ internal static partial class DbConnectionStringKeywords internal static class DbConnectionStringSynonyms { - //internal const string AsynchronousProcessing = Async; - internal const string Async = "async"; - //internal const string ApplicationName = APP; internal const string APP = "app"; diff --git a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionString.cs b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionString.cs index 7752feb4f0..b68f19354b 100644 --- a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionString.cs +++ b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionString.cs @@ -62,7 +62,6 @@ internal static class KEY { internal const string ApplicationIntent = "application intent"; internal const string Application_Name = "application name"; - internal const string AsynchronousProcessing = "asynchronous processing"; internal const string AttachDBFilename = "attachdbfilename"; #if NETCOREAPP internal const string PoolBlockingPeriod = "pool blocking period"; @@ -114,7 +113,6 @@ private static class SYNONYM internal const string APPLICATIONINTENT = "applicationintent"; // application name internal const string APP = "app"; - internal const string Async = "async"; // attachDBFilename internal const string EXTENDED_PROPERTIES = "extended properties"; internal const string INITIAL_FILE_NAME = "initial file name"; @@ -252,7 +250,6 @@ internal static class TRANSACTIONBINDING internal SqlConnectionString(string connectionString) : base(connectionString, GetParseSynonyms()) { - ThrowUnsupportedIfKeywordSet(KEY.AsynchronousProcessing); ThrowUnsupportedIfKeywordSet(KEY.Connection_Reset); ThrowUnsupportedIfKeywordSet(KEY.Context_Connection); @@ -660,7 +657,6 @@ internal static Dictionary GetParseSynonyms() { { KEY.ApplicationIntent, KEY.ApplicationIntent }, { KEY.Application_Name, KEY.Application_Name }, - { KEY.AsynchronousProcessing, KEY.AsynchronousProcessing }, { KEY.AttachDBFilename, KEY.AttachDBFilename }, #if NETCOREAPP { KEY.PoolBlockingPeriod, KEY.PoolBlockingPeriod}, @@ -703,7 +699,6 @@ internal static Dictionary GetParseSynonyms() { SYNONYM.APP, KEY.Application_Name }, { SYNONYM.APPLICATIONINTENT, KEY.ApplicationIntent }, - { SYNONYM.Async, KEY.AsynchronousProcessing }, { SYNONYM.EXTENDED_PROPERTIES, KEY.AttachDBFilename }, { SYNONYM.INITIAL_FILE_NAME, KEY.AttachDBFilename }, { SYNONYM.CONNECTRETRYCOUNT, KEY.Connect_Retry_Count }, diff --git a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs index 9102b07a4a..4a850575a8 100644 --- a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs +++ b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs @@ -1234,12 +1234,9 @@ public override bool TryGetValue(string keyword, out object value) } private static readonly string[] s_notSupportedKeywords = new string[] { - DbConnectionStringKeywords.AsynchronousProcessing, DbConnectionStringKeywords.ConnectionReset, DbConnectionStringKeywords.ContextConnection, DbConnectionStringKeywords.TransactionBinding, - - DbConnectionStringSynonyms.Async }; private static readonly string[] s_notSupportedNetworkLibraryKeywords = new string[] { diff --git a/src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.cs b/src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.cs index 93adb4b621..42066ed59d 100644 --- a/src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.cs +++ b/src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.cs @@ -932,11 +932,6 @@ public SqlConnectionStringBuilder(string connectionString) { } [System.ComponentModel.DisplayNameAttribute("Application Name")] [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)] public string ApplicationName { get { throw null; } set { } } - /// - [System.ComponentModel.DisplayNameAttribute("Asynchronous Processing")] - [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)] - [System.ObsoleteAttribute("AsynchronousProcessing has been deprecated. SqlConnection will ignore the 'Asynchronous Processing' keyword and always allow asynchronous processing.")] - public bool AsynchronousProcessing { get { throw null; } set { } } /// [System.ComponentModel.DisplayNameAttribute("AttachDbFilename")] [System.ComponentModel.EditorAttribute("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/Common/DbConnectionStringCommon.cs b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/Common/DbConnectionStringCommon.cs index f37aed4a2d..49ebbb1ebf 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/Common/DbConnectionStringCommon.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/Common/DbConnectionStringCommon.cs @@ -1178,7 +1178,6 @@ internal static class DbConnectionStringDefaults // SqlClient internal const ApplicationIntent ApplicationIntent = Microsoft.Data.SqlClient.ApplicationIntent.ReadWrite; internal const string ApplicationName = "Framework Microsoft SqlClient Data Provider"; - internal const bool AsynchronousProcessing = false; internal const string AttachDBFilename = _emptyString; internal const int CommandTimeout = 30; internal const int ConnectTimeout = 15; @@ -1262,7 +1261,6 @@ internal static class DbConnectionStringKeywords // SqlClient internal const string ApplicationIntent = "Application Intent"; internal const string ApplicationName = "Application Name"; - internal const string AsynchronousProcessing = "Asynchronous Processing"; internal const string AttachDBFilename = "AttachDbFilename"; internal const string ConnectTimeout = "Connect Timeout"; internal const string CommandTimeout = "Command Timeout"; @@ -1310,9 +1308,6 @@ internal static class DbConnectionStringKeywords internal static class DbConnectionStringSynonyms { - //internal const string AsynchronousProcessing = Async; - internal const string Async = "async"; - //internal const string ApplicationName = APP; internal const string APP = "app"; diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionString.cs b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionString.cs index bc01c7491c..ce776de882 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionString.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionString.cs @@ -71,7 +71,6 @@ internal static class KEY { internal const string ApplicationIntent = "application intent"; internal const string Application_Name = "application name"; - internal const string AsynchronousProcessing = "asynchronous processing"; internal const string AttachDBFilename = "attachdbfilename"; internal const string PoolBlockingPeriod = "pool blocking period"; internal const string ColumnEncryptionSetting = "column encryption setting"; @@ -290,8 +289,6 @@ internal SqlConnectionString(string connectionString) : base(connectionString, G _integratedSecurity = ConvertValueToIntegratedSecurity(); - ConvertValueToBoolean(KEY.AsynchronousProcessing, DEFAULT.Asynchronous); // while we don't use it anymore, we still need to verify it is true/false - // SQLPT 41700: Ignore ResetConnection=False (still validate the keyword/value) _poolBlockingPeriod = ConvertValueToPoolBlockingPeriod(); _connectionReset = ConvertValueToBoolean(KEY.Connection_Reset, DEFAULT.Connection_Reset); @@ -796,7 +793,6 @@ internal static Hashtable GetParseSynonyms() hash = new Hashtable(SqlConnectionStringBuilder.KeywordsCount + SynonymCount); hash.Add(KEY.ApplicationIntent, KEY.ApplicationIntent); hash.Add(KEY.Application_Name, KEY.Application_Name); - hash.Add(KEY.AsynchronousProcessing, KEY.AsynchronousProcessing); hash.Add(KEY.AttachDBFilename, KEY.AttachDBFilename); hash.Add(KEY.PoolBlockingPeriod, KEY.PoolBlockingPeriod); hash.Add(KEY.Connect_Timeout, KEY.Connect_Timeout); @@ -840,7 +836,6 @@ internal static Hashtable GetParseSynonyms() #endif hash.Add(SYNONYM.APPLICATIONINTENT, KEY.ApplicationIntent); hash.Add(SYNONYM.APP, KEY.Application_Name); - hash.Add(SYNONYM.Async, KEY.AsynchronousProcessing); hash.Add(SYNONYM.EXTENDED_PROPERTIES, KEY.AttachDBFilename); hash.Add(SYNONYM.INITIAL_FILE_NAME, KEY.AttachDBFilename); hash.Add(SYNONYM.CONNECTION_TIMEOUT, KEY.Connect_Timeout); diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs index 15590fe981..19bec77b80 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs @@ -37,7 +37,6 @@ private enum Keywords MinPoolSize, MaxPoolSize, PoolBlockingPeriod, - AsynchronousProcessing, ConnectionReset, MultipleActiveResultSets, Replication, @@ -101,7 +100,6 @@ private enum Keywords private int _packetSize = DbConnectionStringDefaults.PacketSize; private int _connectRetryCount = DbConnectionStringDefaults.ConnectRetryCount; private int _connectRetryInterval = DbConnectionStringDefaults.ConnectRetryInterval; - private bool _asynchronousProcessing = DbConnectionStringDefaults.AsynchronousProcessing; private bool _connectionReset = DbConnectionStringDefaults.ConnectionReset; private bool _contextConnection = DbConnectionStringDefaults.ContextConnection; private bool _encrypt = DbConnectionStringDefaults.Encrypt; @@ -131,7 +129,6 @@ static SqlConnectionStringBuilder() string[] validKeywords = new string[KeywordsCount]; validKeywords[(int)Keywords.ApplicationIntent] = DbConnectionStringKeywords.ApplicationIntent; validKeywords[(int)Keywords.ApplicationName] = DbConnectionStringKeywords.ApplicationName; - validKeywords[(int)Keywords.AsynchronousProcessing] = DbConnectionStringKeywords.AsynchronousProcessing; validKeywords[(int)Keywords.AttachDBFilename] = DbConnectionStringKeywords.AttachDBFilename; validKeywords[(int)Keywords.PoolBlockingPeriod] = DbConnectionStringKeywords.PoolBlockingPeriod; validKeywords[(int)Keywords.ConnectionReset] = DbConnectionStringKeywords.ConnectionReset; @@ -179,7 +176,6 @@ static SqlConnectionStringBuilder() Dictionary hash = new Dictionary(KeywordsCount + SqlConnectionString.SynonymCount, StringComparer.OrdinalIgnoreCase); hash.Add(DbConnectionStringKeywords.ApplicationIntent, Keywords.ApplicationIntent); hash.Add(DbConnectionStringKeywords.ApplicationName, Keywords.ApplicationName); - hash.Add(DbConnectionStringKeywords.AsynchronousProcessing, Keywords.AsynchronousProcessing); hash.Add(DbConnectionStringKeywords.AttachDBFilename, Keywords.AttachDBFilename); hash.Add(DbConnectionStringKeywords.PoolBlockingPeriod, Keywords.PoolBlockingPeriod); hash.Add(DbConnectionStringKeywords.ConnectTimeout, Keywords.ConnectTimeout); @@ -225,7 +221,6 @@ static SqlConnectionStringBuilder() hash.Add(DbConnectionStringSynonyms.IPADDRESSPREFERENCE, Keywords.IPAddressPreference); hash.Add(DbConnectionStringSynonyms.APP, Keywords.ApplicationName); hash.Add(DbConnectionStringSynonyms.APPLICATIONINTENT, Keywords.ApplicationIntent); - hash.Add(DbConnectionStringSynonyms.Async, Keywords.AsynchronousProcessing); hash.Add(DbConnectionStringSynonyms.EXTENDEDPROPERTIES, Keywords.AttachDBFilename); hash.Add(DbConnectionStringSynonyms.INITIALFILENAME, Keywords.AttachDBFilename); hash.Add(DbConnectionStringSynonyms.CONNECTIONTIMEOUT, Keywords.ConnectTimeout); @@ -370,11 +365,6 @@ public override object this[string keyword] Certificate = ConvertToString(value); break; #endif -#pragma warning disable 618 // Obsolete AsynchronousProcessing - case Keywords.AsynchronousProcessing: - AsynchronousProcessing = ConvertToBoolean(value); - break; -#pragma warning restore 618 case Keywords.PoolBlockingPeriod: PoolBlockingPeriod = ConvertToPoolBlockingPeriod(keyword, value); break; @@ -471,22 +461,6 @@ public string ApplicationName } } - /// - [DisplayName(DbConnectionStringKeywords.AsynchronousProcessing)] - [Obsolete("AsynchronousProcessing has been deprecated. SqlConnection will ignore the 'Asynchronous Processing' keyword and always allow asynchronous processing.")] - [ResCategoryAttribute(StringsHelper.ResourceNames.DataCategory_Initialization)] - [ResDescriptionAttribute(StringsHelper.ResourceNames.DbConnectionString_AsynchronousProcessing)] - [RefreshPropertiesAttribute(RefreshProperties.All)] - public bool AsynchronousProcessing - { - get { return _asynchronousProcessing; } - set - { - SetValue(DbConnectionStringKeywords.AsynchronousProcessing, value); - _asynchronousProcessing = value; - } - } - /// [DisplayName(DbConnectionStringKeywords.AttachDBFilename)] [ResCategoryAttribute(StringsHelper.ResourceNames.DataCategory_Source)] @@ -1311,10 +1285,6 @@ private object GetAt(Keywords index) return this.ApplicationIntent; case Keywords.ApplicationName: return ApplicationName; -#pragma warning disable 618 // Obsolete AsynchronousProcessing - case Keywords.AsynchronousProcessing: - return AsynchronousProcessing; -#pragma warning restore 618 case Keywords.AttachDBFilename: return AttachDBFilename; case Keywords.PoolBlockingPeriod: @@ -1468,9 +1438,6 @@ private void Reset(Keywords index) case Keywords.ApplicationName: _applicationName = DbConnectionStringDefaults.ApplicationName; break; - case Keywords.AsynchronousProcessing: - _asynchronousProcessing = DbConnectionStringDefaults.AsynchronousProcessing; - break; case Keywords.AttachDBFilename: _attachDBFilename = DbConnectionStringDefaults.AttachDBFilename; break; diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlDependencyListener.cs b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlDependencyListener.cs index 0f00a3ffdb..23dba04f58 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlDependencyListener.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlDependencyListener.cs @@ -1536,9 +1536,6 @@ private static SqlConnectionContainerHashHelper GetHashHelper(string connectionS // This logic is done here to enable us to have the complete connection string now to be used // for tracing as we flow through the logic. connectionStringBuilder = new SqlConnectionStringBuilder(connectionString); -#pragma warning disable CS0618 // Obsolete AsynchronousProcessing - connectionStringBuilder.AsynchronousProcessing = true; -#pragma warning restore CS0618 connectionStringBuilder.Pooling = false; connectionStringBuilder.Enlist = false; connectionStringBuilder.ConnectRetryCount = 0; diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs index bf23167d40..19647ab984 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs @@ -5550,15 +5550,6 @@ internal static string DbConnectionString_ApplicationName { } } - /// - /// Looks up a localized string similar to When true, enables usage of the Asynchronous functionality in the .NET Framework Data Provider.. - /// - internal static string DbConnectionString_AsynchronousProcessing { - get { - return ResourceManager.GetString("DbConnectionString_AsynchronousProcessing", resourceCulture); - } - } - /// /// Looks up a localized string similar to The name of the primary file, including the full path name, of an attachable database.. /// diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.de.resx b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.de.resx index cdd2c85eb3..be05a33255 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.de.resx +++ b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.de.resx @@ -3201,9 +3201,6 @@ Der Name der Anwendung. - - Bei Festlegung auf TRUE wird die Verwendung der asynchronen Funktionalität im .NET Framework-Datenanbieter aktiviert. - Der Name der primären Datei, einschließlich dem vollständigen Pfadnamen, einer anfügbaren Datenbank. From 3a2bde4df54b8f08a96ce43fc856fa928e76ffb7 Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:02:51 -0700 Subject: [PATCH 04/12] remove asynchronousprocessing --- .../Microsoft.Data.SqlClient/SqlConnection.xml | 1 - .../SqlConnectionStringBuilder.xml | 1 - .../netfx/src/Resources/Strings.Designer.cs | 18 ------------------ .../SqlConnectionStringBuilderTest.cs | 1 - 4 files changed, 21 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index e3eed7e41b..1970ab42d0 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -526,7 +526,6 @@ End Module |App|N/A|Synonym of **Application Name**.| |Application Intent

-or-

ApplicationIntent|ReadWrite|Declares the application workload type when connecting to a server. Possible values are `ReadOnly` and `ReadWrite`. For example:

`ApplicationIntent=ReadOnly`

For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](/sql/connect/ado-net/sql/sqlclient-support-high-availability-disaster-recovery).| |Application Name|N/A|The name of the application, or 'Core Microsoft SqlClient Data Provider' if no application name is provided.

An application name can be 128 characters or less.| -|Asynchronous Processing

-or-

Async|'false'|This property is obsolete and should not used.

When `true`, enables asynchronous operation support. Recognized values are `true`, `false`, `yes`, and `no`.

This property is ignored beginning in .NET Framework 4.5. For more information about SqlClient support for asynchronous programming, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).| |AttachDBFilename

-or-

Extended Properties

-or-

Initial File Name|N/A|The name of the primary database file, including the full path name of an attachable database. AttachDBFilename is only supported for primary data files with an .mdf extension.

If the value of the AttachDBFileName key is specified in the connection string, the database is attached and becomes the default database for the connection.

If this key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection.

If this key is specified together with the AttachDBFileName key, the value of this key will be used as the alias. However, if the name is already used in another attached database, the connection will fail.

The path may be absolute or relative by using the DataDirectory substitution string. If DataDirectory is used, the database file must exist within a subdirectory of the directory pointed to by the substitution string. **Note:** Remote server, HTTP, and UNC path names are not supported.

The database name must be specified with the keyword 'database' (or one of its aliases) as in the following:

"AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase"

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.| |Attestation Protocol|N/A|Gets or sets the value of Attestation Protocol.

Valid values are:
`AAS`
`HGS`| |Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, `Sql Password`. Currently `Active Directory Integrated` and `Active Directory Interactive` modes of authentication are supported only for .NET Framework. | diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 575d9eb599..f26a7891c8 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -755,7 +755,6 @@ Connections are considered the same if they have the same connection string. Dif |Key|Default value| |---------|-------------------| |Application Name|"Core Microsoft SqlClient Data Provider"| -|Asynchronous Processing(Obsolete)|False| |AttachDBFilename|Empty string| |Connection Timeout|15| |Context Connection(Obsolete)|False| diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs index 19647ab984..3558686c4b 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Resources/Strings.Designer.cs @@ -8856,15 +8856,6 @@ internal static string SQL_ArgumentLengthMismatch { } } - /// - /// Looks up a localized string similar to This command requires an asynchronous connection. Set "Asynchronous Processing=true" in the connection string.. - /// - internal static string SQL_AsyncConnectionRequired { - get { - return ResourceManager.GetString("SQL_AsyncConnectionRequired", resourceCulture); - } - } - /// /// Looks up a localized string similar to The asynchronous operation has already completed.. /// @@ -10539,15 +10530,6 @@ internal static string SqlConnection_AccessToken { } } - /// - /// Looks up a localized string similar to State of connection, synchronous or asynchronous. 'Asynchronous Processing=x' in the connection string.. - /// - internal static string SqlConnection_Asynchronous { - get { - return ResourceManager.GetString("SqlConnection_Asynchronous", resourceCulture); - } - } - /// /// Looks up a localized string similar to A guid to represent the physical connection.. /// diff --git a/src/Microsoft.Data.SqlClient/tests/FunctionalTests/SqlConnectionStringBuilderTest.cs b/src/Microsoft.Data.SqlClient/tests/FunctionalTests/SqlConnectionStringBuilderTest.cs index 5c44a5830c..c9a2bfe658 100644 --- a/src/Microsoft.Data.SqlClient/tests/FunctionalTests/SqlConnectionStringBuilderTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/FunctionalTests/SqlConnectionStringBuilderTest.cs @@ -86,7 +86,6 @@ public void ConnectionStringTests(string connectionString) } [Theory] - [InlineData("Asynchronous Processing = True")] [InlineData("Context Connection = false")] [InlineData("Network Library = dbmssocn")] [InlineData("Network = dbnmpntw")] From 5bec9291faf9c67d785d79512567bd99b2b57fdb Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:06:26 -0700 Subject: [PATCH 05/12] Update doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml Co-authored-by: Cheena Malhotra --- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index f26a7891c8..db79dcd29e 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -389,7 +389,7 @@ The host name MUST be specified in one of the following ways: - IPv4Address - IPv6Address -The pipe name is used to identify the database instance to which the .NET Framework application will be connected. +The pipe name is used to identify the database instance to which the .NET application will connect. If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" should not be specified. **Note:** You can force the use of TCP instead of shared memory, either by prefixing **tcp:** to the server name in the connection string, or by using **localhost**. From f968090dc65bf7926591bdd90ed049c0655cef7d Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:06:47 -0700 Subject: [PATCH 06/12] Update doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml Co-authored-by: Cheena Malhotra --- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index db79dcd29e..0c170cd06c 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -363,7 +363,7 @@ The port number can be specified after the server name: `server=tcp:servername, When specifying a local instance, always use (local). To force a protocol, add one of the following prefixes:`np:(local), tcp:(local), lpc:(local)`. -Beginning in .NET Framework 4.5, you can also connect to a LocalDB database as follows: `server=(localdb)\\myInstance`. For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb). +You can also connect to a LocalDB database as follows: `server=(localdb)\\myInstance`. For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb). **Data Source** must use the TCP format or the Named Pipes format. TCP format is as follows: - tcp:\\\ From a4d2f3e712cdaee256aa325340c399a92d715655 Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:07:04 -0700 Subject: [PATCH 07/12] Update doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml Co-authored-by: Cheena Malhotra --- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 0c170cd06c..12d2cd0ebd 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -416,7 +416,7 @@ If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" ## Remarks This property corresponds to the "Encrypt" key within the connection string. -Beginning in .NET Framework 4.5, when `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Enable encrypted connections to the Database Engine](sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine#certificate-requirements).| +When `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Enable encrypted connections to the Database Engine](sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine#certificate-requirements).| ]]> From a8b73d48881163c37693d1d68dc5c349e6244db8 Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:07:17 -0700 Subject: [PATCH 08/12] Update doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml Co-authored-by: Cheena Malhotra --- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 12d2cd0ebd..19f123c65c 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -202,7 +202,7 @@ Currently Active Directory Integrated and Active Directory Interactive modes of Gets or sets the column encryption settings for the connection string builder. - The column encryption settings for the connection string builder.This property enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine?view=sql-server-2017) functionality for the connection. + The column encryption settings for the connection string builder.This property enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine) functionality for the connection. From f7cf55b5d3d066729c4012a0171de2bd6ef7a04c Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:12:27 -0700 Subject: [PATCH 09/12] address feedback --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 8 ++++---- .../SqlConnectionStringBuilder.xml | 3 +-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 1970ab42d0..69fc20cb7b 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -528,16 +528,16 @@ End Module |Application Name|N/A|The name of the application, or 'Core Microsoft SqlClient Data Provider' if no application name is provided.

An application name can be 128 characters or less.| |AttachDBFilename

-or-

Extended Properties

-or-

Initial File Name|N/A|The name of the primary database file, including the full path name of an attachable database. AttachDBFilename is only supported for primary data files with an .mdf extension.

If the value of the AttachDBFileName key is specified in the connection string, the database is attached and becomes the default database for the connection.

If this key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection.

If this key is specified together with the AttachDBFileName key, the value of this key will be used as the alias. However, if the name is already used in another attached database, the connection will fail.

The path may be absolute or relative by using the DataDirectory substitution string. If DataDirectory is used, the database file must exist within a subdirectory of the directory pointed to by the substitution string. **Note:** Remote server, HTTP, and UNC path names are not supported.

The database name must be specified with the keyword 'database' (or one of its aliases) as in the following:

"AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase"

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.| |Attestation Protocol|N/A|Gets or sets the value of Attestation Protocol.

Valid values are:
`AAS`
`HGS`| -|Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, `Sql Password`. Currently `Active Directory Integrated` and `Active Directory Interactive` modes of authentication are supported only for .NET Framework. | -|Column Encryption Setting|N/A|Enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine?view=sql-server-2017) functionality for the connection.| +|Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, `Sql Password`.| +|Column Encryption Setting|N/A|Enables or disables [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine) functionality for the connection.| |Command Timeout|30|The default wait time (in seconds) before terminating the attempt to execute a command and generating an error.

Valid values are greater than or equal to 0 and less than or equal to 2147483647.| |Connect Retry Count

-or-

ConnectRetryCount|1|Controls the number of reconnection attempts after the client identifies an idle connection failure. Valid values are 0 to 255. The default is 1. 0 means do not attempt to reconnect (disable connection resiliency).

For additional information about idle connection resiliency, see [Technical Article - Idle Connection Resiliency](https://go.microsoft.com/fwlink/?LinkId=393996).| |Connect Retry Interval

-or-

ConnectRetryInterval|10|Specifies the time between each connection retry attempt (`ConnectRetryCount`). Valid values are 1 to 60 seconds (default=10), applied after the first reconnection attempt. When a broken connection is detected, the client immediately attempts to reconnect; this is the first reconnection attempt and only occurs if `ConnectRetryCount` is greater than 0. If the first reconnection attempt fails and `ConnectRetryCount` is greater than 1, the client waits `ConnectRetryInterval` to try the second and subsequent reconnection attempts.

For additional information about idle connection resiliency, see [Technical Article - Idle Connection Resiliency](https://go.microsoft.com/fwlink/?LinkId=393996).| |Connect Timeout

-or-

Connection Timeout

-or-

Timeout|15|The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.

Valid values are greater than or equal to 0 and less than or equal to 2147483647.

When opening a connection to a Azure SQL Database, set the connection timeout to 30 seconds.| |Current Language

-or-

Language|N/A|Sets the language used for database server warning or error messages.

The language name can be 128 characters or less.| -|Data Source

-or-

Server

-or-

Address

-or-

Addr

-or-

Network Address|N/A|The name or network address of the instance of SQL Server to which to connect. The port number can be specified after the server name:

`server=tcp:servername, portnumber`

When specifying a local instance, always use (local). To force a protocol, add one of the following prefixes:

`np:(local), tcp:(local), lpc:(local)`

Beginning in .NET Framework 4.5, you can also connect to a LocalDB database as follows:

`server=(localdb)\\myInstance`

For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb).

**Data Source** must use the TCP format or the Named Pipes format.

TCP format is as follows:

- tcp:\\\
- tcp:\,\

The TCP format must start with the prefix "tcp:" and is followed by the database instance, as specified by a host name and an instance name. This format is not applicable when connecting to Azure SQL Database. TCP is automatically selected for connections to Azure SQL Database when no protocol is specified.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The instance name is used to resolve to a particular TCP/IP port number on which a database instance is hosted. Alternatively, specifying a TCP/IP port number directly is also allowed. If both instance name and port number are not present, the default database instance is used.

The Named Pipes format is as follows:

- np:\\\\\pipe\\

The Named Pipes format MUST start with the prefix "np:" and is followed by a named pipe name.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The pipe name is used to identify the database instance to which the .NET Framework application will be connected.

If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" should not be specified. **Note:** You can force the use of TCP instead of shared memory, either by prefixing **tcp:** to the server name in the connection string, or by using **localhost**.| +|Data Source

-or-

Server

-or-

Address

-or-

Addr

-or-

Network Address|N/A|The name or network address of the instance of SQL Server to which to connect. The port number can be specified after the server name:

`server=tcp:servername, portnumber`

When specifying a local instance, always use (local). To force a protocol, add one of the following prefixes:

`np:(local), tcp:(local), lpc:(local)`

You can also connect to a LocalDB database as follows:

`server=(localdb)\\myInstance`

For more information about LocalDB, see [SqlClient Support for LocalDB](/sql/connect/ado-net/sql/sqlclient-support-localdb).

**Data Source** must use the TCP format or the Named Pipes format.

TCP format is as follows:

- tcp:\\\
- tcp:\,\

The TCP format must start with the prefix "tcp:" and is followed by the database instance, as specified by a host name and an instance name. This format is not applicable when connecting to Azure SQL Database. TCP is automatically selected for connections to Azure SQL Database when no protocol is specified.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The instance name is used to resolve to a particular TCP/IP port number on which a database instance is hosted. Alternatively, specifying a TCP/IP port number directly is also allowed. If both instance name and port number are not present, the default database instance is used.

The Named Pipes format is as follows:

- np:\\\\\pipe\\

The Named Pipes format MUST start with the prefix "np:" and is followed by a named pipe name.

The host name MUST be specified in one of the following ways:

- NetBIOSName
- IPv4Address
- IPv6Address

The pipe name is used to identify the database instance to which the .NET application will connect.

If the value of the **Network** key is specified, the prefixes "tcp:" and "np:" should not be specified. **Note:** You can force the use of TCP instead of shared memory, either by prefixing **tcp:** to the server name in the connection string, or by using **localhost**.| |Enclave Attestation Url|N/A|Gets or sets the enclave attestation URL to be used with enclave based Always Encrypted.| -|Encrypt|'false'|When `true`, SQL Server uses SSL encryption for all data sent between the client and server if the server has a certificate installed. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](/sql/connect/ado-net/connection-string-syntax).

Beginning in .NET Framework 4.5, when `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Accepted wildcards used by server certificates for server authentication](https://support.microsoft.com/kb/258858).| +|Encrypt|'false'|When `true`, SQL Server uses SSL encryption for all data sent between the client and server if the server has a certificate installed. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](/sql/connect/ado-net/connection-string-syntax).

When `TrustServerCertificate` is false and `Encrypt` is true, the server name (or IP address) in a SQL Server SSL certificate must exactly match the server name (or IP address) specified in the connection string. Otherwise, the connection attempt will fail. For information about support for certificates whose subject starts with a wildcard character (*), see [Accepted wildcards used by server certificates for server authentication](https://support.microsoft.com/kb/258858).| |Enlist|'true'|`true` indicates that the SQL Server connection pooler automatically enlists the connection in the creation thread's current transaction context.| |Failover Partner|N/A|The name of the failover partner server where database mirroring is configured.

If the value of this key is "", then **Initial Catalog** must be present, and its value must not be "".

The server name can be 128 characters or less.

If you specify a failover partner but the failover partner server is not configured for database mirroring and the primary server (specified with the Server keyword) is not available, then the connection will fail.

If you specify a failover partner and the primary server is not configured for database mirroring, the connection to the primary server (specified with the Server keyword) will succeed if the primary server is available.| |Initial Catalog

-or-

Database|N/A|The name of the database.

The database name can be 128 characters or less.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index f26a7891c8..b671e6ca75 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -177,7 +177,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security @@ -189,7 +189,6 @@ Currently Active Directory Integrated and Active Directory Interactive modes of ## Remarks 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. - ## Examples From 846b6793696498b7790dc9b2b636b45afd7c8c1c Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:13:06 -0700 Subject: [PATCH 10/12] Update SqlUtil.cs --- .../netfx/src/Microsoft/Data/SqlClient/SqlUtil.cs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlUtil.cs b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlUtil.cs index 868f9eaf9a..0e2cc47582 100644 --- a/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlUtil.cs +++ b/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlUtil.cs @@ -530,10 +530,6 @@ static internal Exception ConnectionLockedForBcpEvent() { return ADP.InvalidOperation(StringsHelper.GetString(Strings.SQL_ConnectionLockedForBcpEvent)); } - static internal Exception AsyncConnectionRequired() - { - return ADP.InvalidOperation(StringsHelper.GetString(Strings.SQL_AsyncConnectionRequired)); - } static internal Exception FatalTimeout() { return ADP.InvalidOperation(StringsHelper.GetString(Strings.SQL_FatalTimeout)); From c20c612187afb84ba585c16c645dd067b266d22c Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Mon, 5 Jul 2021 16:42:14 -0700 Subject: [PATCH 11/12] remove asyncprocessing tests --- .../DDBasics/DDAsyncTest/DDAsyncTest.cs | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/src/Microsoft.Data.SqlClient/tests/ManualTests/DDBasics/DDAsyncTest/DDAsyncTest.cs b/src/Microsoft.Data.SqlClient/tests/ManualTests/DDBasics/DDAsyncTest/DDAsyncTest.cs index 2bdde5eda1..bb1fd24a1f 100644 --- a/src/Microsoft.Data.SqlClient/tests/ManualTests/DDBasics/DDAsyncTest/DDAsyncTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/ManualTests/DDBasics/DDAsyncTest/DDAsyncTest.cs @@ -11,24 +11,6 @@ namespace Microsoft.Data.SqlClient.ManualTesting.Tests { public static class DDAsyncTest { - [SkipOnTargetFramework(TargetFrameworkMonikers.NetFramework)] - [ConditionalFact(typeof(DataTestUtility), nameof(DataTestUtility.AreConnStringsSetup))] - public static void OpenConnection_WithAsyncTrue_ThrowsNotSupportedException() - { - //Passes on NetCore - var asyncConnectionString = DataTestUtility.TCPConnectionString + ";async=true"; - Assert.Throws(() => { new SqlConnection(asyncConnectionString); }); - } - - [SkipOnTargetFramework(TargetFrameworkMonikers.Netcoreapp)] - [ConditionalFact(typeof(DataTestUtility), nameof(DataTestUtility.AreConnStringsSetup))] - public static void OpenConnection_WithAsyncTrue() - { - // Passes on NetFx - var asyncConnectionString = DataTestUtility.TCPConnectionString + ";async=true"; - using (SqlConnection connection = new SqlConnection(asyncConnectionString)){} - } - #region <> // TODO Synapse: Remove dependency on Northwind database by creating required table in setup. [ConditionalFact(typeof(DataTestUtility), nameof(DataTestUtility.AreConnStringsSetup), nameof(DataTestUtility.IsNotAzureSynapse))] From f456445d265167038e375a95655237e624f732fb Mon Sep 17 00:00:00 2001 From: Johnny Pham Date: Wed, 7 Jul 2021 09:53:54 -0700 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: David Engel --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 69fc20cb7b..ea70cb5f9d 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -525,7 +525,7 @@ End Module |Address|N/A|Synonym of **Data Source**.| |App|N/A|Synonym of **Application Name**.| |Application Intent

-or-

ApplicationIntent|ReadWrite|Declares the application workload type when connecting to a server. Possible values are `ReadOnly` and `ReadWrite`. For example:

`ApplicationIntent=ReadOnly`

For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](/sql/connect/ado-net/sql/sqlclient-support-high-availability-disaster-recovery).| -|Application Name|N/A|The name of the application, or 'Core Microsoft SqlClient Data Provider' if no application name is provided.

An application name can be 128 characters or less.| +|Application Name|N/A|The name of the application. If no application name is provided, 'Framework Microsoft SqlClient Data Provider' when running on .NET Framework and 'Core Microsoft SqlClient Data Provider' otherwise.

An application name can be 128 characters or less.| |AttachDBFilename

-or-

Extended Properties

-or-

Initial File Name|N/A|The name of the primary database file, including the full path name of an attachable database. AttachDBFilename is only supported for primary data files with an .mdf extension.

If the value of the AttachDBFileName key is specified in the connection string, the database is attached and becomes the default database for the connection.

If this key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection.

If this key is specified together with the AttachDBFileName key, the value of this key will be used as the alias. However, if the name is already used in another attached database, the connection will fail.

The path may be absolute or relative by using the DataDirectory substitution string. If DataDirectory is used, the database file must exist within a subdirectory of the directory pointed to by the substitution string. **Note:** Remote server, HTTP, and UNC path names are not supported.

The database name must be specified with the keyword 'database' (or one of its aliases) as in the following:

"AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase"

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.| |Attestation Protocol|N/A|Gets or sets the value of Attestation Protocol.

Valid values are:
`AAS`
`HGS`| |Authentication|N/A|The authentication method used for [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/#7-connect-to-your-database-by-using-azure-active-directory-identities).

Valid values are:

`Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Password`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, `Sql Password`.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index ab21884cb2..d0cebe8712 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -102,7 +102,7 @@ The default value is `ApplicationIntent.ReadWrite`. Gets or sets the name of the application associated with the connection string. - The name of the application, or "Core Microsoft SqlClient Data Provider" if no name has been supplied. + The name of the application. If no name has been supplied, "Framework Microsoft SqlClient Data Provider" when running on .NET Framework and "Core Microsoft SqlClient Data Provider" otherwise.