本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon X-Ray 适用于.NET 的 SDK
X-Ray SDK for .NET
**注意**
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 SDK 是一个用于检测 C\$1 .NET Web 应用程序、.NET Core Web 应用程序和.NET 核心函数的库。 Amazon Lambda它提供用于生成跟踪数据并将其发送到 [X-Ray 进程守护程序](xray-daemon.md)的类及方法。这包括有关应用程序处理的传入请求的信息，以及应用程序对下游 Amazon Web Services 服务、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 记录的函数分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。
接下来，使用 X-Ray SDK for .NET [检测 适用于 .NET 的 Amazon SDK 客户端](xray-sdk-dotnet-sdkclients.md)。每当您使用已检测的客户端调用下游 Amazon Web Services 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 Amazon 服务和您在服务中访问的资源在跟踪图上显示为下游节点，以帮助您识别各个连接上的错误和限制问题。
适用于.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 的类和方法的参考文档，请参阅以下内容：
+ [Amazon X-Ray 适用于.NET 的 SDK API 参考](https://docs.amazonaws.cn//xray-sdk-for-dotnet/latest/reference)
+ [Amazon X-Ray 适用于.NET 的 SDK Core API 参考](https://docs.amazonaws.cn//xray-sdk-for-dotnetcore/latest/reference)
同一个程序包同时支持 .NET 和 .NET Core，但使用的类不同。本章中的示例与 .NET API 参考相关，除非该类特定于 .NET Core。
## 要求
适用于.NET 的 X-Ray SDK 需要.NET 框架 4.5 或更高版本以及 适用于 .NET 的 Amazon SDK。
对于 .NET Core 应用程序和函数，SDK 需要 .NET Core 2.0 或更高版本。
## 将 X-Ray SDK for .NET 添加到应用程序
用于 NuGet 将适用于.NET 的 X-Ray SDK 添加到您的应用程序中。
**在 Visual Studio 中使用 NuGet 包管理器安装适用于.NET 的 X-Ray SDK**
1. 选择 “**工具**”、“P **NuGet ackage Manager****”、“管理解决方案 NuGet 包**”。
1. 搜索**AWSXRay录音机**。
1. 依次选择此程序包和**安装**。
## 依赖关系管理
可从 [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
```
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
```
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)的文档。
# 配置适用于 .NET 的 X-Ray 开发工具包
配置
**注意**
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 开发工具包 以包括应用程序在其上运行的服务的相关信息，修改默认采样行为，或者添加应用于特定路径请求的采样规则。
对于 .NET Web 应用程序，请将密钥添加到 `appSettings` 文件的 `Web.config` 部分。
**Example Web.config**
```
```
对于 .NET Core，请使用名为 `appsettings.json` 的顶层密钥创建名为 `XRay` 的文件。
**Example .NET appsettings.json**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin",
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
然后，在应用程序代码中，生成配置对象并将其用于初始化 X-Ray 记录器。在[初始化记录器](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)之前执行此操作。
**Example .NET Core Program.cs 记录器配置**
```
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```
如果您正在检测 .NET Core Web 应用程序，则在[配置消息处理程序](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)时，还可以将配置对象传递到 `UseXRay` 方法。对于 Lambda 函数，使用上面所示的 `InitializeInstance` 方法。
有关 .NET Core 配置 API 的更多信息，请参阅 docs.microsoft.com 上的[配置 ASP.NET Core 应用程序](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration)。
**Topics**
+ [
## 插件
](#xray-sdk-dotnet-configuration-plugins)
+ [
## 采样规则
](#xray-sdk-dotnet-configuration-sampling)
+ [
## 日志记录 (.NET)
](#xray-sdk-dotnet-configuration-logging)
+ [
## 日志记录 (.NET Core)
](#xray-sdk-dotnet-configuration-corelogging)
+ [
## 环境变量
](#xray-sdk-dotnet-configuration-envvars)
## 插件
使用插件可添加有关托管您应用程序的服务的数据。
**插件**
+ Amazon EC2 — `EC2Plugin` 添加实例 ID、可用区和 CloudWatch 日志组。
+ Elastic Beanstalk - `ElasticBeanstalkPlugin` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ECSPlugin` 添加容器 ID。
要使用插件，请通过添加 `AWSXRayPlugins` 设置配置适用于 .NET 的 X-Ray 开发工具包客户端。如果多个插件应用到您的应用程序，请在同一个设置中指定所有这些设置，以逗号分隔。
**Example Web.config - 插件**
```
```
**Example .NET Core appsettings.json 插件**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
}
}
```
## 采样规则
该 SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。[在 X-Ray 控制台中创建其他规则](xray-console-sampling.md)以自定义为每个应用程序记录的数据量。
该 SDK 按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则 SDK 仅应用第一条规则。
**注意**
如果 SDK 无法访问 X-Ray 来获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有其他请求的百分之五。如果主机无权调用采样，或者无法连接到 X-Ray 守护程序 APIs，后者充当 SDK 发出的 API 调用的 TCP 代理，则可能会发生这种情况。
您还可以将 SDK 配置为从 JSON 文档加载采样规则。在 X-Ray 采样不可用的情况下，SDK 可以使用本地规则作为备份，也可以只使用本地规则。
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率，对于 `/api/move/` 之下的路径要跟踪的请求数量不设下限。默认规则中每秒的第一个请求以及其他请求的百分之十。
在本地定义规则的缺点是，固定目标由记录器的每个实例独立应用而不是由 X-Ray 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。
启 Amazon Lambda用，您无法修改采样率。如果您的函数由检测服务调用，Lambda 将记录生成由该服务采样的请求的调用。如果启用了主动跟踪且不存在任何跟踪标头，则 Lambda 会做出采样决定。
要配置备份规则，请指示从具有适用于 .NET 的 X-Ray 开发工具包 `SamplingRuleManifest` 设置的文件加载采样规则。
**Example .NET Web.config - 采样规则**
```
```
**Example .NET Core appsettings.json 采样规则**
```
{
"XRay": {
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
要仅使用本地规则，请使用 `LocalizedSamplingStrategy` 构建记录器。如果您配置了备份规则，请删除该配置。
**Example .NET global.asax - 本地采样规则**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
```
**Example .NET Core Program.cs - 本地采样规则**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);
```
## 日志记录 (.NET)
适用于 .NET 的 X-Ray 开发工具包使用与 [适用于 .NET 的 Amazon SDK](https://docs.amazonaws.cn/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) 相同的日志记录机制。如果您已经将应用程序配置为记录 适用于 .NET 的 Amazon SDK 输出，则同样的配置也适用于适用于.NET 的 X-Ray SDK 的输出。
要配置日志记录，请将名为 `aws` 的配置部分添加到您的 `App.config` 文件或 `Web.config` 文件。
**Example Web.config - 日志记录**
```
...
```
有关更多信息，请参阅 [适用于 .NET 的 Amazon SDK 开发人员指南](https://docs.amazonaws.cn/sdk-for-net/latest/developer-guide/net-dg-config.html) 中的*配置您的适用于 .NET 的 Amazon SDK 应用程序*。
## 日志记录 (.NET Core)
适用于 .NET 的 X-Ray 开发工具包使用与 [适用于 .NET 的 Amazon SDK](https://docs.amazonaws.cn/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) 相同的日志记录选项。要为 .NET Core 应用程序配置日志记录，请将日志选项传递给 `AWSXRayRecorder.RegisterLogger` 方法。
例如，要使用 log4net，请创建定义记录器的配置文件、输出格式和文件位置。
**Example .NET Core log4net.config**
```
```
然后，创建记录器并在程序代码中应用配置。
**Example .NET Core Program.cs - 日志记录**
```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
class Program
{
private static ILog log;
static Program()
{
var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
log = LogManager.GetLogger(typeof(Program));
AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
}
static void Main(string[] args)
{
...
}
}
```
有关配置 log4net 的更多信息，请参阅 logging.apache.org 上的[配置](https://logging.apache.org/log4net/release/manual/configuration.html)。
## 环境变量
您可以使用环境变量配置适用于.NET 的 X-Ray 开发工具包。SDK 支持以下变量。
+ `AWS_XRAY_TRACING_NAME` - 设置开发工具包用于进行分段的服务名称。覆盖您根据 servlet 筛选器的[分段命名策略](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming)设置的服务名称。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，SDK 使用用于跟踪数据（UDP）和采样（TCP）的 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。
**Format**
+ **同一个端口** — `address:port`
+ **不同的端口** — `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。
**有效值**
+ `RUNTIME_ERROR`— 引发运行时异常。
+ `LOG_ERROR`— 记录错误并继续（默认）。
+ `IGNORE_ERROR`— 忽略错误并继续。
对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。
# 使用适用于 .NET 的 X-Ray 开发工具包检测传入 HTTP 请求
传入请求
**注意**
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)。
您可以使用 X-Ray SDK 来跟踪您的应用程序在 Amazon EC2 或 Amazon ECS 的 EC2 实例上提供的 Amazon Elastic Beanstalk传入 HTTP 请求。
使用消息处理程序检测传入 HTTP 请求。当您将 X-Ray 消息处理程序添加到应用程序时，适用于 .NET 的 X-Ray 开发工具包将为每个采样请求创建分段。此分段包括 HTTP 请求的计时、方法和处置。其他检测会在此分段上创建子分段。
**注意**
对于 Amazon Lambda 函数，Lambda 会为每个采样请求创建一个分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。
每个分段都有一个名称，用于在服务映射中标识您的应用程序。可以静态命名分段，也可以将 SDK 配置为根据传入请求中的主机标头对其进行动态命名。动态命名允许根据请求中的域名对跟踪进行分组，并且在名称不匹配预期模式时（例如，如果主机标头是伪造的）应用默认名称。
**转发的请求**
如果负载均衡器或其他中间将请求转发到您的应用程序，X-Ray 会提取请求 `X-Forwarded-For` 标头中的客户端 IP 而非 IP 数据包中的源 IP。由于转发的请求记录的客户端 IP 可以伪造，因此不应信任。
信息处理程序使用包含以下信息的 `http` 数据块为每个传入请求创建一个分段：
+ **HTTP 方法** - GET、POST、PUT、DELETE 等。
+ **客户端地址** - 发送请求的客户端的 IP 地址。
+ **响应代码** - 已完成请求的 HTTP 响应代码。
+ **时间** - 开始时间（收到请求时）和结束时间（发送响应时）。
+ **用户代理** - 请求中的 `user-agent`。
+ **内容长度** - 响应中的 `content-length`。
**Topics**
+ [
## 检测传入请求 (.NET)
](#xray-sdk-dotnet-messagehandler-globalasax)
+ [
## 检测传入请求 (.NET Core)
](#xray-sdk-dotnet-messagehandler-startupcs)
+ [
## 配置分段命名策略
](#xray-sdk-dotnet-messagehandler-naming)
## 检测传入请求 (.NET)
要检测由您的应用程序所服务的请求，请在 `global.asax` 文件的 `Init` 方法中调用 `RegisterXRay`。
**Example global.asax - 消息处理程序**
```
using System.Web.Http;
using [Amazon.XRay.Recorder.Handlers.AspNet](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AspNet.htm);
namespace SampleEBWebApplication
{
public class MvcApplication : System.Web.HttpApplication
{
public override void Init()
{
base.Init();
AWSXRayASPNET.RegisterXRay(this, "MyApp");
}
}
}
```
## 检测传入请求 (.NET Core)
若要检测您的应用程序处理的请求，请在启动类的 `Configure` 方法中的任何其他中间件之前调用 `UseXRay` 方法。因为理想情况下，X-Ray 应该是第一个处理请求的中间件，以及最后一个处理管道中响应的中间件。
**注意**
对于.NET Core 2.0，如果应用程序中有 `UseExceptionHandler` 方法，请确保在 `UseExceptionHandler` 方法之后调用 `UseXRay` 以确保记录下异常。
**Example Startup.cs**
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseXRay("MyApp");
// additional middleware
...
}
```
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseExceptionHandler("/Error");
app.UseXRay("MyApp");
// additional middleware
...
}
```
`UseXRay` 方法还会获取[配置对象](xray-sdk-dotnet-configuration.md)作为第二个参数。
```
app.UseXRay("MyApp", configuration);
```
## 配置分段命名策略
Amazon X-Ray 使用*服务名称*来标识您的应用程序，并将其与您的应用程序使用的其他应用程序、数据库 APIs、外部数据库和 Amazon 资源区分开来。当 X-Ray SDK 为传入请求生成分段时，会将应用程序的服务名称记录在分段的[名称字段](xray-api-segmentdocuments.md#api-segmentdocuments-fields)中。
X-Ray SDK 可以用在 HTTP 请求标头中的 hostname 来命名分段。不过，此标头可以伪造，会导致服务地图中出现意料之外的节点。为防止 SDK 由于包含伪造的主机标头的请求而错误地命名分段，必须为传入请求指定一个默认名称。
如果应用程序为多个域的请求提供服务，则可以将 SDK 配置为使用动态命名策略以在分段名称中反映出这一点。动态命名策略允许 SDK 将主机名用于符合预期模式的请求，并将默认名称应用于不符合预期模式的请求。
例如，可能有一款应用程序为发送到三个子域的请求提供服务，分别为 `www.example.com`、`api.example.com` 和 `static.example.com`。可以使用格式 `*.example.com` 的动态命名策略以识别包含不同名称的子域的分段，服务地图上因此会显示三个服务节点。如果应用程序收到包含与该格式不匹配的 hostname 的请求，您将会在服务地图上看到第四个节点，以及您指定的回退名称。
要对所有请求分段使用同一名称，可在初始化消息处理程序时指定应用程序名称，如[上一部分](#xray-sdk-dotnet-messagehandler-globalasax)中所示。这与创建 [https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm) 并将它传递给 `RegisterXRay` 方法的效果相同。
```
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
```
**注意**
您可以使用 `AWS_XRAY_TRACING_NAME` [环境变量](xray-sdk-dotnet-configuration.md#xray-sdk-dotnet-configuration-envvars)覆盖您在代码中定义的默认服务名称。
动态命名策略定义一个主机名应匹配的模式和一个在 HTTP 请求中的主机名与该模式不匹配时要使用的默认名称。要动态命名分段，请创建 [https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm) 并将它传递给 `RegisterXRay` 方法。
```
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
```
# 使用适用于.NET 的 X-Ray SD Amazon K 追踪 SDK 调用
Amazon SDK 客户端
**注意**
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)。
当您的应用程序调用 Amazon Web Services 服务 以存储数据、写入队列或发送通知时，X-Ray SDK for .NET 会按[子分段](xray-sdk-dotnet-subsegments.md)跟踪下游的调用。在这些服务（例如，Amazon S3 存储桶或 Amazon SQS 队列）中追踪的资源 Amazon Web Services 服务 和访问的资源在 X-Ray 控制台的跟踪地图上显示为下游节点。
在创建 适用于 .NET 的 Amazon SDK 客户`RegisterXRayForAllServices`之前，您可以通过致电来检测所有客户。
**Example SampleController.cs-DynamoDB 客户端工具**
```
using Amazon;
using Amazon.Util;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
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.AwsSdk](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AwsSdk.htm);
namespace SampleEBWebApplication.Controllers
{
public class SampleController : ApiController
{
AWSSDKHandler.RegisterXRayForAllServices();
private static readonly Lazy LazyDdbClient = new Lazy(() =>
{
var client = new AmazonDynamoDBClient(EC2InstanceMetadata.Region ?? RegionEndpoint.USEast1);
return client;
});
```
要检测一些服务的客户端而不包括另一些服务的客户端，请调用 `RegisterXRay` 而不是 `RegisterXRayForAllServices`。使用服务客户端接口的名称替换突出显示的文本。
```
AWSSDKHandler.RegisterXRay()
```
对于所有服务，都可以在 X-Ray 控制台中看到调用的 API 的名称。X-Ray 开发工具包会为一部分服务将信息添加到分段，从而在服务地图中提供更高的粒度。
例如，当使用经过检测的 DynamoDB 客户端发出调用时，对于针对表的调用，开发工具包会将表名称添加到分段中。在控制台中，每个表在服务地图中显示为一个独立的节点，以及没有表作为目标的调用的一般 DynamoDB 节点。
**Example 对 DynamoDB 进行调用以保存项目的子分段**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
在您访问指定的资源时，对以下服务的调用会在服务地图中创建额外的节点。没有定向到特定资源的调用，为服务创建了通用节点。
+ **Amazon DynamoDB** - 表名称
+ **Amazon Simple Storage Service** - 存储桶和键名称
+ **Amazon Simple Queue Service** - 队列名称
# 使用适用于 .NET 的 X-Ray 开发工具包跟踪对下游 HTTP Web 服务的调用
传出 HTTP 调用
**注意**
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)。
当您的应用程序调用微服务或公共 HTTP 时 APIs，您可以使用适用于.NET 的 X-Ray SDK 的`GetResponseTraced`扩展方法`System.Net.HttpWebRequest`来检测这些调用，并将该 API 作为下游服务添加到服务图中。
**Example HttpWebRequest**
```
using System.Net;
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.System.Net](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://names.example.com/api");
request.GetResponseTraced();
}
```
对于异步调用，请使用 `GetAsyncResponseTraced`。
```
request.GetAsyncResponseTraced();
```
如果您使用 [https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx](https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx)，请使用 `HttpClientXRayTracingHandler` 委托处理程序来记录调用。
**Example HttpClient**
```
using System.Net.Http;
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.System.Net](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler()));
httpClient.GetAsync(URL);
}
```
在您检测对下游 Web API 的调用时，适用于 .NET 的 X-Ray 开发工具包会使用有关 HTTP 请求和响应的信息记录子分段。X-Ray 使用子分段为 API 生成推断分段。
**Example 下游 HTTP 调用的子分段**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 下游 HTTP 调用的推断分段**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# 使用适用于 .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 查询的收集**
```
```
------
#### [ .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();
}
}
```
# 创建附加子分段
自定义子分段
**注意**
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)。
子分段可为跟踪的[分段](xray-concepts.md#xray-concepts-segments)扩展为了给请求提供服务而已完成的工作的详细信息。每次使用已检测的客户端进行调用时，X-Ray SDK 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。
要管理子分段，请使用 `BeginSubsegment` 和 `EndSubsegment` 方法。在 `try` 代码块的子分段中执行任何任务，使用 `AddException` 跟踪异常。在 `finally` 代码块中调用 `EndSubsegment` 确保结束子分段。
**Example Controller.cs – 自定义子分段**
```
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
try
{
DoWork();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
当您在分段或者其他子分段中创建子分段时，适用于 .NET 的 X-Ray 开发工具包将为其生成 ID 并记录开始时间和结束时间。
**Example 包含元数据的子分段**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# 使用 X-Ray SDK for .NET，将注释和元数据添加到分段
注释和元数据
**注意**
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)。
可以利用注释和元数据记录与请求、环境或应用程序相关的其他信息。可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。
**注释**是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与[筛选表达式](xray-console-filters.md)一起使用。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) API 时使用的数据。
**元数据**是可以具有任何类型值的键-值对，包括对象和列表，但没有编制索引，无法与筛选条件表达式一起使用。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的其他数据。
**Topics**
+ [
## 使用 X-Ray SDK for .NET 记录注释
](#xray-sdk-dotnet-segment-annotations)
+ [
## 使用 X-Ray SDK for .NET 记录元数据
](#xray-sdk-dotnet-segment-metadata)
## 使用 X-Ray SDK for .NET 记录注释
使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。
X-Ray 中的所有注释都需要以下内容：
**注释要求**
+ **键** - X-Ray 注释的键最多可以包含 500 个字母数字字符。除了点或句点（.）之外，不能使用空格或符号
+ **值** - X-Ray 注释的值最多可以包含 1,000 个 Unicode 字符。
+ **注释**的数量 - 每个跟踪最多可使用 50 条注释。
**在 Amazon Lambda 函数之外录制注释**
1. 获取 `AWSXRayRecorder` 的实例。
```
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. 使用字符串键和布尔型、Int32、Int64、双精度或字符串值调用 `addAnnotation`。
```
recorder.AddAnnotation("mykey", "my value");
```
以下示例说明如何使用包含点和布尔值、数字值或字符串值的字符串键调用 `putAnnotation`。
```
document.putAnnotation("testkey.test", "my value");
```
**在 Amazon Lambda 函数内部录制注释**
Lambda 函数中的分段和子分段均由 Lambda 运行时环境管理。如果要在 Lambda 函数中为分段或子分段添加注释，则必须执行以下操作：
1. 在 Lambda 函数中创建分段或子分段。
1. 将注释添加到分段或子分段。
1. 结束分段或子分段。
以下代码示例显示如何在 Lambda 函数中将注释添加到子分段：
```
#Create the subsegment
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
#Add an annotation
AWSXRayRecorder.Instance.AddAnnotation("My", "Annotation");
try
{
YourProcess(); #Your function
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally #End the subsegment
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
X-Ray SDK 将注释以键-值对的形式记录在分段文档的 `annotations` 对象中。使用相同键调用两次 `addAnnotation` 操作将覆盖同一分段或子分段上之前记录的值。
要查找具有带特定值的注释的跟踪，请在`annotation[key]`筛选表达式[中使用 ](xray-console-filters.md) 关键字。
## 使用 X-Ray SDK for .NET 记录元数据
使用元数据可记录有关您无需编制索引即可在搜索中使用的分段或子分段的信息。元数据值可以是字符串、数字、布尔值或可序列化为 JSON 对象或数组的任何其他对象。
**记录元数据**
1. 获取 `AWSXRayRecorder` 的实例，如以下代码示例中所示：
```
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. 使用字符串命名空间、字符串键和对象值调用 `AddMetadata`，如以下代码示例所示：
```
recorder.AddMetadata("my namespace", "my key", "my value");
```
也可以仅使用键和值对来调用 `AddMetadata` 操作，如以下代码示例中所示：
```
recorder.AddMetadata("my key", "my value");
```
如果您没有指定命名空间的值，X-Ray SDK 将使用 `default`。使用相同键调用两次 `AddMetadata` 操作将覆盖同一分段或子分段上之前记录的值。