本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用适用于 .NET 的 X-Ray 开发工具包跟踪 SQL 查询
SQL 查询

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

适用于 .NET 的 X-Ray 开发工具包为 `System.Data.SqlClient.SqlCommand` 提供了名为 `TraceableSqlCommand` 的包装程序类，您可以用来代替 `SqlCommand`。您可以使用 `TraceableSqlCommand` 类初始化 SQL 命令。

## 使用同步和异步方法跟踪 SQL 查询


以下示例显示如何使用 `TraceableSqlCommand` 来同步和异步自动跟踪 SQL Server 查询。

**Example `Controller.cs` - SQL 客户端检测（异步）**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);

private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
  {
    sqlCommand.Connection.Open();
    sqlCommand.ExecuteNonQuery();
  }
}
```

您可以使用 `ExecuteReaderAsync` 方法异步执行查询。

**Example `Controller.cs` - SQL 客户端检测（异步）**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
  {
    await sqlCommand.ExecuteReaderAsync();
  }
}
```

## 收集对 SQL Server 执行的 SQL 查询


您可以启用 `SqlCommand.CommandText` 的捕获作为 SQL 查询创建的子分段的一部分。`SqlCommand.CommandText` 显示为子分段 JSON 中的字段 `sanitized_query`。默认情况下，出于安全考虑，此功能处于禁用状态。

**注意**  
如果您在 SQL 查询中以明文形式包含敏感信息，请不要启用收集功能。

可以通过下列两种方式启用 SQL 查询：
+ 在应用程序全局配置中将 `CollectSqlQueries` 属性设置为 `true`。
+ 将 `TraceableSqlCommand` 实例中的 `collectSqlQueries` 参数设置为 `true` 以收集该实例中的调用。

### 启用全局 CollectSqlQueries 属性


以下示例显示如何为 .NET 和 .NET Core 启用 `CollectSqlQueries` 属性。

------
#### [ .NET ]

在 .NET 中您应用程序的全局配置内，要将 `CollectSqlQueries` 属性设置为 `true`，请修改您的 `App.config` 或 `Web.config` 文件的 `appsettings`，如图所示。

**Example `App.config` 或 `Web.config` - 全局启用 SQL 查询的收集**  

```
<configuration>
<appSettings>
    <add key="CollectSqlQueries" value="true">
</appSettings>
</configuration>
```

------
#### [ .NET Core ]

在 .NET Core 中您应用程序的全局配置内，要将 `CollectSqlQueries` 属性设置为 `true`，请在 X-Ray 键下修改您的 `appsettings.json` 文件，如图所示。

**Example `appsettings.json` - 全局启用 SQL 查询的收集**  

```
{
  "XRay": {
    "CollectSqlQueries":"true"
  }
}
```

------

### 启用该 collectSqlQueries 参数


您可以在 `TraceableSqlCommand` 实例中将 `collectSqlQueries` 参数设置为 `true`，以收集使用该实例进行的 SQL Server 查询的 SQL 查询文本。将参数设置为 `false` 禁用 `TraceableSqlCommand` 实例的 `CollectSqlQuery` 功能。

**注意**  
 `TraceableSqlCommand` 实例中 `collectSqlQueries` 的值将覆盖 `CollectSqlQueries` 属性的全局配置中设置的值。

**Example 示例 `Controller.cs` - 启用实例的 SQL 查询收集**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);

private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var command = new TraceableSqlCommand("SELECT " + id, sqlConnection, collectSqlQueries: true))
  {
    command.ExecuteNonQuery();
  }
}
```