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

# AWS X-Ray 适用于.NET 的 SDK
<a name="xray-sdk-dotnet"></a>

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](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 SDK 是一个用于检测 C\$1 .NET Web 应用程序、.NET Core Web 应用程序和.NET 核心函数的库。 AWS Lambda它提供用于生成跟踪数据并将其发送到 [X-Ray 进程守护程序](xray-daemon.md)的类及方法。这包括有关应用程序处理的传入请求的信息，以及应用程序对下游 AWS 服务、HTTP Web APIs 和 SQL 数据库的调用的信息。

**注意**  
X-Ray SDK for .NET 是一个开源项目。你可以关注该项目并在 [github 上 GitHub提交议题和拉取请求。 com/aws/aws](https://github.com/aws/aws-xray-sdk-dotnet)-xray-sdk-dotnet

对于 Web 应用程序，首先通过[添加消息处理程序到 Web 配置](xray-sdk-dotnet-messagehandler.md)来跟踪传入请求。消息处理程序为每个被跟踪的请求创建一个[分段](xray-concepts.md#xray-concepts-segments)并在发送响应时完成该分段。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。

对于由经过检测的应用程序或服务调用的 Lambda 函数，Lambda 会读取[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)并自动跟踪采样的请求。对于其他函数，您可以[将 Lambda 配置](xray-services-lambda.md)为采样和跟踪传入请求。无论哪种情况，Lambda 都会创建分段并将其提供给 X-Ray 开发工具包。

**注意**  
在 Lambda 上，X-Ray 开发工具包是可选的。如果您不在函数中使用它，您的服务映射仍将包含一个用于 Lambda 服务的节点，以及每个 Lambda 函数的节点。可通过添加该开发工具包检测函数代码，将子分段添加到 Lambda 记录的函数分段。请参阅[AWS Lambda 和 AWS X-Ray](xray-services-lambda.md)了解更多信息。

接下来，使用 X-Ray SDK for .NET [检测 适用于 .NET 的 AWS SDK 客户端](xray-sdk-dotnet-sdkclients.md)。每当您使用已检测的客户端调用下游 AWS 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 AWS 服务和您在服务中访问的资源在跟踪图上显示为下游节点，以帮助您识别各个连接上的错误和限制问题。

适用于.NET 的 X-Ray SDK 还为对 [HTTP Web APIs](xray-sdk-dotnet-httpclients.md) 和 [SQL 数据库](xray-sdk-dotnet-sqlqueries.md)的下游调用提供了工具。`GetResponseTraced` 的 `System.Net.HttpWebRequest` 扩展方法跟踪传出 HTTP 调用。您可以使用 X-Ray SDK for .NET 的 `SqlCommand` 版本来检测 SQL 查询。

在开始使用 SDK 后，通过[配置记录器和消息处理程序](xray-sdk-dotnet-configuration.md)来自定义其行为。您可以添加插件来记录有关应用程序上运行的计算资源的数据，通过定义采样规则来自定义采样行为，设置日志级别以在应用程序日志中查看来自开发工具包的更多或更少的信息。

记录有关请求以及应用程序在[注释和元数据](xray-sdk-dotnet-segment.md)中所做的工作的其他信息。注释是简单的键值对，已为这些键值对编制索引以用于[筛选条件表达式](xray-console-filters.md)，以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低，并且可以记录整个对象和数组 - 可序列化为 JSON 的任何项目。

**注释和元数据**  
注释和元数据是您使用 X-Ray 开发工具包添加到分段的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始分段中查看。您授予 X-Ray 读取权限的任何人都可以查看这些数据。

当代码中具有大量检测的客户端时，一个请求分段可包含大量子分段，检测的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在[自定义子分段](xray-sdk-dotnet-subsegments.md)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段，并记录子分段的元数据和注释，而不是编写父分段的所有内容。

有关 SDK 的类和方法的参考文档，请参阅以下内容：
+ [AWS X-Ray 适用于.NET 的 SDK API 参考](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray 适用于.NET 的 SDK Core API 参考](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)

同一个程序包同时支持 .NET 和 .NET Core，但使用的类不同。本章中的示例与 .NET API 参考相关，除非该类特定于 .NET Core。

## 要求
<a name="xray-sdk-requirements"></a>

适用于.NET 的 X-Ray SDK 需要.NET 框架 4.5 或更高版本以及 适用于 .NET 的 AWS SDK。

对于 .NET Core 应用程序和函数，SDK 需要 .NET Core 2.0 或更高版本。

## 将 X-Ray SDK for .NET 添加到应用程序
<a name="xray-sdk-dotnet-dependencies"></a>

用于 NuGet 将适用于.NET 的 X-Ray SDK 添加到您的应用程序中。

**在 Visual Studio 中使用 NuGet 包管理器安装适用于.NET 的 X-Ray SDK**

1. 选择 “**工具**”、“P **NuGet ackage Manager****”、“管理解决方案 NuGet 包**”。

1. 搜索**AWSXRay录音机**。

1. 依次选择此程序包和**安装**。

## 依赖关系管理
<a name="xray-sdk-dotnet-dependencies"></a>

可从 [Nuget](https://www.nuget.org/packages/AWSXRayRecorder/) 获得 X-Ray SDK for .NET。使用程序包管理器安装 SDK ：

```
Install-Package AWSXRayRecorder -Version 2.10.1
```

`AWSXRayRecorder v2.10.1` NuGet 程序包具有以下依赖项：

### .NET Framework 4.5
<a name="xray-sdk-dotnet-dependencies-4.5"></a>

```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- AWSSDK.Core (>= 3.3.25.1)
|      
|-- AWSXRayRecorder.Handlers.AspNet (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- EntityFramework (>= 6.2.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
    |-- AWSXRayRecorder.Core (>= 2.10.1)
```

### .NET Framework 2.0
<a name="xray-sdk-dotnet-dependencies-2.0"></a>

```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- AWSSDK.Core (>= 3.3.25.1)
|   |-- Microsoft.AspNetCore.Http (>= 2.0.0)
|   |-- Microsoft.Extensions.Configuration (>= 2.0.0)
|   |-- System.Net.Http (>= 4.3.4)
|      
|-- AWSXRayRecorder.Handlers.AspNetCore (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- Microsoft.AspNetCore.Http.Extensions (>= 2.0.0)
|   |-- Microsoft.AspNetCore.Mvc.Abstractions (>= 2.0.0)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- Microsoft.EntityFrameworkCore.Relational (>= 3.1.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- System.Data.SqlClient (>= 4.4.0)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
    |-- AWSXRayRecorder.Core (>= 2.10.1)
```

有关依赖项管理的详细信息，请参阅 Microsoft 关于 [Nuget 依赖项](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies)和 [Nuget 依赖项解析](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution)的文档。