Skip to content

Commit 276434b

Browse files
v-aljev-alje
committed
Merge branch 'master' of https://github.com/MicrosoftDocs/sql-docs-pr into release-qds-hints
2 parents 49d174c + 328a7e7 commit 276434b

18 files changed

Lines changed: 211 additions & 38 deletions

‎docs/connect/ado-net/appcontext-switches.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCal
8282

8383
## Disable blocking behavior of ReadAsync
8484

85-
[!INCLUDE [appliesto-netfx-xxxx-xxxx-md](../../includes/appliesto-netfx-xxxx-xxxx-md.md)]
85+
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
8686

8787
By default, ReadAsync runs synchronously and blocks the calling thread on .NET Framework. To disable this blocking behavior, you can set the AppContext switch **Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking** to `false` at application startup:
8888

@@ -99,11 +99,20 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", fa
9999
By default, configurable retry logic is disabled. To enable this feature, set the AppContext switch **Switch.Microsoft.Data.SqlClient.EnableRetryLogic** to `true` at application startup. This switch is required, even if a retry provider is assigned to a connection or command.
100100

101101
```csharp
102-
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", false);
102+
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);
103103
```
104104

105105
* For information on how to enable the switch by using a configuration file see [Enable safety switch](configurable-retry-logic-config-file-sqlclient.md#enable-safety-switch).
106106

107+
## Enabling row version null behavior
108+
109+
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
110+
Starting in version 3.0, `SqlDataReader` returns a `DBNull` value instead of an empty `byte[]`. To enable the legacy behavior of returning an empty `byte[]`, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior** on application startup.
111+
112+
```csharp
113+
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);
114+
```
115+
107116
## See also
108117

109118
[AppContext Class](/dotnet/api/system.appcontext?view=netcore-3.1&preserve-view=true)

‎docs/connect/ado-net/configurable-retry-logic-config-file-sqlclient.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ ms.reviewer: v-deshtehari
1212
---
1313
# Configurable retry logic configuration file with SqlClient
1414

15-
[!INCLUDE[appliesto-netfx-netcore-xxxx-md](../../includes/appliesto-netfx-netcore-xxxx-md.md)]
15+
[!INCLUDE[appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
1616

1717
[!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
1818

‎docs/connect/ado-net/diagnostic-counters.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: "Diagnostic counters in SqlClient"
3+
description: Use Microsoft SqlClient Data Provider for SQL Server diagnostic counters to monitor your application status and its connection resources.
4+
ms.date: "05/31/2021"
5+
dev_langs:
6+
- "csharp"
7+
ms.prod: sql
8+
ms.prod_service: connectivity
9+
ms.technology: connectivity
10+
ms.topic: conceptual
11+
author: David-Engel
12+
ms.author: v-daenge
13+
ms.reviewer: v-deshtehari
14+
---
15+
# Diagnostic counters in SqlClient
16+
17+
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
18+
19+
[!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
20+
21+
You can use <xref:Microsoft.Data.SqlClient> diagnostic counters in multiple target frameworks to monitor the status of your application and the connection resources that it uses. Use `performance counters` in .NET Framework, and `event counters` in .NET Core and .NET Standard.
22+
23+
> [!NOTE]
24+
> When using Windows Authentication (integrated security), you must monitor either the pair `number-of-active-connection-pool-groups` and `number-of-active-connection-pools` event counters or the `NumberOfActiveConnectionPoolGroups` and `NumberOfActiveConnectionPools` performance counters. The reason is that connection pool groups map to unique connection strings. When integrated security is used, connection pools map to connection strings and additionally create separate pools for individual Windows identities. For example, if Fred and Julie, each within the same AppDomain, both use the connection string `"Data Source=MySqlServer;Integrated Security=true"`, a connection pool group is created for the connection string, and two additional pools are created, one for Fred and one for Julie. If John and Martha use a connection string with an identical SQL Server login, `"Data Source=MySqlServer;User Id=<myUserID>;Password=<myPassword>"`, then only a single pool is created for the **<myUserID>** identity.
25+
26+
## In this section
27+
28+
[Performance counters in SqlClient](performance-counters.md)
29+
Use Microsoft SqlClient Data Provider for SQL Server performance counters to monitor your application status and its connection resources by using Windows Performance Monitor or programmatically in `.NET Framework`.
30+
31+
[Event counters in SqlClient](event-counters.md)
32+
Use Microsoft SqlClient Data Provider for SQL Server event counters to monitor your application status and its connection resources in `.NET Core` and `.NET Standard`.
33+
34+
## See also
35+
36+
- [Retrieving and modifying data in ADO.NET](retrieving-modifying-data.md)
37+
- [Microsoft ADO.NET for SQL Server](microsoft-ado-net-sql-server.md)

‎docs/connect/ado-net/event-counters.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: "Event counters in SqlClient"
3+
description: Use Microsoft SqlClient Data Provider for SQL Server event counters to monitor your application status and its connection resources in .NET Core and .NET Standard.
4+
ms.date: "05/31/2021"
5+
dev_langs:
6+
- "csharp"
7+
ms.prod: sql
8+
ms.prod_service: connectivity
9+
ms.technology: connectivity
10+
ms.topic: conceptual
11+
author: David-Engel
12+
ms.author: v-daenge
13+
ms.reviewer: v-deshtehari
14+
---
15+
# Event counters in SqlClient
16+
17+
[!INCLUDE[appliesto-xxxx-netcore-netst-md](../../includes/appliesto-xxxx-netcore-netst-md.md)]
18+
19+
[!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
20+
21+
> [!IMPORTANT]
22+
> Event counters are available when targeting **.NET Core 3.1** and higher or **.NET Standard 2.1** and higher. This feature is available starting with `Microsoft.Data.SqlClient` **version 3.0.0**.
23+
24+
You can use <xref:Microsoft.Data.SqlClient> event counters to monitor the status of your application and the connection resources that it uses. Event counters can be monitored by `.NET CLI global tools` and `perfView` or can be accessed programmatically using the <xref:System.Diagnostics.Tracing.EventListener> class in the <xref:System.Diagnostics.Tracing> namespace.
25+
26+
## Available event counters
27+
28+
Currently there are 16 different event counters available for <xref:Microsoft.Data.SqlClient> as described in the following table:
29+
30+
|Name|Display name|Description|
31+
|-------------------------|-----------------|-----------------|
32+
|**active-hard-connections**|Actual active connections currently made to servers|The number of connections that are currently open to database servers.|
33+
|**hard-connects**|Actual connection rate to servers|The number of connections per second that are being opened to database servers.|
34+
|**hard-disconnects**|Actual disconnection rate from servers|The number of disconnects per second that are being made to database servers.|
35+
|**active-soft-connects**|Active connections retrieved from the connection pool|The number of already-open connections being consumed from the connection pool.|
36+
|**soft-connects**|Rate of connections retrieved from the connection pool|The number of connections per second that are being consumed from the connection pool.|
37+
|**soft-disconnects**|Rate of connections returned to the connection pool|The number of connections per second that are being returned to the connection pool.|
38+
|**number-of-non-pooled-connections**|Number of connections not using connection pooling|The number of active connections that aren't pooled.|
39+
|**number-of-pooled-connections**|Number of connections managed by the connection pool|The number of active connections that are being managed by the connection pooling infrastructure.|
40+
|**number-of-active-connection-pool-groups**|Number of active unique connection strings|The number of unique connection pool groups that are active. This counter is controlled by the number of unique connection strings that are found in the AppDomain.|
41+
|**number-of-inactive-connection-pool-groups**|Number of unique connection strings waiting for pruning|The number of unique connection pool groups that are marked for pruning. This counter is controlled by the number of unique connection strings that are found in the AppDomain.|
42+
|**number-of-active-connection-pools**|Number of active connection pools|The total number of connection pools.|
43+
|**number-of-inactive-connection-pools**|Number of inactive connection pools|The number of inactive connection pools that haven't had any recent activity and are waiting to be disposed.|
44+
|**number-of-active-connections**|Number of active connections|The number of active connections that are currently in use.|
45+
|**number-of-free-connections**|Number of ready connections in the connection pool|The number of open connections available for use in the connection pools.|
46+
|**number-of-stasis-connections**|Number of connections currently waiting to be ready|The number of connections currently awaiting completion of an action and which are unavailable for use by the application.|
47+
|**number-of-reclaimed-connections**|Number of reclaimed connections from GC|The number of connections that have been reclaimed through garbage collection where `Close` or `Dispose` wasn't called by the application. **Note** Not explicitly closing or disposing connections hurts performance.|
48+
49+
## Retrieve event counter values
50+
51+
There are two primary ways of consuming EventCounters, either in-proc, or out-of-proc. For more information, see [Consume EventCounters](/dotnet/core/diagnostics/event-counters).
52+
53+
### Consume out-of-proc
54+
55+
In Windows, you can use [PerfView](https://github.com/microsoft/perfview) and [Xperf](/windows-hardware/test/wpt/) to collect event counters data. For more information, see [Enable event tracing in SqlClient](enable-eventsource-tracing.md).
56+
You can use [dotnet-counters](/dotnet/core/diagnostics/dotnet-counters) and [dotnet-trace](/dotnet/core/diagnostics/dotnet-trace), which are cross platform **.NET** tools to monitor and collect event counters data.
57+
58+
#### Out-of-proc example
59+
60+
The following command runs and collects SqlClient event counters values once every second. Replacing `EventCounterIntervalSec=1` with a higher value allows collection of a smaller trace with less granularity in the counter data.
61+
62+
```Console
63+
PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 run "<application-Path>"
64+
```
65+
66+
The following command collects SqlClient event counters values once every second.
67+
68+
```Console
69+
dotnet-trace collect --process-id <pid> --providers Microsoft.Data.SqlClient.EventSource:0:1:EventCounterIntervalSec=1
70+
```
71+
72+
The following command monitors SqlClient event counters values once every three seconds.
73+
74+
```Console
75+
dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p <process-id> --refresh-interval 3
76+
```
77+
78+
The following command monitors selected SqlClient event counters values once every second.
79+
80+
```Console
81+
dotnet-counters monitor Microsoft.Data.SqlClient.EventSource[hard-connects,hard-disconnects] -p <process-id>
82+
```
83+
84+
### Consume in-proc
85+
86+
You can consume the counter values via the [EventListener](/dotnet/api/system.diagnostics.tracing.eventlistener) API. An `EventListener` is an in-proc way of consuming any event written by instances of an [EventSource](/dotnet/api/system.diagnostics.tracing.eventsource) in your application. For more information, see [EventListener](/dotnet/api/system.diagnostics.tracing.eventlistener).
87+
88+
#### In-proc example
89+
90+
The following sample code captures `Microsoft.Data.SqlClient.EventSource` events using `EventCounterIntervalSec=1`. It writes the counter name and its `Mean` value on each event counter update.
91+
92+
> [!NOTE]
93+
> It's required to specify the `EventCounterIntervalSec` property value when enabling this event.
94+
95+
[!code-csharp[SqlClientDiagnosticCounter#1](~/../sqlclient/doc/samples/SqlClientDiagnosticCounter.cs#1)]
96+
97+
``` Output
98+
Actual active connections currently made to servers 0
99+
Active connections retrieved from the connection pool 26
100+
Number of connections not using connection pooling 0
101+
Number of connections managed by the connection pool 26
102+
Number of active unique connection strings 1
103+
Number of unique connection strings waiting for pruning 0
104+
Number of active connection pools 1
105+
Number of inactive connection pools 0
106+
Number of active connections 26
107+
Number of ready connections in the connection pool 0
108+
Number of connections currently waiting to be ready 0
109+
...
110+
```
111+
112+
## See also
113+
114+
- [Performance counters in SqlClient](performance-counters.md)
115+
- [dotnet-counters](/dotnet/core/diagnostics/dotnet-counters)
116+
- [dotnet-trace](/dotnet/core/diagnostics/dotnet-trace)
117+
- [Enable event tracing in SqlClient](enable-eventsource-tracing.md)
118+
- [Microsoft ADO.NET for SQL Server](microsoft-ado-net-sql-server.md)

‎docs/connect/ado-net/execute-command.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,7 @@ The following code example demonstrates how to create a <xref:Microsoft.Data.Sql
4747

4848
### Troubleshooting commands
4949

50-
[!INCLUDE[appliesto-netfx-xxxx-xxxx-md](../../includes/appliesto-netfx-xxxx-xxxx-md.md)]
51-
52-
The Microsoft SqlClient Data Provider for SQL Server adds **performance counters** to enable you to detect intermittent problems related to failed command executions. For more information, see [Performance counters in SqlClient](performance-counters.md).
50+
The Microsoft SqlClient Data Provider for SQL Server adds **diagnostic counters** to enable you to detect intermittent problems related to failed command executions. For more information, see [Diagnostic counters in SqlClient](diagnostic-counters.md).
5351

5452
## See also
5553

‎docs/connect/ado-net/performance-counters.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Performance counters in SqlClient"
3-
description: Use Microsoft SqlClient Data Provider for SQL Server performance counters to monitor your application status and its connection resources by using Windows Performance Monitor or programmatically.
3+
description: Use Microsoft SqlClient Data Provider for SQL Server performance counters to monitor your application status and its connection resources by using Windows Performance Monitor or programmatically in .NET Framework.
44
ms.date: "12/04/2020"
55
dev_langs:
66
- "csharp"
@@ -42,10 +42,6 @@ Currently there are 14 different performance counters available for <xref:Micros
4242
|`SoftConnectsPerSecond`|The number of active connections being pulled from the connection pool. **Note:** This performance counter is not enabled by default. To enable this performance counter, see [Activate off-by-default counters](#ActivatingOffByDefault).|
4343
|`SoftDisconnectsPerSecond`|The number of active connections that are being returned to the connection pool. **Note:** This performance counter is not enabled by default. To enable this performance counter, see [Activate off-by-default counters](#ActivatingOffByDefault).|
4444

45-
### Connection pool groups and connection pools
46-
47-
When using Windows Authentication (integrated security), you must monitor both the `NumberOfActiveConnectionPoolGroups` and `NumberOfActiveConnectionPools` performance counters. The reason is that connection pool groups map to unique connection strings. When integrated security is used, connection pools map to connection strings and additionally create separate pools for individual Windows identities. For example, if Fred and Julie, each within the same AppDomain, both use the connection string `"Data Source=MySqlServer;Integrated Security=true"`, a connection pool group is created for the connection string, and two additional pools are created, one for Fred and one for Julie. If John and Martha use a connection string with an identical SQL Server login, `"Data Source=MySqlServer;User Id=<myUserID>;Password=<myPassword>"`, then only a single pool is created for the **<myUserID>** identity.
48-
4945
<a name="ActivatingOffByDefault"></a>
5046

5147
### Activate off-by-default counters
@@ -74,6 +70,7 @@ The following console application shows how to retrieve performance counter valu
7470

7571
## See also
7672

73+
- [Event counters in SqlClient](event-counters.md)
7774
- [Connecting to a data source](connecting-to-data-source.md)
7875
- [Runtime profiling](/dotnet/framework/debug-trace-profile/runtime-profiling)
7976
- [Introduction to monitoring performance thresholds](/previous-versions/visualstudio/visual-studio-2008/bd20x32d(v=vs.90))

‎docs/connect/ado-net/retrieving-modifying-data.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ Describes how to use stored procedure input parameters and output parameters to
6060
[Data tracing in SqlClient](data-tracing.md)
6161
Describes how Microsoft SqlClient Data Provider for SQL Server provides built-in data tracing functionality.
6262

63-
[Performance counters in SqlClient](performance-counters.md)
64-
Describes performance counters available for Microsoft SqlClient Data Provider for SQL Server.
63+
[Diagnostic counters in SqlClient](diagnostic-counters.md)
64+
Describes diagnostic counters and available for Microsoft SqlClient Data Provider for SQL Server.
6565

6666
[Asynchronous programming](asynchronous-programming.md)
6767
Describes Microsoft SqlClient Data Provider for SQL Server support for asynchronous programming.

‎docs/connect/ado-net/sql-server-connection-pooling.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,5 @@ We recommend that you take advantage of security mechanisms that you can use ins
125125

126126
- [Connection pooling](connection-pooling.md)
127127
- [SQL Server and ADO.NET](./sql/index.md)
128-
- [performance counters in SqlClient](performance-counters.md)
128+
- [Diagnostic counters in SqlClient](diagnostic-counters.md)
129129
- [Microsoft ADO.NET for SQL Server](microsoft-ado-net-sql-server.md)

‎docs/connect/toc.yml‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,13 @@
157157
items:
158158
- name: Obtain a SqlClientFactory
159159
href: ../connect/ado-net/obtain-sqlclientfactory.md
160+
- name: Diagnostic counters
161+
href: ../connect/ado-net/diagnostic-counters.md
162+
items:
163+
- name: Event counters
164+
href: ../connect/ado-net/event-counters.md
165+
- name: Performance counters
166+
href: ../connect/ado-net/performance-counters.md
160167
- name: Retrieve identity or autonumber values
161168
href: ../connect/ado-net/retrieve-identity-or-autonumber-values.md
162169
- name: Retrieve binary data
@@ -165,8 +172,6 @@
165172
href: ../connect/ado-net/modify-data-with-stored-procedures.md
166173
- name: Data tracing in SqlClient
167174
href: ../connect/ado-net/data-tracing.md
168-
- name: Performance counters in SqlClient
169-
href: ../connect/ado-net/performance-counters.md
170175
- name: Asynchronous programming
171176
href: ../connect/ado-net/asynchronous-programming.md
172177
- name: SqlClient streaming support

‎docs/includes/synapse-analytics-dedicated-unsupported-syntax.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
This syntax is not supported by dedicated SQL pool in Azure Synapse Analytics.

0 commit comments

Comments
 (0)