本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用適用於 .NET 的 X-Ray 開發套件追蹤 SQL 查詢
<a name="xray-sdk-dotnet-sqlqueries"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

適用於 .NET 的 X-Ray 開發套件提供`System.Data.SqlClient.SqlCommand`名為 的包裝函式類別`TraceableSqlCommand`，可用於取代 `SqlCommand`。您可以使用 `TraceableSqlCommand` 類別來初始化 SQL 命令。

## 使用同步和非同步方法追蹤 SQL 查詢
<a name="xray-sdk-dotnot-sqlqueries-trace"></a>

以下範例說明如何使用 `TraceableSqlCommand` 來以同步和非同步方式自動追蹤 SQL Server 查詢。

**Example `Controller.cs` - SQL 用戶端檢測 (同步)**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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 查詢
<a name="xray-sdk-dotnot-sqlqueries-collect"></a>

您可以啟用 `SqlCommand.CommandText` 的擷取，做為 SQL 查詢所建立子區段的一部分。`SqlCommand.CommandText` 會在子區段 JSON 中顯示為欄位 `sanitized_query`。基於安全考量，此功能預設為停用。

**注意**  
如果您在 SQL 查詢中包含純文字形式的敏感資訊，請勿啟用收集功能。

您可以透過兩種方式啟用收集 SQL 查詢：
+ 針對您的應用程式，在全域組態中將 `CollectSqlQueries` 屬性設定為 `true`。
+ 將 `TraceableSqlCommand` 執行個體中的 `collectSqlQueries` 參數設為 `true`，以收集執行個體內的呼叫。

### 啟用全域 CollectSqlQueries 屬性
<a name="xray-sdk-dotnot-sqlqueries-collect-global"></a>

以下範例說明如何啟用適用於 .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 `true` 中將應用程式全域組態中的 `CollectSqlQueries` 屬性設定為 ，請在 X-Ray 金鑰下修改 `appsettings.json` 檔案，如下所示。

**Example `appsettings.json` – 全域啟用 SQL 查詢集合**  

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

------

### 啟用 collectSqlQueries 參數
<a name="xray-sdk-dotnot-sqlqueries-collect-instance"></a>

您可以將 `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.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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();
  }
}
```