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

# 使用適用於 .NET 的 X-Ray 開發套件將註釋和中繼資料新增至區段
<a name="xray-sdk-dotnet-segment"></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)。

您可以使用註釋和中繼資料記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray 開發套件建立的區段，或新增至您建立的自訂子區段。

**註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。

**中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。

**Topics**
+ [使用適用於 .NET 的 X-Ray 開發套件記錄註釋](#xray-sdk-dotnet-segment-annotations)
+ [使用適用於 .NET 的 X-Ray 開發套件記錄中繼資料](#xray-sdk-dotnet-segment-metadata)

## 使用適用於 .NET 的 X-Ray 開發套件記錄註釋
<a name="xray-sdk-dotnet-segment-annotations"></a>

針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。

以下是 X-Ray 中所有註釋的必要項目：

**註釋要求**
+ **金鑰** – X-Ray 註釋的金鑰最多可有 500 個英數字元。您不能使用點或句點以外的空格或符號 ( 。 )
+ **值** – X-Ray 註釋的值最多可有 1，000 個 Unicode 字元。
+ **註釋**數量 – 每個追蹤最多可以使用 50 個註釋。

**記錄 AWS Lambda 函數外部的註釋**

1. 取得 `AWSXRayRecorder` 的執行個體。

   ```
   using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/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");
   ```

**在 AWS 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`操作兩次會覆寫先前在相同區段或子區段上記錄的值。

若要尋找具有具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。

## 使用適用於 .NET 的 X-Ray 開發套件記錄中繼資料
<a name="xray-sdk-dotnet-segment-metadata"></a>

使用中繼資料記錄您不需要編製索引以在搜尋中使用的區段或子區段資訊。中繼資料值可以是字串、數字、布林值，或任何其他可序列化為 JSON 物件或陣列的物件。

**記錄中繼資料**

1. 取得 執行個體`AWSXRayRecorder`，如下列程式碼範例所示：

   ```
   using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/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 開發套件會使用 `default`。使用相同索引鍵呼叫`AddMetadata`操作兩次會覆寫先前在相同區段或子區段上記錄的值。