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

# AWS X-Ray 適用於 .NET 的 SDK
<a name="xray-sdk-dotnet"></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 開發套件是用於檢測 C\$1 .NET Web 應用程式、.NET Core Web 應用程式和 .NET Core 函數的程式庫 AWS Lambda。它提供產生追蹤資料並將其傳送至 [X-Ray 協助程式](xray-daemon.md)的類別和方法。這包括應用程式提供的傳入請求，以及應用程式對下游 AWS 服務、HTTP Web APIs和 SQL 資料庫發出的呼叫的相關資訊。

**注意**  
適用於 .NET 的 X-Ray 開發套件是開放原始碼專案。您可以追蹤專案，並在 GitHub 上提交問題與提取請求：[github.com/aws/aws-xray-sdk-dotnet](https://github.com/aws/aws-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 函數的節點。透過新增 SDK，您可以檢測函數程式碼，將子區段新增至 Lambda 記錄的函數區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。

接著，使用適用於 .NET 的 X-Ray 開發套件來[檢測您的 適用於 .NET 的 AWS SDK 用戶端](xray-sdk-dotnet-sdkclients.md)。每當您使用經檢測的用戶端呼叫下游 AWS 服務 或資源時，開發套件會在子區段中記錄有關呼叫的資訊。 AWS 服務和您在服務中存取的資源會在追蹤地圖上顯示為下游節點，以協助您識別錯誤並調節個別連線的問題。

適用於 .NET 的 X-Ray 開發套件也提供對 [HTTP Web APIs](xray-sdk-dotnet-httpclients.md)和 [SQL 資料庫](xray-sdk-dotnet-sqlqueries.md)進行下游呼叫的檢測。適用於 `System.Net.HttpWebRequest` 的 `GetResponseTraced` 延伸方法可追蹤傳出的 HTTP 呼叫。您可以使用適用於 .NET 的 X-Ray 開發套件的 版本`SqlCommand`來檢測 SQL 查詢。

開始使用 SDK 後，請透過[設定記錄器和訊息處理常式來](xray-sdk-dotnet-configuration.md)自訂其行為。您可以新增外掛程式，以記錄執行應用程式所需的運算資源相關資料、定義抽樣規則以自訂抽樣行為，並設定日誌層級以在應用程式日誌中查看更多或更少的軟體開發套件資訊。

使用[註釋與中繼資料](xray-sdk-dotnet-segment.md)，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於[篩選條件表達式](xray-console-filters.md)，因此您可以搜尋包含特定資料的追蹤。中繼資料項目的限制性較低，可以記錄整個物件和陣列，任何可以序列化為 JSON 的項目。

**標註與中繼資料**  
註釋和中繼資料是您使用 X-Ray SDK 新增至客群的任意文字。註釋會編製索引，以便與篩選條件表達式搭配使用。中繼資料不會編製索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授予 X-Ray 讀取存取權的任何人都可以檢視此資料。

當程式碼中有許多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在[自訂子區段](xray-sdk-dotnet-subsegments.md)中，以組織和群組子區段。您可以為整個函數或任何部分的程式碼建立自訂子區段，並記錄子區段上的中繼資料和註釋，而不必寫入父區段上的所有項目。

如需軟體開發套件之類別和方法的參考文件，請參閱以下項目：
+ [AWS X-Ray 適用於 .NET 的 SDK API 參考](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray 適用於 .NET Core API 參考的 SDK](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)

相同套件可同時支援 .NET 和 .NET Core，但使用的類別不同。除非類別是 .NET Core 專屬，否則本章範例都會連結至 .NET API 參考。

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

適用於 .NET 的 X-Ray 開發套件需要 .NET Framework 4.5 或更新版本，以及 適用於 .NET 的 AWS SDK。

若是 .NET Core 應用程式和函數，則軟體開發套件需要 .NET Core 2.0 或更新版本。

## 將適用於 .NET 的 X-Ray 開發套件新增至您的應用程式
<a name="xray-sdk-dotnet-dependencies"></a>

使用 NuGet 將適用於 .NET 的 X-Ray 開發套件新增至您的應用程式。

**在 Visual Studio 中使用 NuGet 套件管理員安裝適用於 .NET 的 X-Ray 開發套件**

1. 選擇 **Tools (工具)**、**NuGet Package Manager (NuGet 套件管理員)**、**Manage NuGet Packages for Solution (管理解決方案的 NuGet 套件)**。

1. 搜尋 **AWSXRayRecorder**。

1. 選擇套件，然後選擇 **Install (安裝)**。

## 相依性管理
<a name="xray-sdk-dotnet-dependencies"></a>

適用於 .NET 的 X-Ray 開發套件可從 [Nuget](https://www.nuget.org/packages/AWSXRayRecorder/) 取得。使用套件管理員安裝 SDK：

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

nuget `AWSXRayRecorder v2.10.1` 套件具有下列相依性：

### 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)的文件。