Developer Guide

AWS X-Ray SDK for .NET

The X-Ray SDK for .NET is a library for C# .NET web applications that provides classes and methods for generating and sending trace data to the X-Ray daemon. Trace data includes information about incoming HTTP requests served by the application, and calls that the application makes to downstream AWS services, HTTP web APIs, and SQL databases. You can also create segments manually and add debug information in annotations and metadata.

Annotations and Metadata

Annotations and metadata are arbitrary text that you add to segments with the X-Ray SDK. Annotations are indexed for use with filter expressions. Metadata are not indexed but can be viewed in the raw segment with the X-Ray console or API. Anyone that you grant read access to X-Ray can view this data.

Download the X-Ray SDK for .NET from NuGet:

Start by adding a TracingMessageHandler to your web configuration to trace incoming requests. The message handler creates a segment to record information about each traced request that your application serves, and completes the segment when the response is sent. Within this segment you can create subsegments to trace downstream calls to other AWS services, HTTP web APIs, and SQL databases.

Next, use the X-Ray SDK for .NET to instrument your AWS SDK for .NET clients. Whenever you make a call to a downstream AWS service or resource with an instrumented client, the SDK records information about the call in a subsegment. AWS services and the resources that you access within the services appear as downstream nodes on the service map to help you identify errors and throttling issues on individual connections.

The X-Ray SDK for .NET also provides instrumentation for downstream calls to HTTP web APIs and SQL databases. The GetResponseTraced extension method for System.Net.HttpWebRequest traces outgoing HTTP calls. You can use the X-Ray SDK for .NET's version of SqlCommand to instrument SQL queries.

For reference documentation about the SDK's classes and methods, see the AWS X-Ray SDK for .NET API Reference.


The X-Ray SDK for .NET requires the .NET framework and AWS SDK for .NET.

Adding the X-Ray SDK for .NET to Your Application

Use NuGet to add the X-Ray SDK for .NET to your application.

To install the X-Ray SDK for .NET with NuGet Package Manager in Visual Studio

  1. Choose Tools, choose NuGet Package Manager, and then choose Manage NuGet Packages for Solution.

  2. Search for AWSXRayRecorder.

  3. Choose the package and then choose Install.