Tracing docs for .NET

proposed-docs-for-sentry-docs/README.md

@@ -0,0 +1,31 @@
+# Proposed Documentation Changes for getsentry/sentry-docs
+
+These files are intended to be applied to the [getsentry/sentry-docs](https://github.com/getsentry/sentry-docs) repository.
+The file paths mirror the sentry-docs repo structure. Once the changes are applied to sentry-docs, this directory should be removed from sentry-dotnet.
+
+## Context
+
+Fixes https://github.com/getsentry/sentry-dotnet/issues/4898
+
+The distributed tracing "how-to-use" docs for .NET were showing ASP.NET Framework-specific
+content (`Application_BeginRequest`) on all .NET guide pages, including ASP.NET Core and
+Blazor WebAssembly — which was incorrect.
+
+## Changes
+
+### Modified
+- `platform-includes/distributed-tracing/how-to-use/dotnet.mdx` — Updated generic .NET
+  fallback to focus on `SentryHttpMessageHandler` usage and DI-based auto-registration.
+
+### New Files
+- `platform-includes/distributed-tracing/how-to-use/dotnet.aspnetcore.mdx` — ASP.NET Core
+  guide explaining automatic middleware trace extraction and `IHttpClientFactory` integration.
+- `platform-includes/distributed-tracing/how-to-use/dotnet.blazor-webassembly.mdx` — Blazor
+  WASM guide showing how to configure `SentryHttpMessageHandler` with `HttpClient`.
+- `platform-includes/distributed-tracing/how-to-use/dotnet.aspnet.mdx` — Preserves the old
+  ASP.NET Framework content for the correct guide page.
+- `platform-includes/distributed-tracing/how-to-use/dotnet.azure-functions-worker.mdx` —
+  Azure Functions Worker guide.
+
+All includes also document the `TracePropagationTargets` option for controlling where
+trace headers are sent.

proposed-docs-for-sentry-docs/platform-includes/distributed-tracing/how-to-use/dotnet.aspnet.mdx

@@ -0,0 +1,31 @@
+When using ASP.NET (classic), you need to call `StartOrContinueTrace()` in your `Application_BeginRequest` method so that Sentry can extract incoming trace headers and continue distributed traces:
+
+```csharp
+protected void Application_BeginRequest()
+{
+    Context.StartOrContinueTrace();
+}
+```
+
+### Outgoing HTTP Requests
+
+For outgoing HTTP requests, use `SentryHttpMessageHandler` when creating your `HttpClient` to automatically propagate trace headers:
+
+```csharp
+var httpClient = new HttpClient(new SentryHttpMessageHandler());
+```
+
+The `SentryHttpMessageHandler` will automatically attach `sentry-trace` and `baggage` headers to all outgoing requests.
+
+### Controlling Where Headers Are Sent
+
+By default, tracing headers are attached to all outgoing HTTP requests. Use the `TracePropagationTargets` option to restrict which URLs receive tracing headers:
+
+```csharp
+options.TracePropagationTargets = [
+    "https://myapi.example.com",
+    "https://.*\\.mycompany\\.com"
+];
+```
+
+If `TracePropagationTargets` is configured, only requests whose URL matches one of the entries will have headers attached.

proposed-docs-for-sentry-docs/platform-includes/distributed-tracing/how-to-use/dotnet.aspnetcore.mdx

@@ -0,0 +1,37 @@
+If you use the current version of our .NET SDK, distributed tracing works automatically in ASP.NET Core applications without additional configuration.
+
+### Incoming Requests
+
+The Sentry middleware automatically extracts `sentry-trace` and `baggage` headers from incoming HTTP requests to continue traces started by upstream services (such as a frontend application using the Sentry JavaScript SDK).
+
+### Outgoing HTTP Requests
+
+When using `IHttpClientFactory` (the [recommended approach](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for managing `HttpClient` in ASP.NET Core), the SDK automatically registers `SentryHttpMessageHandler` with the factory. This means all `HttpClient` instances created through dependency injection will automatically:
+
+- Attach `sentry-trace` and `baggage` headers to outgoing requests
+- Create spans for outgoing HTTP requests when tracing is enabled
+
+No additional setup is needed if your application already uses `IHttpClientFactory` or calls `services.AddHttpClient()`.
+
+If you create `HttpClient` instances manually (without the factory), you need to pass `SentryHttpMessageHandler` yourself:
+
+```csharp
+var httpClient = new HttpClient(new SentryHttpMessageHandler());
+```
+
+### Controlling Where Headers Are Sent
+
+By default, tracing headers are attached to all outgoing HTTP requests. Use the `TracePropagationTargets` option to restrict which URLs receive tracing headers:
+
+```csharp
+builder.WebHost.UseSentry(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.TracePropagationTargets = [
+        "https://myapi.example.com",
+        "https://.*\\.mycompany\\.com"
+    ];
+});
+```
+
+If `TracePropagationTargets` is configured, only requests whose URL matches one of the entries will have headers attached.

proposed-docs-for-sentry-docs/platform-includes/distributed-tracing/how-to-use/dotnet.azure-functions-worker.mdx

@@ -0,0 +1,13 @@
+If you use the current version of our .NET SDK, distributed tracing works automatically in Azure Functions Worker applications without additional configuration.
+
+The Sentry integration automatically extracts `sentry-trace` and `baggage` headers from incoming HTTP trigger requests to continue traces started by upstream services.
+
+### Outgoing HTTP Requests
+
+For outgoing HTTP requests, use `SentryHttpMessageHandler` when creating your `HttpClient` to automatically propagate trace headers:
+
+```csharp
+var httpClient = new HttpClient(new SentryHttpMessageHandler());
+```
+
+If you register `HttpClient` through dependency injection using `IHttpClientFactory`, the `SentryHttpMessageHandler` is automatically added — no additional setup is needed.

proposed-docs-for-sentry-docs/platform-includes/distributed-tracing/how-to-use/dotnet.blazor-webassembly.mdx

@@ -0,0 +1,44 @@
+Blazor WebAssembly applications run in the browser and typically communicate with backend services via HTTP. To enable distributed tracing for these outgoing requests, use `SentryHttpMessageHandler` when creating your `HttpClient`:
+
+```csharp
+var builder = WebAssemblyHostBuilder.CreateDefault(args);
+builder.UseSentry(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.TracesSampleRate = 1.0;
+});
+
+builder.Services.AddScoped(_ =>
+    new HttpClient(new SentryHttpMessageHandler())
+    {
+        BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
+    });
+
+await builder.Build().RunAsync();
+```
+
+The `SentryHttpMessageHandler` will automatically attach `sentry-trace` and `baggage` headers to outgoing requests, connecting your Blazor frontend to backend services that also use Sentry.
+
+### Controlling Where Headers Are Sent
+
+By default, tracing headers are attached to all outgoing HTTP requests. If your Blazor WebAssembly application communicates with third-party APIs, you may want to restrict which URLs receive tracing headers using the `TracePropagationTargets` option:
+
+```csharp
+builder.UseSentry(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.TracesSampleRate = 1.0;
+    options.TracePropagationTargets = [
+        "https://myapi.example.com",
+        "https://.*\\.mycompany\\.com"
+    ];
+});
+```
+
+If `TracePropagationTargets` is configured, only requests whose URL matches one of the entries will have headers attached.
+
+<Alert>
+
+If your backend is on a different origin than your Blazor app, make sure the `sentry-trace` and `baggage` headers are included in your backend's CORS allowlist.
+
+</Alert>

proposed-docs-for-sentry-docs/platform-includes/distributed-tracing/how-to-use/dotnet.mdx

@@ -0,0 +1,22 @@
+If you use a Sentry .NET SDK that integrates via dependency injection (`Sentry.AspNetCore`, `Sentry.Maui`, `Sentry.Extensions.Logging`, and so on), distributed tracing for outgoing HTTP requests works automatically when using `IHttpClientFactory`. The SDK registers `SentryHttpMessageHandler` with the factory, which attaches `sentry-trace` and `baggage` headers to all outgoing requests.
+
+For manually created `HttpClient` instances, you need to pass `SentryHttpMessageHandler` yourself:
+
+```csharp
+var httpClient = new HttpClient(new SentryHttpMessageHandler());
+```
+
+The `SentryHttpMessageHandler` will automatically attach `sentry-trace` and `baggage` headers to outgoing requests, connecting your service to downstream services that also use Sentry.
+
+### Controlling Where Headers Are Sent
+
+By default, tracing headers are attached to all outgoing HTTP requests. Use the `TracePropagationTargets` option to restrict which URLs receive tracing headers. This accepts a list of substrings or regular expressions:
+
+```csharp
+options.TracePropagationTargets = [
+    "https://myapi.example.com",
+    "https://.*\\.mycompany\\.com"
+];
+```
+
+If `TracePropagationTargets` is configured, only requests whose URL matches one of the entries will have headers attached.