As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Rastrear consultas SQL com o X-Ray SDK para .NET
**nota**
Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
O SDK fornece uma classe wrapper para `System.Data.SqlClient.SqlCommand`, denominada `TraceableSqlCommand`, que você pode usar em vez de `SqlCommand`. É possível inicializar um comando SQL com a classe `TraceableSqlCommand`.
## Rastrear consultas SQL com métodos síncronos e assíncronos
Os exemplos a seguir mostram como usar o `TraceableSqlCommand` para rastrear automaticamente consultas do SQL Server de forma síncrona e assíncrona.
**Example `Controller.cs` – Instrumentação de cliente SQL (síncrono)**
```
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();
}
}
```
É possível executar a consulta de forma assíncrona usando o método `ExecuteReaderAsync`.
**Example `Controller.cs` – instrumentação de cliente SQL (assíncrono)**
```
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();
}
}
```
## Coletar consultas SQL feitas ao SQL Server
É possível habilitar a captura de `SqlCommand.CommandText` como parte do subsegmento criado pela consulta SQL. O `SqlCommand.CommandText` aparece como o campo `sanitized_query` no subsegmento JSON. Por padrão, esse recurso está desabilitado para segurança.
**nota**
Não habilite o recurso de coleta se você estiver incluindo informações confidenciais como texto simples em suas consultas SQL.
É possível habilitar a coleção de consultas SQL de duas maneiras:
+ Defina a propriedade `CollectSqlQueries` como `true` na configuração global do aplicativo.
+ Defina o parâmetro `collectSqlQueries` na instância `TraceableSqlCommand` como `true` para coletar chamadas dentro da instância.
### Ativar a CollectSqlQueries propriedade global
Os exemplos a seguir mostram como habilitar a propriedade `CollectSqlQueries` para .NET e .NET Core.
------
#### [ .NET ]
Para definir a propriedade `CollectSqlQueries` como `true` na configuração global do seu aplicativo em .NET, modifique o `appsettings` do arquivo `Web.config` ou `App.config`, conforme mostrado.
**Example `App.config` ou `Web.config`: habilitar a coleta de consultas SQL globalmente**
```
```
------
#### [ .NET Core ]
Para definir a propriedade `CollectSqlQueries` como `true` na configuração global do aplicativo no .NET Core, modifique o arquivo `appsettings.json` na chave do X-Ray, conforme mostrado.
**Example `appsettings.json`: habilitar a coleta de consultas SQL globalmente**
```
{
"XRay": {
"CollectSqlQueries":"true"
}
}
```
------
### Ative o collectSqlQueries parâmetro
É possível definir o parâmetro `collectSqlQueries` na instância `TraceableSqlCommand` como `true` para coletar o texto da consulta SQL para consultas do SQL Server feitas usando essa instância. Definir o parâmetro como `false` desabilita o recurso `CollectSqlQuery` para a instância `TraceableSqlCommand`.
**nota**
O valor de `collectSqlQueries` na instância `TraceableSqlCommand` substitui o valor definido na configuração global da propriedade `CollectSqlQueries`.
**Example Exemplo de `Controller.cs`: habilitar a coleta de consultas SQL para a instância**
```
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();
}
}
```