Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Arbeiten mit .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Es gibt zwei Möglichkeiten, Ihre .NET-Anwendung so zu instrumentieren, dass sie Traces an X-Ray sendet:
+ [AWS Distro for OpenTelemetry .NET](xray-dotnet-opentel-sdk.md) — Eine AWS Distribution, die eine Reihe von Open-Source-Bibliotheken zum Senden korrelierter Metriken und Traces über [AWS Distro](https://aws-otel.github.io/docs/getting-started/collector) for Collector an mehrere AWS Überwachungslösungen wie Amazon CloudWatch und Amazon OpenSearch Service bereitstellt. AWS X-Ray OpenTelemetry
+ [AWS X-Ray SDK for .NET](xray-sdk-dotnet.md) — Eine Reihe von Bibliotheken zum Generieren und Senden von Traces an X-Ray über den [X-Ray-Daemon](xray-daemon.md).
Weitere Informationen finden Sie unter [Wahl zwischen AWS Distro for OpenTelemetry und X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro für .NET OpenTelemetry
Mit der AWS Distro for OpenTelemetry .NET können Sie Ihre Anwendungen einmal instrumentieren und korrelierte Metriken und Traces an mehrere AWS Monitoring-Lösungen wie Amazon CloudWatch AWS X-Ray, und Amazon OpenSearch Service senden. Die Verwendung von X-Ray mit AWS Distro for OpenTelemetry erfordert zwei Komponenten: ein *OpenTelemetry SDK*, das für die Verwendung mit X-Ray aktiviert ist, und das *AWS Distro for OpenTelemetry Collector, das für* die Verwendung mit X-Ray aktiviert ist.
Informationen zu den ersten Schritten finden Sie in der Dokumentation zu [AWS Distro for OpenTelemetry .NET](https://aws-otel.github.io/docs/getting-started/dotnet-sdk).
Weitere Informationen zur Verwendung von AWS Distro for OpenTelemetry with AWS X-Ray und anderen AWS-Services finden Sie unter [AWS Distro for OpenTelemetry oder The [AWS Distro](https://aws-otel.github.io/docs/introduction) for](https://aws-otel.github.io/) Documentation. OpenTelemetry
[Weitere Informationen zur Sprachunterstützung und -verwendung finden Sie unter AWS Observability on. GitHub](https://github.com/aws-observability)
# AWS X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Das X-Ray-SDK SDK for .NET ist eine Bibliothek für die Instrumentierung von C\$1.NET-Webanwendungen, .NET Core-Webanwendungen und .NET Core-Funktionen. AWS Lambda Es bietet Klassen und Methoden zum Generieren und Senden von Trace-Daten an den [X-Ray-Daemon](xray-daemon.md). Dazu gehören Informationen über eingehende Anfragen, die von der Anwendung bedient werden, sowie über Aufrufe, die die Anwendung an Downstream- AWS-Services, HTTP-Web APIs - und SQL-Datenbanken sendet.
**Anmerkung**
Das X-Ray SDK for .NET ist ein Open-Source-Projekt. Du kannst das Projekt verfolgen und Issues und Pull-Requests einreichen auf GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-dotnet)- xray-sdk-dotnet
Für Webanwendungen fügen Sie zunächst [einen Message Handler zu Ihrer Web-Konfiguration hinzu](xray-sdk-dotnet-messagehandler.md), um eingehende Anforderungen zu verfolgen. Der Message Handler erstellt für jede rückverfolgte Anforderung ein [Segment](xray-concepts.md#xray-concepts-segments) und vervollständigt das Segment, nachdem die Antwort gesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist.
Bei Lambda-Funktionen, die von einer instrumentierten Anwendung oder einem Dienst aufgerufen werden, liest Lambda den [Tracing-Header und verfolgt automatisch Sampling-Anfragen](xray-concepts.md#xray-concepts-tracingheader). Für andere Funktionen können Sie [Lambda so konfigurieren](xray-services-lambda.md), dass eingehende Anfragen abgefragt und verfolgt werden. In beiden Fällen erstellt Lambda das Segment und stellt es dem X-Ray SDK zur Verfügung.
**Anmerkung**
Auf Lambda ist das X-Ray SDK optional. Wenn Sie es nicht in Ihrer Funktion verwenden, enthält Ihre Service-Map immer noch einen Knoten für den Lambda-Service und einen für jede Lambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren, um Untersegmente zu dem von Lambda aufgezeichneten Funktionssegment hinzuzufügen. Weitere Informationen finden Sie unter [AWS Lambda und AWS X-Ray](xray-services-lambda.md).
Verwenden Sie als Nächstes das X-Ray SDK for .NET, um [Ihre AWS SDK für .NET Clients zu instrumentieren](xray-sdk-dotnet-sdkclients.md). Immer wenn Sie mit einem instrumentierten Client einen Downstream AWS-Service oder eine Ressource aufrufen, zeichnet das SDK Informationen über den Anruf in einem Untersegment auf. AWS Dienste und die Ressourcen, auf die Sie innerhalb der Dienste zugreifen, werden in der Trace-Map als Downstream-Knoten angezeigt, sodass Sie Fehler und Drosselungsprobleme bei einzelnen Verbindungen leichter identifizieren können.
Das X-Ray SDK for .NET bietet auch Instrumentierung für Downstream-Aufrufe von [HTTP-Web APIs](xray-sdk-dotnet-httpclients.md) - und [SQL-Datenbanken](xray-sdk-dotnet-sqlqueries.md). Die `GetResponseTraced`-Erweiterungsmethode für `System.Net.HttpWebRequest` verfolgt ausgehende HTTP-Aufrufe. Sie können das X-Ray SDK für die Version von .NET verwenden`SqlCommand`, um SQL-Abfragen zu instrumentieren.
Nachdem Sie das SDK verwendet haben, passen Sie sein Verhalten an, indem Sie [den Rekorder und den Message-Handler konfigurieren](xray-sdk-dotnet-configuration.md). Sie können Plugins zum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, um mehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendung ausführt, in [Anmerkungen und Metadaten](xray-sdk-dotnet-segment.md) auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit [Filterausdrücken](xray-console-filters.md) indiziert werden, damit Sie nach Ablaufverfolgen mit bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganze Objekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
**Anmerkungen und Metadaten**
Anmerkungen und Metadaten sind beliebiger Text, den Sie Segmenten mit dem X-Ray SDK hinzufügen. Anmerkungen werden für die Verwendung mit Filterausdrücken indexiert. Metadaten werden nicht indexiert, können aber im Rohsegment mit der X-Ray-Konsole oder API angezeigt werden. Jeder, dem Sie Lesezugriff auf X-Ray gewähren, kann diese Daten einsehen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmente viele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie können Untersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in [benutzerdefinierten Untersegmenten](xray-sdk-dotnet-subsegments.md) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eine ganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegment festhalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter:
+ [AWS X-Ray SDK for .NET für.NET-API-Referenz](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray SDK for .NET Core API-Referenz](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)
Das Paket unterstützt sowohl .NET als auch .NET Core. Die verwendeten Klassen sind jedoch unterschiedlich. Beispiele in diesem Kapitel verweisen auf die .NET API-Referenz, es sei denn, die Klasse ist für .NET Core spezifisch.
## Voraussetzungen
Das X-Ray SDK for .NET benötigt das.NET Framework 4.5 oder höher und AWS SDK für .NET.
Für .NET Core-Anwendungen und -Funktionen erfordert das SDK .NET Core 2.0 oder höher.
## Hinzufügen des X-Ray-SDK SDK for .NET zu Ihrer Anwendung
Verwenden Sie NuGet , um das X-Ray SDK for .NET zu Ihrer Anwendung hinzuzufügen.
**So installieren Sie das X-Ray SDK for .NET mit dem NuGet Paketmanager in Visual Studio**
1. Wählen Sie **Tools**, **NuGet Package Manager, Manage NuGet ** **Packages for Solution**.
1. Suchen Sie nach **AWSXRayRecorder**.
1. Wählen sie das Paket und dann **Installieren**.
## Abhängigkeitsmanagement
Das X-Ray SDK for .NET ist bei [Nuget](https://www.nuget.org/packages/AWSXRayRecorder/) erhältlich. Installieren Sie das SDK mit dem Paketmanager:
```
Install-Package AWSXRayRecorder -Version 2.10.1
```
Das `AWSXRayRecorder v2.10.1` Nuget-Paket hat die folgenden Abhängigkeiten:
### 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)
```
Weitere Informationen zur Abhängigkeitsverwaltung finden Sie in der Dokumentation von Microsoft zu [Nuget-Abhängigkeit und [Nuget-Abhängigkeitsauflösung](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution)](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies).
# Konfiguration des X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Sie können das X-Ray-SDK SDK for .NET mit Plug-ins so konfigurieren, dass es Informationen über den Dienst enthält, auf dem Ihre Anwendung ausgeführt wird, das standardmäßige Sampling-Verhalten ändern oder Sampling-Regeln hinzufügen, die für Anfragen an bestimmte Pfade gelten.
Für .NET-Webanwendungen fügen Sie dem Abschnitt `appSettings` Ihrer `Web.config`-Datei Schlüssel hinzu.
**Example Web.config**
```
```
Erstellen Sie für .NET Core eine Datei mit dem Namen `appsettings.json` mit einem Top-Level-Schlüssel namens `XRay`.
**Example .NET appsettings.json**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin",
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
Erstellen Sie dann in Ihrem Anwendungscode ein Konfigurationsobjekt und verwenden Sie es, um den X-Ray-Recorder zu initialisieren. Führen Sie dies aus, bevor Sie [den Recorder initialisieren](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs).
**Example .NET Core Program.cs — Rekorder-Konfiguration**
```
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);
```
Wenn Sie eine .NET Core-Webanwendung instrumentieren, können Sie bei der Konfiguration des [Message-Handlers auch das Konfigurationsobjekt an die `UseXRay`](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs) Methode übergeben. Verwenden Sie für Lambda-Funktionen die oben gezeigte `InitializeInstance` Methode.
Weitere Informationen zur .NET Core-Konfigurations-API finden [Sie unter Konfigurieren einer ASP.NET-Core-App](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration) auf docs.microsoft.com.
**Topics**
+ [Plugins](#xray-sdk-dotnet-configuration-plugins)
+ [Regeln für die Probenahme](#xray-sdk-dotnet-configuration-sampling)
+ [Protokollierung (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [Protokollierung (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [Umgebungsvariablen](#xray-sdk-dotnet-configuration-envvars)
## Plugins
Verwenden Sie Plugins zum Hinzufügen von Daten über den Service, der Ihre Anwendung hostet.
**Plugins**
+ Amazon EC2 — `EC2Plugin` fügt die Instance-ID, die Availability Zone und die CloudWatch Logs-Gruppe hinzu.
+ Elastic Beanstalk — `ElasticBeanstalkPlugin` fügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.
+ Amazon ECS — `ECSPlugin` fügt die Container-ID hinzu.
Um ein Plugin zu verwenden, konfigurieren Sie das X-Ray-SDK SDK for .NET .NET-Client, indem Sie die `AWSXRayPlugins` Einstellung hinzufügen. Wenn mehrere Plugins auf Ihre Anwendung zutreffen, geben Sie alle Plugins in der gleichen Einstellung an (getrennt durch Kommata).
**Example Web.config – Plugins**
```
```
**Example .NET Core appsettings.json — Plug-ins**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
}
}
```
## Regeln für die Probenahme
Das SDK verwendet die Sampling-Regeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anfragen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen aller Dienste, die Traces an X-Ray senden. [Erstellen Sie zusätzliche Regeln in der X-Ray-Konsole](xray-console-sampling.md), um die Menge der aufgezeichneten Daten für jede Ihrer Anwendungen anzupassen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
**Anmerkung**
Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln abzurufen, kehrt es zu einer lokalen Standardregel zurück, die die erste Anfrage pro Sekunde und fünf Prozent aller zusätzlichen Anfragen pro Host vorsieht. Dies kann passieren, wenn der Host nicht berechtigt ist APIs, Sampling aufzurufen, oder wenn er keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe durch das SDK fungiert.
Sie können das SDK auch so konfigurieren, dass Sampling-Regeln aus einem JSON-Dokument geladen werden. Das SDK kann lokale Regeln als Backup für Fälle verwenden, in denen X-Ray Sampling nicht verfügbar ist, oder ausschließlich lokale Regeln verwenden.
**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
}
}
```
Dieses Beispiel definiert eine benutzerdefinierte Regel und eine Standardregel. Die benutzerdefinierte Regel wendet eine Stichprobenrate von fünf Prozent an, ohne dass eine Mindestanzahl von Anfragen für Pfade verfolgt werden muss. `/api/move/` Die Standardregel verfolgt die erste Anfrage jede Sekunde und 10 Prozent der weiteren Anfragen.
Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Rekorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird die feste Rate vervielfacht, wodurch es schwieriger wird, die Menge der aufgezeichneten Daten zu kontrollieren.
Wenn aktiviert AWS Lambda, können Sie die Samplerate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generierten, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.
Um Backup-Regeln zu konfigurieren, weisen Sie das X-Ray SDK for .NET an, Sampling-Regeln aus einer Datei mit der `SamplingRuleManifest` Einstellung zu laden.
**Example .NET Web.config – Samplingregeln**
```
```
**Example .NET Core appsettings.json — Sampling-Regeln**
```
{
"XRay": {
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
Um nur lokale Regeln zu verwenden, erstellen Sie den Recorder mit einer `LocalizedSamplingStrategy`. Wenn Sie Sicherungsregeln konfiguriert haben, entfernen Sie die Konfiguration.
**Example .NET global.asax — Lokale Sampling-Regeln**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
```
**Example .NET Core Program.cs — Lokale Sampling-Regeln**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);
```
## Protokollierung (.NET)
Das X-Ray-SDK SDK for .NET verwendet denselben Protokollierungsmechanismus wie das [AWS SDK für .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Wenn Sie Ihre Anwendung bereits für die Protokollierung der AWS SDK für .NET Ausgabe konfiguriert haben, gilt dieselbe Konfiguration für die Ausgabe aus dem X-Ray SDK for .NET.
Zum Konfigurieren von Protokollierung fügen Sie einen Konfigurationsabschnitt mit dem Namen `aws` Ihrer `App.config`-Datei oder `Web.config`-Datei hinzu.
**Example Web.config – Protokollierung**
```
...
```
Weitere Informationen finden Sie unter [Konfigurieren Ihrer AWS SDK für .NET -Anwendung](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) im *AWS SDK für .NET -Entwicklerhandbuch*.
## Protokollierung (.NET Core)
Das X-Ray-SDK SDK for .NET verwendet dieselben Protokollierungsoptionen wie das [AWS SDK für .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Um die Protokollierung für .NET Core-Anwendungen zu konfigurieren, übergeben Sie die Protokollierungsoption an die `AWSXRayRecorder.RegisterLogger` Methode.
Um beispielsweise log4net zu verwenden, erstellen Sie eine Konfigurationsdatei, die den Logger, das Ausgabeformat und den Speicherort der Datei definiert.
**Example .NET Core log4net.config**
```
```
Erstellen Sie dann den Logger und übernehmen Sie die Konfiguration in Ihren Programmcode.
**Example .NET Core Program.cs — Protokollierung**
```
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)
{
...
}
}
```
Weitere Informationen zur Konfiguration von log4net finden Sie unter Konfiguration auf [logging.apache.org](https://logging.apache.org/log4net/release/manual/configuration.html).
## Umgebungsvariablen
Sie können Umgebungsvariablen verwenden, um das X-Ray SDK for .NET zu konfigurieren. Das SDK unterstützt die folgenden Variablen.
+ `AWS_XRAY_TRACING_NAME`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den für die [Segmentbenennungsstrategie](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming) des Servlet-Filters festgelegten Dienstnamen.
+ `AWS_XRAY_DAEMON_ADDRESS`— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig verwendet `127.0.0.1:2000` das SDK sowohl Trace-Daten (UDP) als auch Sampling-Daten (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon so konfiguriert haben, dass er [auf einem anderen Port lauscht](xray-daemon-configuration.md) oder wenn er auf einem anderen Host läuft.
**Format**
+ **Derselbe Port** — `address:port`
+ **Verschiedene Anschlüsse** — `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`— Auf einstellen, `RUNTIME_ERROR` um Ausnahmen auszulösen, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, obwohl kein Segment geöffnet ist.
**Zulässige Werte**
+ `RUNTIME_ERROR`— Löst eine Laufzeitausnahme aus.
+ `LOG_ERROR`— Fehler protokollieren und fortfahren (Standard).
+ `IGNORE_ERROR`— Fehler ignorieren und fortfahren.
Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startcode zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread erzeugt.
# Instrumentierung eingehender HTTP-Anfragen mit dem X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Sie können das X-Ray SDK verwenden, um eingehende HTTP-Anfragen zu verfolgen, die Ihre Anwendung auf einer EC2-Instance in Amazon EC2 oder Amazon ECS bearbeitet. AWS Elastic Beanstalk
Verwenden Sie einen Meldungs-Handler, um eingehende HTTP-Anforderungen zu instrumentieren. Wenn Sie den X-Ray-Nachrichtenhandler zu Ihrer Anwendung hinzufügen, erstellt das X-Ray-SDK für.NET für jede gesampelte Anfrage ein Segment. Dieses Segment umfasst Dauer, Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.
**Anmerkung**
Für AWS Lambda Funktionen erstellt Lambda für jede abgetastete Anfrage ein Segment. Weitere Informationen finden Sie unter [AWS Lambda und AWS X-Ray](xray-services-lambda.md).
Jedes Segment hat einen Namen, der Ihre Anwendung in der Service Map identifiziert. Das Segment kann statisch benannt werden, oder Sie können das SDK so konfigurieren, dass es dynamisch auf der Grundlage des Host-Headers in der eingehenden Anfrage benannt wird. Mit der dynamischen Benennung können Sie Traces auf der Grundlage des Domainnamens in der Anfrage gruppieren und einen Standardnamen anwenden, wenn der Name nicht einem erwarteten Muster entspricht (z. B. wenn der Host-Header gefälscht ist).
**Weitergeleitete Anfragen**
Wenn ein Load Balancer oder ein anderer Vermittler eine Anfrage an Ihre Anwendung weiterleitet, nimmt X-Ray die Client-IP aus dem `X-Forwarded-For` Header in der Anfrage und nicht aus der Quell-IP im IP-Paket. Die Client-IP, die für eine weitergeleitete Anfrage aufgezeichnet wird, kann gefälscht sein und sollte daher nicht als vertrauenswürdig eingestuft werden.
Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem `http`-Block, der die folgenden Informationen enthält:
+ **HTTP-Methode** — GET, POST, PUT, DELETE usw.
+ **Client-Adresse** — Die IP-Adresse des Clients, der die Anfrage gesendet hat.
+ **Antwortcode** — Der HTTP-Antwortcode für die abgeschlossene Anfrage.
+ **Timing** — Die Startzeit (als die Anfrage empfangen wurde) und die Endzeit (als die Antwort gesendet wurde).
+ **Benutzeragent** — Der `user-agent` aus der Anfrage.
+ **Länge des Inhalts** — Die Länge `content-length` der Antwort.
**Topics**
+ [Instrumentierung eingehender Anforderungen (.NET)](#xray-sdk-dotnet-messagehandler-globalasax)
+ [Instrumentierung eingehender Anforderungen (.NET Core)](#xray-sdk-dotnet-messagehandler-startupcs)
+ [Konfiguration einer Segmentbenennungsstrategie](#xray-sdk-dotnet-messagehandler-naming)
## Instrumentierung eingehender Anforderungen (.NET)
Um die von Ihrer Anwendung verarbeiteten Anforderungen zu instrumentieren, rufen Sie in der Methode `RegisterXRay` Ihrer `Init`-Datei die Methode `global.asax` auf.
**Example global.asax – Meldungshandler**
```
using System.Web.Http;
using [Amazon.XRay.Recorder.Handlers.AspNet](https://docs.aws.amazon.com/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");
}
}
}
```
## Instrumentierung eingehender Anforderungen (.NET Core)
Um Anfragen zu instrumentieren, die von Ihrer Anwendung bedient werden, rufen Sie die `UseXRay` Methode vor jeder anderen Middleware in der `Configure` Methode Ihrer Startup-Klasse auf, da die X-Ray-Middleware idealerweise die erste Middleware sein sollte, die die Anfrage verarbeitet, und die letzte Middleware, die die Antwort in der Pipeline verarbeitet.
**Anmerkung**
Wenn Sie für .NET Core 2.0 eine `UseExceptionHandler` Methode in der Anwendung haben, stellen Sie sicher, dass Sie nach der Methode aufrufen`UseXRay`, um sicherzustellen, dass Ausnahmen aufgezeichnet werden. `UseExceptionHandler`
**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
...
}
```
Die `UseXRay`-Methode kann außerdem ein [Konfigurationsobjekt](xray-sdk-dotnet-configuration.md) als zweites Argument entgegennehmen.
```
app.UseXRay("MyApp", configuration);
```
## Konfiguration einer Segmentbenennungsstrategie
AWS X-Ray verwendet einen *Dienstnamen*, um Ihre Anwendung zu identifizieren und sie von den anderen Anwendungen, Datenbanken, externen AWS Ressourcen und Ressourcen zu unterscheiden APIs, die Ihre Anwendung verwendet. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den Dienstnamen Ihrer Anwendung im [Namensfeld des Segments auf](xray-api-segmentdocuments.md#api-segmentdocuments-fields).
Das X-Ray SDK kann Segmente nach dem Hostnamen im HTTP-Anforderungsheader benennen. Dieser Header kann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service Map führen kann. Um zu verhindern, dass das SDK Segmente aufgrund von Anfragen mit gefälschten Host-Headern falsch benennt, müssen Sie einen Standardnamen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bearbeitet, können Sie das SDK so konfigurieren, dass es eine dynamische Benennungsstrategie verwendet, um dies in Segmentnamen widerzuspiegeln. Eine dynamische Benennungsstrategie ermöglicht es dem SDK, den Hostnamen für Anfragen zu verwenden, die einem erwarteten Muster entsprechen, und den Standardnamen auf Anfragen anzuwenden, bei denen dies nicht der Fall ist.
Beispielsweise können Sie über eine einzige Anwendung verfügen, die Anfragen an drei Subdomänen — `www.example.com``api.example.com`, und — bedient. `static.example.com` Sie können eine dynamische Benennungsstrategie mit dem Muster verwenden`*.example.com`, um Segmente für jede Subdomain mit einem anderen Namen zu identifizieren, was zu drei Dienstknoten auf der Service-Map führt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen empfängt, der nicht dem Muster entspricht, wird auf der Service Map ein vierter Knoten mit einem von Ihnen angegebenen Fallback-Namen angezeigt.
Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung des Message-Handlers den Namen Ihrer Anwendung, wie [im vorherigen Abschnitt](#xray-sdk-dotnet-messagehandler-globalasax) gezeigt, ein. Dies hat den gleichen Effekt wie das Anlegen einer [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm) und das Übergeben an die `RegisterXRay`-Methode.
```
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
```
**Anmerkung**
Sie können den mit der `AWS_XRAY_TRACING_NAME`-[Umgebungsvariablen](xray-sdk-dotnet-configuration.md#xray-sdk-dotnet-configuration-envvars) in Code definierten standardmäßigen Dienstnamen überschreiben.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesem Muster übereinstimmt. Zur dynamischen Segmentbenennung erstellen Sie eine [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm) und übergeben diese an die `RegisterXRay`-Methode.
```
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
```
# Verfolgen von AWS SDK-Aufrufen mit dem X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Wenn Ihre Anwendung Aufrufe tätigt, um Daten AWS-Services zu speichern, in eine Warteschlange zu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for .NET die Aufrufe im Downstream in [Untersegmenten](xray-sdk-dotnet-subsegments.md). Verfolgte Ressourcen AWS-Services und Ressourcen, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3 S3-Bucket oder eine Amazon SQS SQS-Warteschlange), werden als Downstream-Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt.
Sie können all Ihre AWS SDK für .NET Clients instrumentieren, indem Sie `RegisterXRayForAllServices` sie anrufen, bevor Sie sie erstellen.
**Example SampleController.cs — DynamoDB-Client-Instrumentierung**
```
using Amazon;
using Amazon.Util;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.AwsSdk](https://docs.aws.amazon.com/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;
});
```
Um Clients nur für einige Services zu instrumentieren, rufen Sie `RegisterXRay` statt `RegisterXRayForAllServices` auf. Ersetzen Sie den markierten Text durch den Namen der Client-Schnittstelle des Services.
```
AWSSDKHandler.RegisterXRay()
```
Für alle Dienste können Sie den Namen der aufgerufenen API in der X-Ray-Konsole sehen. Für eine Untergruppe von Diensten fügt das X-Ray SDK dem Segment Informationen hinzu, um die Service Map detaillierter zu gestalten.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client tätigen, fügt das SDK den Tabellennamen dem Segment für Aufrufe hinzu, die auf eine Tabelle abzielen. In der Konsole wird jede Tabelle als separater Knoten in der Service Map angezeigt, mit einem generischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
**Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements**
```
{
"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",
}
}
```
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitere Knoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird ein generischer Knoten für den Service erstellt.
+ **Amazon DynamoDB — Tabellenname**
+ **Amazon Simple Storage Service** — Bucket und Schlüsselname
+ **Amazon Simple Queue Service** — Name der Warteschlange
# Verfolgen von Aufrufen an Downstream-HTTP-Webservices mit dem X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Wenn Ihre Anwendung Microservices oder öffentliches HTTP aufruft APIs, können Sie die `GetResponseTraced` Erweiterungsmethode des X-Ray-SDK für .NET verwenden, `System.Net.HttpWebRequest` um diese Aufrufe zu instrumentieren und die API als Downstream-Service zum Service Graph hinzuzufügen.
**Example HttpWebRequest**
```
using System.Net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/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();
}
```
Für asynchrone Aufrufe verwenden Sie `GetAsyncResponseTraced`.
```
request.GetAsyncResponseTraced();
```
Zeichnen Sie bei der Verwendung von [https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx](https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx) Aufrufe mit dem delegierenden `HttpClientXRayTracingHandler`-Handler auf.
**Example HttpClient**
```
using System.Net.Http;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/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);
}
```
Wenn Sie einen Aufruf einer Downstream-Web-API instrumentieren, zeichnet das X-Ray SDK for .NET ein Untersegment mit Informationen über die HTTP-Anfrage und -Antwort auf. X-Ray verwendet das Untersegment, um ein abgeleitetes Segment für die API zu generieren.
**Example Untersegment für einen nachgelagerten HTTP-Aufruf**
```
{
"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 Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf**
```
{
"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
}
```
# Verfolgen von SQL-Abfragen mit dem X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Das X-Ray-SDK SDK for .NET bietet eine Wrapper-Klasse für `System.Data.SqlClient.SqlCommand``TraceableSqlCommand`, named, die Sie anstelle von `SqlCommand` verwenden können. Sie können einen SQL-Befehl mit der Klasse `TraceableSqlCommand` initialisieren.
## Ablaufverfolgung von SQL-Abfragen mit synchronen und asynchronen Methoden
Die folgenden Beispiele zeigen, wie Sie SQL Server-Abfragen mit `TraceableSqlCommand` automatisch synchron und asynchron verfolgen.
**Example `Controller.cs` – SQL-Client-Instrumentierung (synchron)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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();
}
}
```
Sie können die Abfrage mithilfe der `ExecuteReaderAsync`-Methode asynchron ausführen.
**Example `Controller.cs` – SQL-Client-Instrumentierung (asynchron)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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();
}
}
```
## Erfassen von SQL-Abfragen an SQL Server
Sie können die Erfassung von `SqlCommand.CommandText` als Teil des Untersegments aktivieren, das von Ihrer SQL-Abfrage erstellt wurde. `SqlCommand.CommandText` wird als Feld `sanitized_query` im JSON-Untersegment angezeigt. Standardmäßig ist diese Funktion aus Sicherheitsgründen deaktiviert.
**Anmerkung**
Aktivieren Sie die Sammlungsfunktion nicht, wenn Sie sensible Informationen als Klartext in Ihre SQL-Abfragen einfügen.
Sie können die Sammlung von SQL-Abfragen auf zwei Arten aktivieren:
+ Legen Sie die Eigenschaft `CollectSqlQueries` in der globalen Konfiguration für Ihre Anwendung auf `true` fest.
+ Legen Sie den Parameter `collectSqlQueries` in der Instance `TraceableSqlCommand` auf `true` fest, um Aufrufe innerhalb der Instance zu erfassen.
### Aktivieren Sie die globale Eigenschaft CollectSqlQueries
Die folgenden Beispiele zeigen, wie Sie die Eigenschaft `CollectSqlQueries` für .NET und .NET Core aktivieren.
------
#### [ .NET ]
Um die Eigenschaft `CollectSqlQueries` in der globalen Konfiguration Ihrer Anwendung in .NET auf `true` festzulegen, ändern Sie die `appsettings` Ihrer `App.config`- oder `Web.config`-Datei wie dargestellt.
**Example `App.config`Oder `Web.config` — Aktiviert die Erfassung von SQL-Abfragen global**
```
```
------
#### [ .NET Core ]
Um die `CollectSqlQueries` Eigenschaft `true` in der globalen Konfiguration Ihrer Anwendung in .NET Core auf zu setzen, ändern Sie Ihre `appsettings.json` Datei unter dem X-Ray-Schlüssel, wie hier gezeigt.
**Example `appsettings.json`— Aktiviert die Erfassung von SQL-Abfragen global**
```
{
"XRay": {
"CollectSqlQueries":"true"
}
}
```
------
### Aktivieren Sie den collectSqlQueries Parameter
Sie können den Parameter `collectSqlQueries` in der Instance `TraceableSqlCommand` auf `true` setzen, um den SQL-Abfragetext für SQL Server-Abfragen zu erfassen, die mit dieser Instance durchgeführt wurden. Wenn Sie den Parameter auf `false` setzen, wird die Funktion `CollectSqlQuery` für die Instance `TraceableSqlCommand` deaktiviert.
**Anmerkung**
Der Wert von `collectSqlQueries` in der Instance `TraceableSqlCommand` überschreibt den in der globalen Konfiguration der Eigenschaft `CollectSqlQueries` festgelegten Wert.
**Example Beispiel `Controller.cs` — Aktivieren Sie die Erfassung von SQL-Abfragen für die Instanz**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/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();
}
}
```
# Erstellen zusätzlicher Untersegmente
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Untersegmente erweitern das [Segment](xray-concepts.md#xray-concepts-segments) eines Traces um Details über die Arbeit, die zur Bearbeitung einer Anfrage geleistet wurde. Jedes Mal, wenn Sie einen Anruf mit einem instrumentierten Client tätigen, zeichnet das X-Ray-SDK die in einem Untersegment generierten Informationen auf. Sie können zusätzliche Untersegmente erstellen, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zu messen oder Anmerkungen und Metadaten aufzuzeichnen.
Um Untersegmente zu verwalten, verwenden Sie die Methoden `BeginSubsegment` und `EndSubsegment`. Führen Sie die gewünschte Bearbeitung im Untersegment in einem `try`-Block aus und verwenden Sie `AddException`, um Ausnahmen zu verfolgen. Rufen Sie `EndSubsegment` in einem `finally`-Block auf, um sicherzustellen, dass das Untersegment geschlossen ist.
**Example Controller.cs — Benutzerdefiniertes Untersegment**
```
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
try
{
DoWork();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
Wenn Sie ein Untersegment innerhalb eines Segments oder eines anderen Untersegments erstellen, generiert das X-Ray SDK for .NET eine ID dafür und zeichnet die Start- und Endzeit auf.
**Example Untersegment mit Metadaten**
```
"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"
}
},
```
# Hinzufügen von Anmerkungen und Metadaten zu Segmenten mit dem X-Ray SDK for .NET
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Sie können zusätzliche Informationen über Anfragen, die Umgebung oder Ihre Anwendung mit Anmerkungen und Metadaten aufzeichnen. Sie können Anmerkungen und Metadaten zu den Segmenten hinzufügen, die das X-Ray SDK erstellt, oder zu benutzerdefinierten Untersegmenten, die Sie erstellen.
**Anmerkungen** sind Schlüssel-Wert-Paare mit Zeichenfolgen-, Zahlen- oder booleschen Werten. [Anmerkungen sind für die Verwendung mit Filterausdrücken indexiert.](xray-console-filters.md) Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in der Konsole zu verwenden, oder wenn Sie die [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)-API aufrufen.
**Metadaten** sind Schlüssel-Wert-Paare, die Werte beliebigen Typs enthalten können, einschließlich Objekte und Listen, aber nicht für die Verwendung mit Filterausdrücken indexiert sind. Verwenden Sie Metadaten, um zusätzliche Daten aufzuzeichnen, die Sie im Trace speichern möchten, aber nicht für die Suche verwenden müssen.
**Topics**
+ [Anmerkungen mit dem X-Ray SDK for .NET aufnehmen](#xray-sdk-dotnet-segment-annotations)
+ [Metadaten mit dem X-Ray SDK for .NET aufzeichnen](#xray-sdk-dotnet-segment-metadata)
## Anmerkungen mit dem X-Ray SDK for .NET aufnehmen
Verwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Suche indiziert werden sollten, aufzuzeichnen.
Folgendes ist für alle Anmerkungen in X-Ray erforderlich:
**Anmerkung zu Anforderungen**
+ **Schlüssel** — Der Schlüssel für eine X-Ray-Anmerkung kann bis zu 500 alphanumerische Zeichen enthalten. Sie können keine anderen Leerzeichen oder Symbole als einen Punkt oder Punkt (.) verwenden
+ **Werte** — Der Wert für eine X-Ray-Anmerkung kann bis zu 1.000 Unicode-Zeichen enthalten.
+ Die Anzahl der **Anmerkungen** — Sie können bis zu 50 Anmerkungen pro Spur verwenden.
**Um Anmerkungen außerhalb einer Funktion aufzuzeichnen AWS Lambda**
1. Rufen Sie eine Instance von `AWSXRayRecorder` ab.
```
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. Rufen Sie `addAnnotation` mit einem Zeichenfolgenschlüssel und einem booleschen, Int32-, Int64-, Double- oder Zeichenfolgenwert auf.
```
recorder.AddAnnotation("mykey", "my value");
```
Das folgende Beispiel zeigt, wie Sie `putAnnotation` mit einem String-Schlüssel aufrufen, der einen Punkt und einen booleschen Wert, eine Zahl oder einen String-Wert enthält.
```
document.putAnnotation("testkey.test", "my value");
```
**Um Anmerkungen innerhalb einer Funktion aufzuzeichnen AWS Lambda**
Sowohl Segmente als auch Untersegmente innerhalb einer Lambda-Funktion werden von der Lambda-Laufzeitumgebung verwaltet. Wenn Sie einem Segment oder Untersegment innerhalb einer Lambda-Funktion eine Anmerkung hinzufügen möchten, müssen Sie wie folgt vorgehen:
1. Erstellen Sie das Segment oder Untersegment in der Lambda-Funktion.
1. Fügen Sie die Anmerkung dem Segment oder Untersegment hinzu.
1. Beenden Sie das Segment oder Untersegment.
Das folgende Codebeispiel zeigt Ihnen, wie Sie einem Untersegment innerhalb einer Lambda-Funktion eine Anmerkung hinzufügen:
```
#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();
}
```
Das X-Ray SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem `annotations` Objekt im Segmentdokument auf. Durch `addAnnotation` zweimaliges Aufrufen der Operation mit demselben Schlüssel wird ein zuvor aufgezeichneter Wert für dasselbe Segment oder Untersegment überschrieben.
Nutzen Sie das `annotation[key]`-Schlüsselwort in einem [Filterausdruck](xray-console-filters.md), um Ablaufverfolgungen durch Anmerkungen mit bestimmten Werten zu finden.
## Metadaten mit dem X-Ray SDK for .NET aufzeichnen
Verwenden Sie Metadaten, um Informationen zu Segmenten oder Untersegmenten aufzuzeichnen, die Sie für die Verwendung in einer Suche nicht indizieren müssen. Bei Metadatenwerten kann es sich um Zeichenketten, Zahlen, Boolesche Werte oder jedes andere Objekt handeln, das in ein JSON-Objekt oder -Array serialisiert werden kann.
**So zeichnen Sie Metadaten auf**
1. Rufen Sie eine Instanz von ab`AWSXRayRecorder`, wie im folgenden Codebeispiel gezeigt:
```
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. Rufen Sie `AddMetadata` mit einem Zeichenfolgen-Namespace, einem Zeichenkettenschlüssel und einem Objektwert auf, wie im folgenden Codebeispiel gezeigt:
```
recorder.AddMetadata("my namespace", "my key", "my value");
```
Sie können den `AddMetadata` Vorgang auch nur mit einem Schlüssel- und Wertepaar aufrufen, wie im folgenden Codebeispiel gezeigt:
```
recorder.AddMetadata("my key", "my value");
```
Wenn Sie keinen Wert für den Namespace angeben, verwendet `default` das X-Ray SDK. Wenn Sie den `AddMetadata` Vorgang zweimal mit demselben Schlüssel aufrufen, wird ein zuvor aufgezeichneter Wert für dasselbe Segment oder Untersegment überschrieben.