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

# 設定適用於 .NET 的 X-Ray 開發套件
<a name="xray-sdk-dotnet-configuration"></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 開發套件，以包含應用程式執行服務的相關資訊、修改預設抽樣行為，或新增適用於特定路徑請求的抽樣規則。

針對 .NET web 應用程式，請將鍵新增至您 `Web.config` 檔案中的 `appSettings` 區段。

**Example Web.config**  

```
<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin"/>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>
```

針對 .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.aws.amazon.com/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 的詳細資訊，請參閱[在 ASP.NET 上設定 Core 應用程式](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration)。 docs.microsoft.com

**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)

## 外掛程式
<a name="xray-sdk-dotnet-configuration-plugins"></a>

使用外掛程式來新增託管您應用程式的服務相關資料。

**外掛程式**
+ Amazon EC2 – `EC2Plugin` 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。
+ Elastic Beanstalk – `ElasticBeanstalkPlugin` 新增環境名稱、版本標籤和部署 ID。
+ Amazon ECS – `ECSPlugin` 新增容器 ID。

若要使用外掛程式，請新增 `AWSXRayPlugins`設定來設定適用於 .NET 用戶端的 X-Ray 開發套件。若要將多個外掛程式套用至您的應用程式，請在相同設定中指定它們，並以逗號分隔。

**Example Web.config - 外掛程式**  

```
<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/>
  </appSettings>
</configuration>
```

**Example .NET Core appsettings.json – 外掛程式**  

```
{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
  }
}
```

## 抽樣規則
<a name="xray-sdk-dotnet-configuration-sampling"></a>

SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。預設規則每秒追蹤第一個請求，以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。[在 X-Ray 主控台中建立其他規則](xray-console-sampling.md)，以自訂為每個應用程式記錄的資料量。

軟體開發套件會依定義自訂規則的順序套用自訂規則。如果請求符合多個自訂規則，軟體開發套件只會套用第一個規則。

**注意**  
如果開發套件無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可，或無法連線至 X-Ray 協助程式，該常駐程式可作為 SDK 進行 API 呼叫的 TCP 代理，就會發生這種情況。

您也可以設定 SDK 從 JSON 文件載入抽樣規則。對於無法使用 X-Ray 取樣的情況，軟體開發套件可以使用本機規則作為備份，或僅使用本機規則。

**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
  }
}
```

此範例定義了一個自訂規則和預設規則。自訂規則會套用 5% 的取樣率，沒有追蹤 下路徑的最低請求數`/api/move/`。預設規則會追蹤每秒的第一個請求和 10% 的額外請求。

在本機定義規則的缺點是，固定目標是由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。

開啟時 AWS Lambda，您無法修改取樣率。如果您的函數是由 檢測服務呼叫，則 Lambda 將記錄產生該服務取樣之請求的呼叫。如果啟用主動追蹤且不存在追蹤標頭，Lambda 會做出抽樣決策。

若要設定備份規則，請指示適用於 .NET 的 X-Ray 開發套件使用 `SamplingRuleManifest`設定從 檔案載入取樣規則。

**Example .NET Web.config - 抽樣規則**  

```
<configuration>
  <appSettings>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>
```

**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)
<a name="xray-sdk-dotnet-configuration-logging"></a>

適用於 .NET 的 X-Ray 開發套件使用與 相同的記錄機制[適用於 .NET 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)。如果您已將應用程式設定為記錄 適用於 .NET 的 AWS SDK 輸出，則相同的組態會套用至適用於 .NET 的 X-Ray 開發套件輸出。

若要設定記錄日誌，請將名為 `aws` 的組態區段新增至您的 `App.config` 檔案或 `Web.config` 檔案。

**Example Web.config - 記錄**  

```
...
<configuration>
  <configSections>
    <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/>
  </configSections>
  <aws>
    <logging logTo="Log4Net"/>
  </aws>
</configuration>
```

如需詳細資訊，請參閱《 *適用於 .NET 的 AWS SDK 開發人員指南*》中的[設定您的 適用於 .NET 的 AWS SDK 應用程式](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html)。

## 記錄日誌 (.NET Core)
<a name="xray-sdk-dotnet-configuration-corelogging"></a>

適用於 .NET 的 X-Ray 開發套件使用與 相同的記錄選項[適用於 .NET 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)。若要設定 .NET Core 應用程式的記錄，請將記錄選項傳遞至 `AWSXRayRecorder.RegisterLogger`方法。

例如，若要使用 log4net，請建立定義記錄器、輸出格式及檔案位置的組態檔。

**Example .NET Core log4net.config**  

```
<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net">
    <file value="{{c:\logs\sdk-log.txt}}" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="{{%date [%thread] %level %logger - %message%newline}}" />
    </layout>
  </appender>
  <logger name="Amazon">
    <level value="DEBUG" />
    <appender-ref ref="FileAppender" />
  </logger>
</log4net>
```

然後建立記錄器並在您的程式程式碼中套用組態。

**Example .NET Core Program.cs – 記錄**  

```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/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 的詳細資訊，請參閱 https：//logging.apache.org 上的[組態](https://logging.apache.org/log4net/release/manual/configuration.html)。

## 環境變數
<a name="xray-sdk-dotnet-configuration-envvars"></a>

您可以使用環境變數來設定適用於 .NET 的 X-Ray 開發套件。軟體開發套件支援以下變數。
+ `AWS_XRAY_TRACING_NAME` – 設定 SDK 用於區段的服務名稱。覆寫您在 servlet 篩選條件的[區段命名策略](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming)中設定的服務名稱。
+ `AWS_XRAY_DAEMON_ADDRESS` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會使用 `127.0.0.1:2000` 進行追蹤資料 (UDP) 和取樣 (TCP)。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。

**格式**
  + **相同連接埠** – `{{address}}:{{port}}`
  + **不同的連接埠** – `tcp:{{address}}:{{port}} udp:{{address}}:{{port}}`
+ `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。

**有效值**
  + `RUNTIME_ERROR` – 擲回執行時間例外狀況。
  + `LOG_ERROR` – 記錄錯誤並繼續 （預設）。
  + `IGNORE_ERROR` – 忽略錯誤並繼續。

  當您嘗試在未開啟請求時執行的啟動程式碼中使用經檢測的用戶端，或在產生新執行緒的程式碼中，可能會發生與缺少區段或子區段相關的錯誤。