Skip to content

Commit c60b61f

Browse files
GitHubber17GitHubber17
authored
Merge pull request #17941 from karinazhou/data-classification-sni-trace
Update data classification and sni tracing
2 parents 0d8941d + 3803344 commit c60b61f

5 files changed

Lines changed: 179 additions & 16 deletions

File tree

‎docs/connect/ado-net/enable-eventsource-tracing.md‎

Lines changed: 93 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "Enabling event tracing in SqlClient"
2+
title: "Enable event tracing in SqlClient"
33
description: "Describes how to enable event tracing in SqlClient by implementing an event listener and how to access the event data."
4-
ms.date: "06/15/2020"
4+
ms.date: "11/23/2020"
55
dev_langs:
66
- "csharp"
77
ms.prod: sql
@@ -12,7 +12,7 @@ author: johnnypham
1212
ms.author: v-jopha
1313
ms.reviewer:
1414
---
15-
# Enabling event tracing in SqlClient
15+
# Enable event tracing in SqlClient
1616

1717
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
1818

@@ -48,10 +48,99 @@ The following example enables event tracing for a data operation on the **Advent
4848

4949
[!code-csharp [SqlClientEventSource#1](~/../sqlclient/doc/samples/SqlClientEventSource.cs#1)]
5050

51+
## Event tracing support in Native SNI
52+
53+
**Microsoft.Data.SqlClient** v2.1.0 extends event tracing support in **Microsoft.Data.SqlClient.SNI** and **Microsoft.Data.SqlClient.SNI.runtime**. By sending an EventCommand to `SqlClientEventSource`, events in native SNI.dll can be collected using [Xperf](https://docs.microsoft.com/windows-hardware/test/wpt/) and [PerfView](https://github.com/microsoft/perfview) tools. The valid EventCommand values are listed as below:
54+
55+
```cs
56+
// Enables trace events:
57+
EventSource.SendCommand(eventSource, (EventCommand)8192, null);
58+
59+
// Enables flow events:
60+
EventSource.SendCommand(eventSource, (EventCommand)16384, null);
61+
62+
// Enables both trace and flow events:
63+
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
64+
```
65+
66+
The following example enables event tracing in native SNI.dll when the application targets .NET Framework.
67+
68+
```cs
69+
// Native SNI tracing example
70+
// .NET Framework application
71+
using System;
72+
using System.Diagnostics.Tracing;
73+
using Microsoft.Data.SqlClient;
74+
75+
public class SqlClientListener : EventListener
76+
{
77+
protected override void OnEventSourceCreated(EventSource eventSource)
78+
{
79+
if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
80+
{
81+
// Enables both trace and flow events
82+
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
83+
}
84+
}
85+
}
86+
87+
class Program
88+
{
89+
static string connectionString = @"Data Source = localhost; Initial Catalog = AdventureWorks;Integrated Security=true;";
90+
91+
static void Main(string[] args)
92+
{
93+
using (SqlClientListener listener = new SqlClientListener())
94+
using (SqlConnection connection = new SqlConnection(connectionString))
95+
{
96+
connection.Open();
97+
}
98+
}
99+
}
100+
```
101+
102+
### Use Xperf to collect trace log
103+
104+
1. Start tracing using the following command line.
105+
106+
```
107+
xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSource
108+
```
109+
110+
2. Run the native SNI tracing example to connect to SQL Server.
111+
112+
3. Stop tracing using the following command line.
113+
114+
```
115+
xperf -stop trace
116+
```
117+
118+
4. Use PerfView to open the myTrace.etl file specified in Step 1. The SNI tracing log can be found with `Microsoft.Data.SqlClient.EventSource/SNIScope` and `Microsoft.Data.SqlClient.EventSource/SNITrace` event names.
119+
120+
![Use PerfView to view SNI trace file](media/view-event-trace-native-sni.png)
121+
122+
123+
### Use PerfView to collect trace log
124+
125+
1. Start PerfView and run `Collect > Collect` from menu bar.
126+
127+
2. Configure trace file name, output path, and provider name.
128+
129+
![Configure Prefview before collection](media/collect-event-trace-native-sni.png)
130+
131+
3. Start collection.
132+
133+
4. Run the native SNI tracing example to connect to SQL Server.
134+
135+
5. Stop collection from PerfView. It will take a while to generate PerfViewData.etl file according to configuration in Step 2.
136+
137+
6. Open the etl file in PerfView. The SNI tracing log can be found with `Microsoft.Data.SqlClient.EventSource/SNIScope` and `Microsoft.Data.SqlClient.EventSource/SNITrace` event names.
138+
139+
51140
## External resources
52141
For more information, see the following resources.
53142

54143
|Resource|Description|
55144
|--------------|-----------------|
56145
|[EventSource Class](/dotnet/api/system.diagnostics.tracing.eventsource)|Provides the ability to create ETW events.|
57-
|[EventListener Class](/dotnet/api/system.diagnostics.tracing.eventlistener)|Provides methods for enabling and disabling events from event sources.|
146+
|[EventListener Class](/dotnet/api/system.diagnostics.tracing.eventlistener)|Provides methods for enabling and disabling events from event sources.|

‎docs/connect/ado-net/media/collect-event-trace-native-sni.png‎

198 KB
Loading

‎docs/connect/ado-net/media/view-event-trace-native-sni.png‎

284 KB
Loading

‎docs/connect/ado-net/sql/azure-active-directory-authentication.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Using Azure Active Directory authentication with SqlClient"
33
description: "Describes how to use supported Azure Active Directory authentication modes to connect to Azure SQL data sources with SqlClient"
4-
ms.date: "11/10/2020"
4+
ms.date: "11/20/2020"
55
dev_langs:
66
- "csharp"
77
ms.prod: sql
@@ -26,9 +26,9 @@ Azure Active Directory (Azure AD) authentication uses identities in Azure Active
2626
The early **Microsoft.Data.SqlClient** supports `Active Directory Password` for .NET Framework, .NET Core, and .NET Standard. It also supports `Active Directory Integrated` authentication and `Active Directory Interactive` authentication for .NET Framework. Starting with **Microsoft.Data.SqlClient** 2.0.0, support for `Active Directory Integrated authentication` and `Active Directory Interactive` authentication has been extended across .NET Framework, .NET Core, and .NET Standard. A new `Active Directory Service Principal` authentication mode is also added in SqlClient 2.0.0 that makes use of the client ID and secret of a service principal identity to accomplish authentication. More authentication modes are added in SqlClient 2.1.0 including `Active Directory Device Code Flow` and `Active Directory Managed Identity` (also known as `Active Directory MSI`). These new modes enable the application to acquire an access token to connect to the server. More information about all the Active Directory authentications are covered in the following sections.
2727

2828

29-
## Setting Azure Active Directory authentication in the connection string
29+
## Setting Azure Active Directory authentication
3030

31-
When connecting to Azure SQL data sources with Azure AD authentication, the application needs to provide a valid authentication mode. This table lists the supported authentication modes, which can be specified with the `Authentication` connection property.
31+
When connecting to Azure SQL data sources with Azure AD authentication, the application needs to provide a valid authentication mode. This table lists the supported authentication modes, which can be specified with the `Authentication` connection property in the connection string.
3232

3333
| Value | Description | Framework | Microsoft.Data.SqlClient Version |
3434
|:--|:--|:--|:--:|
@@ -43,7 +43,7 @@ When connecting to Azure SQL data sources with Azure AD authentication, the appl
4343
> <sup>1</sup> Before **Microsoft.Data.SqlClient** 2.0.0, `Active Directory Integrated` and `Active Directory Interactive` authentications are only supported on .NET Framework 4.6+.
4444
4545

46-
## Connecting with Active Directory Password authentication
46+
## Using Active Directory Password authentication
4747

4848
`Active Directory Password` authentication mode supports authentication to Azure data sources with Azure AD for native or federated Azure AD users. When using this mode, user credentials must be provided in the connection string. The following example shows how to use `Active Directory Password` authentication.
4949

@@ -57,7 +57,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString)) {
5757
```
5858

5959

60-
## Connecting with Active Directory Integrated authentication
60+
## Using Active Directory Integrated authentication
6161

6262
To use `Active Directory Integrated` authentication mode, you need to federate the on-premise Active Directory with Azure AD in the cloud. Federation can be done using Active Directory Federation Services (ADFS), for example. When logged in to a domain-joined machine, you can access Azure SQL data sources without being prompted for credentials with this mode. Username and password cannot be specified in the connection string for .NET framework applications. Username is optional in the connection string for .NET Core and .NET Standard applications. The Credential property of SqlConnection cannot be set in this mode. The following code snippet is an example of when `Active Directory Integrated` authentication is in use.
6363

@@ -78,7 +78,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
7878
```
7979

8080

81-
## Connecting with Active Directory Interactive authentication
81+
## Using Active Directory Interactive authentication
8282

8383
`Active Directory Interactive` authentication supports multi-factor authentication technology to connect to Azure SQL data sources. If this authentication mode is provided in the connection string, an Azure authentication screen will be displayed and ask the user to enter valid credentials. The password cannot be specified in the connection string. The Credential property of SqlConnection cannot be set in this mode. With **Microsoft.Data.SqlClient** 2.0.0 and above, username is allowed in the connection string when in interactive mode. The following example displays how to use `Active Directory Interactive` authentication.
8484

@@ -100,7 +100,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
100100
```
101101

102102

103-
## Connecting with Active Directory Service Principal authentication
103+
## Using Active Directory Service Principal authentication
104104

105105
In `Active Directory Service Principal` authentication mode, the client application can connect to Azure SQL data sources by providing the client ID and secret of a service principal identity. Service Principal authentication involves setting up an App registration with a secret, granting permissions to the App in the Azure SQL Database instance, and then connecting with the correct credential. The following example shows how to use `Active Directory Service Principal` authentication.
106106

@@ -114,7 +114,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString)) {
114114
```
115115

116116

117-
## Connecting with Active Directory Device Code Flow authentication
117+
## Using Active Directory Device Code Flow authentication
118118

119119
With [Microsoft Authentication Library](/azure/active-directory/develop/msal-overview) for .NET (MSAL.NET), `Active Directory Device Code Flow` authentication enables the client application to connect to Azure SQL data sources from devices and operating systems that do not have an interactive web browser. Interactive authentication will be performed on another device. For more information about device code flow authentication, see [OAuth2.0 Device Code Flow](/azure/active-directory/develop/v2-oauth2-device-code). When this mode is in use, the Credential property of SqlConnection cannot be set. Also, the username and password must not be specified in the connection string. The following code snippet is an example of using `Active Directory Device Code Flow` authentication.
120120

@@ -128,7 +128,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString)) {
128128
```
129129

130130

131-
## Connecting with Active Directory Managed Identity authentication
131+
## Using Active Directory Managed Identity authentication
132132

133133
**Managed Identities** for Azure resources is the new name for the service formerly known as **Managed Service Identity (MSI)**. When a client application uses an Azure resources to access an Azure service that support Azure AD authentication, **Managed Identities** can be used to authenticate by providing an identity for the Azure resource in Azure AD and use it to obtain access tokens. This can eliminate the need for developers having to manage credentials and secrets. There are two types of **Managed Identities**: _System-assigned Managed Identity_ and _User-assigned Managed Identity_. The _System-assigned Managed Identity_ is an identity created on a service instance in Azure AD. It is tied to the lifecycle of that service instance. _User-assigned Managed Identity_ is created as a standalone Azure resource. It can be assigned to one or more instances of an Azure service. For more information about **Managed Identities**, see [About managed identities for Azure resources](/azure/active-directory/managed-identities-azure-resources/overview).
134134

@@ -169,7 +169,7 @@ using (SqlConnection conn = new SqlConnection(ConnectionString2)) {
169169
```
170170

171171

172-
## Customizing Active Directory authentication with ActiveDirectoryAuthenticationProvider class
172+
## Customizing Active Directory authentication
173173

174174
Besides using the Active Directory authentication built into the driver, **Microsoft.Data.SqlClient** 2.1.0 and later provide applications the option to customize AD authentication. The customization is based on the _ActiveDirectoryAuthenticationProvider_ class, which is derived from the [_SqlAuthenticationProvider_](/dotnet/api/system.data.sqlclient.sqlauthenticationprovider) abstract class. During Active Directory authentication, the client application can define its own _ActiveDirectoryAuthencationProvider_ by either using a customized callback method or passing `Application Client Id` to the MSAL library via SqlClient driver for fetching access tokens.
175175

‎docs/connect/ado-net/sql/data-classification.md‎

Lines changed: 76 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Data discovery and classification in SqlClient"
33
description: "Describes how to check if a SQL Server database supports data classification and how to access data classification information through a SqlDataReader object."
4-
ms.date: "06/15/2020"
4+
ms.date: "11/23/2020"
55
dev_langs:
66
- "csharp"
77
ms.prod: sql
@@ -20,10 +20,84 @@ ms.reviewer:
2020

2121
[Data Discovery & Classification](../../../relational-databases/security/sql-data-discovery-and-classification.md) is a set of advanced services for discovering, classifying, labeling & reporting the sensitive data in your databases. SqlClient provides an API exposing read-only Data Discovery and Classification information when the underlying source supports the feature. This information is accessed through SqlDataReader.
2222

23+
Microsoft.Data.SqlClient v2.1.0 introduces support for Data Classification's `Sensitivity Rank` information. `Sensitivity Rank` is an identifier based on a predefined set of values, which define sensitivity rank. It can be used by other services like Advanced Threat Protection to detect anomalies based on their rank. The following Data Classification APIs are now available in Microsoft.Data.SqlClient.DataClassification namespace:
24+
25+
```csharp
26+
// New in Microsoft.Data.SqlClient v2.1.0
27+
public enum SensitivityRank
28+
{
29+
NOT_DEFINED = -1,
30+
NONE = 0,
31+
LOW = 10,
32+
MEDIUM = 20,
33+
HIGH = 30,
34+
CRITICAL = 40
35+
}
36+
37+
public sealed class SensitivityClassification
38+
{
39+
// Returns the sensitivity rank for the query associated with the active 'SqlDataReader'.
40+
// New in Microsoft.Data.SqlClient v2.1.0
41+
public SensitivityRank SensitivityRank;
42+
43+
// Returns the labels collection for this 'SensitivityClassification' Object
44+
public ReadOnlyCollection<Label> Labels;
45+
46+
// Returns the information types collection for this 'SensitivityClassification' Object
47+
public ReadOnlyCollection<InformationType> InformationTypes;
48+
49+
// Returns the column sensitivity for this 'SensitivityClassification' Object
50+
public ReadOnlyCollection<ColumnSensitivity> ColumnSensitivities;
51+
}
52+
53+
public sealed class SensitivityProperty
54+
{
55+
// Returns the sensitivity rank for this 'SensitivityProperty' Object
56+
// New in Microsoft.Data.SqlClient v2.1.0
57+
public SensitivityRank SensitivityRank;
58+
59+
// Returns the label for this 'SensitivityProperty' Object
60+
public Label Label;
61+
62+
// Returns the information type for this 'SensitivityProperty' Object
63+
public InformationType InformationType;
64+
}
65+
66+
public sealed class Label
67+
{
68+
// Gets the name for this 'Label' object
69+
public string Name;
70+
71+
// Gets the ID for this 'Label' object
72+
public string Id;
73+
}
74+
75+
public sealed class InformationType
76+
{
77+
// Gets the name for this 'InformationType' object
78+
public string Name;
79+
80+
// Gets the ID for this 'InformationType' object
81+
public string Id;
82+
}
83+
84+
public sealed class ColumnSensitivity
85+
{
86+
// Returns the list of sensitivity properties as received from Server for this 'ColumnSensitivity' information
87+
public ReadOnlyCollection<SensitivityProperty> SensitivityProperties;
88+
}
89+
```
90+
91+
> [!NOTE]
92+
> Microsoft.Data.SqlClient reads `Sensitivity Rank` information only if SQL Server supports Data Classification with rank. For servers use old version of Data Classification without rank, the rank value for queries is "NOT DEFINED".
93+
2394
This sample application demonstrates how to access the Data Classification properties of SqlDataReader.
2495

2596
[!code-csharp [SqlDataReader_DataDiscoveryAndClassification#1](~/../sqlclient/doc/samples/SqlDataReader_DataDiscoveryAndClassification.cs#1)]
2697

98+
2799
**See also**
28100

29-
[SQL Server features and ADO.NET](sql-server-features-adonet.md)
101+
- [SQL Server features and ADO.NET](sql-server-features-adonet.md)
102+
- [sys.sensitivity_classifications (Transact-SQL)](../../../relational-databases/system-catalog-views/sys-sensitivity-classifications-transact-sql.md)
103+
- [ADD SENSITIVITY CLASSIFICATION](../../../t-sql/statements/add-sensitivity-classification-transact-sql.md)

0 commit comments

Comments
 (0)