Add guidance for using ActiveScope in an IHttpModule (#31386)

* Add guidance for using ActiveScope in an IHttpModule.

* Fix typo and add code example

Author: brett0000FF

content/en/tracing/trace_collection/custom_instrumentation/dotnet/dd-api.md

@@ -181,6 +181,60 @@ public class ShoppingCartController : Controller
 }
 ```
 
+### Usage with ASP.NET `IHttpModule`
+
+To access the current request span from a custom ASP.NET `IHttpModule`, it is best to read `Tracer.Instance.ActiveScope` in the `PreRequestHandlerExecute` event (or `AcquireRequestState` if you require session state).
+
+While Datadog creates the request span at the start of the ASP.NET pipeline, the execution order of `IHttpModules` is not guaranteed. If your module runs before Datadog's, `ActiveScope` may be `null` during early events like `BeginRequest`. The `PreRequestHandlerExecute` event occurs late enough in the lifecycle to ensure the Datadog module has run and the span is available.
+
+Keep in mind that ActiveScope can still be `null` for requests that are not traced (due to sampling or filtering) or when instrumentation is disabled.
+
+```csharp
+using System;
+using System.Web;
+using Datadog.Trace;
+
+public class MyCustomModule : IHttpModule
+{
+    public void Init(HttpApplication context)
+    {
+        // Prefer reading ActiveScope late in the pipeline
+        context.PreRequestHandlerExecute += OnPreRequestHandlerExecute;
+
+        // If you need session state, you can also hook AcquireRequestState:
+        // context.AcquireRequestState += OnPreRequestHandlerExecute;
+    }
+
+    private void OnPreRequestHandlerExecute(object sender, EventArgs e)
+    {
+        // Earlier events (e.g., BeginRequest) may run before the Datadog module,
+        // so ActiveScope can be null there. Here it should be available.
+        var scope = Tracer.Instance.ActiveScope;
+        if (scope == null)
+        {
+            return; // request not traced (sampling/filters) or instrumentation disabled
+        }
+
+        // Example: add a custom tag
+        scope.Span.SetTag("my.custom.tag", "some_value");
+
+        // SOAP-specific: tag the SOAP action if present
+        if (sender is HttpApplication app)
+        {
+            var soapAction = app.Context?.Request?.Headers["SOAPAction"];
+            if (!string.IsNullOrEmpty(soapAction))
+            {
+                // SOAPAction often includes quotes; trimming keeps it clean
+                scope.Span.SetTag("http.soap_action", soapAction.Trim('"'));
+            }
+        }
+    }
+
+    public void Dispose() { }
+}
+```
+
+
 ### Set errors on a span
 
 To mark errors that occur in your code, use the `Span.SetException(Exception)` method. The method marks the span as an error and adds [related span metadata][5] to provide insight into the exception.