forked from dotnet/SqlClient
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathSqlConnectionStringBuilder.xml
1117 lines (852 loc) · 69.9 KB
/
SqlConnectionStringBuilder.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<docs>
<members name="SqlConnectionStringBuilder">
<SqlConnectionStringBuilder>
<summary>Provides a simple way to create and manage the contents of connection strings used by the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> class.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
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 <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> class to build and modify connection strings. The class also makes it easy to manage connection strings stored in an application configuration file.
The <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> 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 <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Remove%2A> method. See the <xref:Microsoft.Data.SqlClient.SqlConnection.ConnectionString%2A> 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:
```vb
Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder
builder("Data Source") = "(local)"
builder("Integrated Security") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"
Console.WriteLine(builder.ConnectionString)
```
```csharp
Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =
new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();
builder["Data Source"] = "(local)";
builder["Integrated Security"] = true;
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";
Console.WriteLine(builder.ConnectionString);
```
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
```
## Examples
The following console application builds connection strings for a SQL Server database. The code uses a <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> class to create the connection string, and then passes the <xref:System.Data.Common.DbConnectionStringBuilder.ConnectionString%2A> property of the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> instance to the constructor of the connection class. The example also parses an existing connection string and demonstrates various ways of manipulating the connection string's contents.
> [!NOTE]
> This example includes a password to demonstrate how <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application.
[!code-csharp[SqlConnectionStringBuilder#1](~/../sqlclient/doc/samples/SqlConnectionStringBuilder.cs#1)]
]]></format>
</remarks>
</SqlConnectionStringBuilder>
<ctor1>
<summary>Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> class.</summary>
</ctor1>
<ctor2>
<summary>Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> class.</summary>
<remarks>To be added.</remarks>
</ctor2>
<ctorConnectionString>
<param name="connectionString">The basis for the object's internal connection information. Parsed into name/value pairs. Invalid key names raise <see cref="T:System.Collections.Generic.KeyNotFoundException" />.</param>
<summary>Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> class. The provided connection string provides the data for the instance's internal connection information.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> 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.
## Examples
The following example supplies a simple SQL Server connection string in the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> object's constructor, and then iterates through all the key/value pairs within the object. Note that the collection provides default values for each item. Also note that the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> class converts synonyms for the well-known keys so that they are consistent with the well-known names.
> [!NOTE]
> This example includes a password to demonstrate how <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application.
[!code-csharp[SqlConnectionStringBuilder3#1](~/../sqlclient/doc/samples/SqlConnectionStringBuilder3.cs#1)]
]]></format>
</remarks>
<exception cref="T:System.Collections.Generic.KeyNotFoundException">Invalid key name within the connection string.</exception>
<exception cref="T:System.FormatException">Invalid value within the connection string (specifically, when a Boolean or numeric value was expected but not supplied).</exception>
<exception cref="T:System.ArgumentException">The supplied <paramref name="connectionString" /> is not valid.</exception>
</ctorConnectionString>
<ApplicationIntent>
<summary>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 <see cref="T:Microsoft.Data.SqlClient.ApplicationIntent" />. 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).</summary>
<value>Returns the current value of the property.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Application Intent" and "ApplicationIntent" keys within the connection string.
The default value is `ApplicationIntent.ReadWrite`.
]]></format>
</remarks>
<related type="Article" href="/sql/connect/ado-net/overview-sqlclient-driver">Overview of the SqlClient driver</related>
</ApplicationIntent>
<ApplicationName>
<summary>Gets or sets the name of the application associated with the connection string.</summary>
<value>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.</value>
<remarks>
<format type="text/markdown"><]
The sample displays the following text in the console window:
```
Original: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security=True
ApplicationName="Core Microsoft SqlClient Data Provider"
Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security=True;Application Name="My Application"
```
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
</ApplicationName>
<AttachDBFilename>
<summary>Gets or sets a string that contains the name of the primary data file. This includes the full path name of an attachable database.</summary>
<value>The value of the <see langword="AttachDBFilename" /> property, or <see langword="String.Empty" /> if no value has been supplied.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
<related type="Article" href="https://msdn.microsoft.com/library/745c5f95-2f02-4674-b378-6d51a7ec2490">Working with Connection Strings</related>
<related type="Article" href="/sql/connect/ado-net/overview-sqlclient-driver">Overview of the SqlClient driver</related>
</AttachDBFilename>
<AttestationProtocol>
<summary>Gets or sets the value of Attestation Protocol.</summary>
<value>The attestation protocol.</value>
</AttestationProtocol>
<Authentication>
<summary>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).</summary>
<value>The authentication method of the connection string.</value>
<remarks>
<format type="text/markdown"><.
]]></format>
</remarks>
</Authentication>
<Clear>
<summary>Clears the contents of the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> instance.</summary>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
</Clear>
<ColumnEncryptionSetting>
<summary>Gets or sets the column encryption settings for the connection string builder.</summary>
<value>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.</value>
</ColumnEncryptionSetting>
<CommandTimeout>
<summary>
The default wait time (in seconds) before terminating the attempt to execute a command and generating an error. The default is 30 seconds.
</summary>
<value>
The time in seconds to wait for the command to execute. The default is 30 seconds.
</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Command Timeout" key within the <xref:Microsoft.Data.SqlClient.SqlConnection> connection string.
Valid values are greater than or equal to 0 and less than or equal to 2147483647.
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value set is less than 0.</exception>
</CommandTimeout>
<ConnectionReset>
<summary>Obsolete. Gets or sets a Boolean value that indicates whether the connection is reset when drawn from the connection pool.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.ConnectionReset" /> property, or true if no value has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Connection Reset" key within the <xref:Microsoft.Data.SqlClient.SqlConnection> connection string, which has been removed from version 3.5 SP1 of the .NET Framework.
]]></format>
</remarks>
</ConnectionReset>
<ConnectRetryCount>
<summary>The number of reconnections attempted after identifying that there was an idle connection failure. This must be an integer between 0 and 255. Default is 1. Set to 0 to disable reconnecting on idle connection failures. An <see cref="T:System.ArgumentException" /> will be thrown if set to a value outside of the allowed range.</summary>
<value>The number of reconnections attempted after identifying that there was an idle connection failure.</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "Connect Retry Count" key within the <xref:Microsoft.Data.SqlClient.SqlConnection> connection string.
]]>
</format>
</remarks>
</ConnectRetryCount>
<ConnectRetryInterval>
<summary>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.</summary>
<value>Amount of time (in seconds) between each reconnection attempt after identifying that there was an idle connection failure.</value>
<exception cref="T:System.ArgumentException">Value is outside of the allowed range.</exception>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "Connect Retry Interval" key within the <xref:Microsoft.Data.SqlClient.SqlConnection> 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.
]]>
</format>
</remarks>
</ConnectRetryInterval>
<ConnectTimeout>
<summary>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.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.ConnectTimeout" /> property, or 15 seconds if no value has been supplied.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
</ConnectTimeout>
<ContainsKey>
<param name="keyword">The key to locate in the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</param>
<summary>Determines whether the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> contains a specific key.</summary>
<returns>true if the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> contains an element that has the specified key; otherwise, false.</returns>
<remarks>
<format type="text/markdown"><]
The example displays the following output in the console window:
```
Connection string = Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security=True
True
True
True
False
```
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="keyword" /> is null (<see langword="Nothing" /> in Visual Basic)</exception>
</ContainsKey>
<ContextConnection>
<summary>Obsolete. Gets or sets a value that indicates whether a client/server or in-process connection to SQL Server should be made.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.ContextConnection" /> property, or <see langword="False" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Context Connection" key within the connection string.
> [!NOTE]
> The <xref:Microsoft.Data.SqlClient.SqlConnection.DataSource%2A> property returns `null` if the connection string for the <xref:Microsoft.Data.SqlClient.SqlConnection> is "context connection=true".
]]></format>
</remarks>
</ContextConnection>
<CurrentLanguage>
<summary>Gets or sets the language used for database server warning or error messages..</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.CurrentLanguage" /> property, or <see langword="String.Empty" /> if no value has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Current Language" and "language" keys within the connection string.
The language name can be 128 characters or less.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
</CurrentLanguage>
<DataSource>
<summary>Gets or sets the name or network address of the instance of SQL Server to connect to.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.DataSource" /> property, or <see langword="String.Empty" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><.
**Data Source** must use the TCP format or the Named Pipes format. TCP format is as follows:
- tcp:\<host name>\\<instance name\>
- tcp:\<host name>,\<TCP/IP port number>
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:\\\\<host name\>\pipe\\<pipe name\>
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**.
## Examples
The following example demonstrates that the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> class converts synonyms for the "Data Source" connection string key into the well-known key:
[!code-csharp[SqlConnectionStringBuilder_DataSource#1](~/../sqlclient/doc/samples/SqlConnectionStringBuilder_DataSource.cs#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
</DataSource>
<EnclaveAttestationUrl>
<summary>Gets or sets the enclave attestation URL to be used with enclave based Always Encrypted.</summary>
<value>The enclave attestation URL.</value>
</EnclaveAttestationUrl>
<Encrypt>
<summary>Gets or sets a <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> value since version 5.0 or a <see cref="T:System.Boolean" /> value for the earlier versions that indicates whether TLS encryption is required for all data sent between the client and server.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Encrypt" /> property.</value>
<remarks>
<format type="text/markdown"><.
> [!NOTE]
> Starting from **version 4.0**, the default value of the property `Encrypt` is set to `true` while it is `false` for earlier versions.
> [!NOTE]
> Starting from **version 5.0**, the data type is updated to <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption>, and the default value of the `Encrypt` property is set to <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory%2A>.
]]></format>
</remarks>
<related type="Article" href="https://msdn.microsoft.com/library/745c5f95-2f02-4674-b378-6d51a7ec2490">Working with Connection Strings</related>
<related type="Article" href="/sql/connect/ado-net/overview-sqlclient-driver">Overview of the SqlClient driver</related>
</Encrypt>
<Enlist>
<summary>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.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Enlist" /> property, or <see langword="true" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Enlist" key within the connection string.
]]></format>
</remarks>
</Enlist>
<FailoverPartner>
<summary>Gets or sets the name or address of the partner server to connect to if the primary server is down.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.FailoverPartner" /> property, or <see langword="String.Empty" /> if none has been supplied.</value>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
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.
]]></format>
</remarks>
</FailoverPartner>
<FailoverPartnerSPN>
<summary>Gets or sets the service principal name (SPN) of the failover partner for the connection.</summary>
<value>
The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.FailoverPartnerSPN" /> property, or <see langword="String.Empty" /> if none has been supplied.
</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "FailoverPartnerSPN" and "Failover Partner SPN" keys within the connection string.
> [!NOTE]
> This property only applies when using Integrated Security mode, otherwise it is ignored.
]]>
</format>
</remarks>
</FailoverPartnerSPN>
<HostNameInCertificate>
<summary>Gets or sets the host name to use when validating the server certificate for the connection. When not specified, the server name from the `Data Source` is used for certificate validation. (Only available in v5.0+)</summary>
<value>
The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.HostNameInCertificate" /> property, or <see langword="String.Empty" /> if none has been supplied.
</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "HostNameInCertificiate" and "Host Name in Certificiate" keys within the connection string.
> [!NOTE]
> This property only applies when using `Encrypt` in <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory%2A> or <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Strict%2A> mode, otherwise it is ignored.
]]>
</format>
</remarks>
</HostNameInCertificate>
<GetProperties>
<param name="propertyDescriptors">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
</GetProperties>
<InitialCatalog>
<summary>Gets or sets the name of the database associated with the connection.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.InitialCatalog" /> property, or <see langword="String.Empty" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
</InitialCatalog>
<IntegratedSecurity>
<summary>Gets or sets a Boolean value that indicates whether User ID and Password are specified in the connection (when <see langword="false" />) or whether the current Windows account credentials are used for authentication (when <see langword="true" />).</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.IntegratedSecurity" /> property, or <see langword="false" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
<xref:Microsoft.Data.SqlClient.SqlCredential> is a more secure way to specify credentials for a connection that uses SQL Server Authentication (`Integrated Security=false`).
## Examples
The following example converts an existing connection string from using SQL Server Authentication to using integrated security. The example does its work by removing the user name and password from the connection string and then setting the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.IntegratedSecurity%2A> property of the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> object.
> [!NOTE]
> This example includes a password to demonstrate how <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application.
[!code-csharp[SqlConnectionStringBuilder_IntegratedSecurity#1](~/../sqlclient/doc/samples/SqlConnectionStringBuilder_IntegratedSecurity.cs#1)]
]]></format>
</remarks>
</IntegratedSecurity>
<IPAddressPreference>
<summary>Gets or sets the IP address family preference when establishing TCP connections.</summary>
<returns>Returns the IP address preference.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If `Transparent Network IP Resolution` (in .NET Framework) or `Multi Subnet Failover` is set to true, this setting has no effect.
]]></format>
</remarks>
</IPAddressPreference>
<IsFixedSize>
<summary>Gets a value that indicates whether the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> has a fixed size.</summary>
<value>
<see langword="true" /> in every case, because the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> supplies a fixed-size collection of key/value pairs.</value>
<remarks>To be added.</remarks>
<related type="Article" href="https://msdn.microsoft.com/library/745c5f95-2f02-4674-b378-6d51a7ec2490">Working with Connection Strings</related>
<related type="Article" href="/sql/connect/ado-net/overview-sqlclient-driver">Overview of the SqlClient driver</related>
</IsFixedSize>
<Item>
<param name="keyword">The key of the item to get or set.</param>
<summary>Gets or sets the value associated with the specified key. In C#, this property is the indexer.</summary>
<value>The value associated with the specified key.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="keyword" /> is a null reference (<see langword="Nothing" /> in Visual Basic).</exception>
<exception cref="T:System.Collections.Generic.KeyNotFoundException">Tried to add a key that does not exist within the available keys.</exception>
<exception cref="T:System.FormatException">Invalid value within the connection string (specifically, a Boolean or numeric value was expected but not supplied).</exception>
</Item>
<Keys>
<summary>Gets an <see cref="T:System.Collections.ICollection" /> that contains the keys in the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</summary>
<value>An <see cref="T:System.Collections.ICollection" /> that contains the keys in the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
<altmember cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Values" />
<altmember cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Item(System.String)" />
</Keys>
<LoadBalanceTimeout>
<summary>Gets or sets the minimum time, in seconds, for the connection to live in the connection pool before being destroyed.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.LoadBalanceTimeout" /> property, or 0 if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
]]></format>
</remarks>
</LoadBalanceTimeout>
<MaxPoolSize>
<summary>Gets or sets the maximum number of connections allowed in the connection pool for this specific connection string.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.MaxPoolSize" /> property, or 100 if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Max Pool Size" key within the connection string.
]]></format>
</remarks>
</MaxPoolSize>
<MinPoolSize>
<summary>Gets or sets the minimum number of connections allowed in the connection pool for this specific connection string.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.MinPoolSize" /> property, or 0 if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Min Pool Size" key within the connection string.
]]></format>
</remarks>
</MinPoolSize>
<MultipleActiveResultSets>
<summary>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)](https://msdn.microsoft.com//library/cfa084cz.aspx).</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.MultipleActiveResultSets" /> property, or <see langword="false" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
</MultipleActiveResultSets>
<MultiSubnetFailover>
<summary>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).</summary>
<value>Returns <see cref="T:System.Boolean" /> indicating the current value of the property.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Always specify `multiSubnetFailover=True` when connecting to the availability group listener of a SQL Server 2012 (or later) availability group or a SQL Server 2012 (or later) Failover Cluster Instance.
]]></format>
</remarks>
</MultiSubnetFailover>
<NetworkLibrary>
<summary>Gets or sets a string that contains the name of the network library used to establish a connection to the SQL Server.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.NetworkLibrary" /> property, or <see langword="String.Empty" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
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.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
</NetworkLibrary>
<PacketSize>
<summary>Gets or sets the size in bytes of the network packets used to communicate with an instance of SQL Server.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.PacketSize" /> property, or 8000 if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
]]></format>
</remarks>
</PacketSize>
<Password>
<summary>Gets or sets the password for the SQL Server account.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Password" /> property, or <see langword="String.Empty" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The password was incorrectly set to null. See code sample below.</exception>
</Password>
<PersistSecurityInfo>
<summary>Gets or sets a Boolean value indicating if security-sensitive information, such as the password or access token, should be returned as part of the connection string on a connection created with this <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> after that connection has ever been in an open state. This property should only be set to <see langword="true" /> if your application has a specific need to read the password out of an already-opened database connection. The default value of <see langword="false" /> is the more secure setting; using <see langword="true" /> for this property opens your application to security risks such as accidentally logging or tracing the database password.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.PersistSecurityInfo" /> property, or <see langword="false" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
]]></format>
</remarks>
</PersistSecurityInfo>
<PoolBlockingPeriod>
<summary>The blocking period behavior for a connection pool.</summary>
<value>The available blocking period settings.</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "Pool Blocking Period" key within the connection string.
When connection pooling is enabled and a timeout error or other login error occurs, an exception will be thrown and subsequent connection attempts will fail for the next five seconds, the "blocking period". If the application attempts to connect within the blocking period, the first exception will be thrown again. Subsequent failures after a blocking period ends will result in a new blocking period that is twice as long as the previous blocking period, up to a maximum of one minute.
Attempting to connect to Azure SQL databases can fail with transient errors which are typically recovered within a few seconds. However, with the connection pool blocking period behavior, you may not be able to reach your database for extensive periods even though the database is available. This is especially problematic for apps that need to render fast. The **PoolBlockingPeriod** enables you to select the blocking period best suited for your app. See the <xref:Microsoft.Data.SqlClient.PoolBlockingPeriod> enumeration for available settings.
]]></format>
</remarks>
</PoolBlockingPeriod>
<Pooling>
<summary>Gets or sets a Boolean value that indicates whether the connection will be pooled or explicitly opened every time that the connection is requested.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Pooling" /> property, or <see langword="true" /> if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
]]></format>
</remarks>
</Pooling>
<Remove>
<param name="keyword">The key of the key/value pair to be removed from the connection string in this <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</param>
<summary>Removes the entry with the specified key from the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> instance.</summary>
<returns>
<see langword="true" /> if the key existed within the connection string and was removed; <see langword="false" /> if the key did not exist.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
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 <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> instance. Because the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> maintains a fixed-size collection of key/value pairs, calling the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Remove%2A> method simply resets the value of the key/value pair back to its default value.
Because the collection of keys supported by the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> 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 <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> is first initialized, or after the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Remove%2A> method has been called.
|Key|Default value|
|---------|-------------------|
|Application Name|"Framework Microsoft SqlClient Data Provider" when running on .NET Framework. "Core Microsoft SqlClient Data Provider" otherwise.|
|AttachDBFilename|Empty string|
|Connection Timeout|15|
|Context Connection(Obsolete)|False|
|Current Language|Empty string|
|Data Source|Empty string|
|Encrypt|False in versions prior to 4.0, True in versions 4.0 and up|
|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|
## Examples
The following example converts an existing connection string from using Windows Authentication to using integrated security. The example works by removing the user name and password from the connection string, and then setting the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.IntegratedSecurity%2A> property of the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> object.
> [!NOTE]
> This example includes a password to demonstrate how <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application.
[!code-csharp[SqlConnectionStringBuilder_Remove#1](~/../sqlclient/doc/samples/SqlConnectionStringBuilder_Remove.cs#1)]
The example displays the following text in the console window:
```
Original: Data Source=(local);Initial Catalog=AdventureWorks;User ID=ab;Password= a1Pass@@11
Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security=True
Database = AdventureWorks
```
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="keyword" /> is null (<see langword="Nothing" /> in Visual Basic)</exception>
</Remove>
<Replication>
<summary>Gets or sets a Boolean value that indicates whether replication is supported using the connection.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Replication" /> property, or false if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property corresponds to the "Replication" key within the connection string.
]]></format>
</remarks>
</Replication>
<ServerCertificate>
<summary>Gets or sets the path to a certificate file to match against the SQL Server TLS/SSL certificate for the connection. The accepted certificate formats are PEM, DER, and CER. If specified, the SQL Server certificate is checked by verifying if the `ServerCertificate` provided is an exact match. (Only available in v5.1+)</summary>
<value>
The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.ServerCertificate" /> property, or <see langword="String.Empty" /> if none has been supplied.
</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "ServerCertificate" and "Server Certificate" keys within the connection string.
> [!NOTE]
> This property only applies when using `Encrypt` in <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory%2A> or <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Strict%2A> mode, otherwise it is ignored.
]]>
</format>
</remarks>
</ServerCertificate>
<ServerSPN>
<summary>Gets or sets the service principal name (SPN) of the data source.</summary>
<value>
The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.ServerSPN" /> property, or <see langword="String.Empty" /> if none has been supplied.
</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
This property corresponds to the "ServerSPN" and "Server SPN" keys within the connection string.
> [!NOTE]
> This property only applies when using Integrated Security mode, otherwise it is ignored.
]]>
</format>
</remarks>
</ServerSPN>
<ShouldSerialize>
<param name="keyword">The key to locate in the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</param>
<summary>Indicates whether the specified key exists in this <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> instance.</summary>
<returns>
<see langword="true" /> if the <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" /> contains an entry with the specified key; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method behaves identically to the <xref:System.Data.Common.DbConnectionStringBuilder.ContainsKey%2A> method.
]]></format>
</remarks>
</ShouldSerialize>
<TransactionBinding>
<summary>Gets or sets a string value that indicates how the connection maintains its association with an enlisted <see langword="System.Transactions" /> transaction.</summary>
<value>The value of the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.TransactionBinding" /> property, or `Implicit Unbind` if none has been supplied.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The Transaction Binding keywords in a <xref:Microsoft.Data.SqlClient.SqlConnection.ConnectionString%2A> control how a <xref:Microsoft.Data.SqlClient.SqlConnection> binds to an enlisted <xref:System.Transactions.Transaction>.
The following table shows the possible values for the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.TransactionBinding%2A> property:
|Value|Description|
|-----------|-----------------|
|Implicit Unbind|The default. Causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The <xref:System.Transactions.Transaction.Current%2A> property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.|
|Explicit Unbind|Causes the connection to remain attached to the transaction until the connection is closed or until <xref:Microsoft.Data.SqlClient.SqlConnection.EnlistTransaction%2A> is called with a `null` (`Nothing` in Visual Basic) value. An <xref:System.InvalidOperationException> is thrown if <xref:System.Transactions.Transaction.Current%2A> is not the enlisted transaction or if the enlisted transaction is not active. This behavior enforces the strict scoping rules required for <xref:System.Transactions.TransactionScope> support.|
]]></format>
</remarks>
</TransactionBinding>
<TransparentNetworkIPResolution>
<summary>When the value of this key is set to <see langword="true" />, the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.</summary>
<value>A boolean value.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If the `Multi Subnet Failover` key is set to `true`, `Transparent Network IP Resolution` is ignored.
If the `Failover Partner` key is set, `Transparent Network IP Resolution` is ignored.
The value of this key must be `true`, `false`, `yes`, or `no`.
A value of `yes` is treated the same as a value of `true`.
A value of `no` is treated the same as a value of `false`.
This key defaults to `false` when:
- Connecting to Azure SQL Database where the data source ends with:
- .database.chinacloudapi.cn
- .database.usgovcloudapi.net
- .database.cloudapi.de
- .database.windows.net
- `Authentication` is 'Active Directory Password' or 'Active Directory Integrated'
Otherwise it defaults to `true`.
]]></format>
</remarks>
</TransparentNetworkIPResolution>
<TrustServerCertificate>
<summary>Gets or sets a value that indicates whether the channel will be encrypted while bypassing walking the certificate chain to validate trust.</summary>
<value>A boolean. The default is `false`.</value>
<remarks>
<format type="text/markdown">< and [Using Encryption Without Validation](/sql/relational-databases/native-client/features/using-encryption-without-validation).
]]></format>
</remarks>
</TrustServerCertificate>
<TryGetValue>
<param name="keyword">The key of the item to retrieve.</param>
<param name="value">The value corresponding to <paramref name="keyword" />.</param>
<summary>Retrieves a value corresponding to the supplied key from this <see cref="T:Microsoft.Data.SqlClient.SqlConnectionStringBuilder" />.</summary>
<returns>
<see langword="true" /> if <paramref name="keyword" /> was found within the connection string; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.TryGetValue%2A> method lets developers safely retrieve a value from a <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder> without needing to verify that the supplied key name is a valid key name. Because **TryGetValue** does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling **TryGetValue** with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter.
## Examples
The following example demonstrates the behavior of the **TryGetValue** method.