RabbitMQ .NET Client

Use the RabbitMQ.Client.OpenTelemetry library to add OpenTelemetry instrumentation to your RabbitMQ .NET Client applications. This allows you to trace RabbitMQ operations and integrate them with other OpenTelemetry-compatible tools.

To ensure distributed tracing works correctly across service boundaries, you must configure a CompositeTextMapPropagator using TraceContextPropagator and BaggagePropagator to follow the W3C specification for context propagation.

When running the reproduction script, results are categorized into three main outcomes:

1. FAIL: The test failed. The script groups these by reason. A true GH-1968 failure is identified by an OperationCanceledException. If the failure is due to an unrelated error (e.g., ObjectDisposedException), it is not considered a GH-1968 occurrence.
2. slow: The test passed, but its duration exceeded the -SlowSeconds threshold. This is important because Connection.CloseAsync may raise non-abort timeouts up to the InternalConstants.DefaultConnectionCloseTimeout (30s), even if a shorter timeout was requested.
3. PASS: The test completed successfully within the expected time and without errors.

When a RabbitMQ connection is shutting down, the library uses ShutdownEventArgs.CancellationToken to signal to your handlers that the connection is going away.

There are two primary paths for shutdown:

1. Application Path: Triggered by the caller (e.g., calling AbortAsync). The CancellationToken provided by the caller is passed through to the handlers.
2. Library Path: Triggered by the MainLoop (e.g., a dead socket). In this path, the library cancels its internal _mainLoopCts.Token to signal shutdown.

Important: In the Library path, the shutdown token may arrive already-cancelled. Your shutdown cleanup logic must not be gated on this token (e.g., do not use await semaphore.WaitAsync(args.CancellationToken)), as this can cause deadlocks or hangs. Instead, use a bounded wait with CancellationToken.None and manually fault any pending tasks.

When using AsyncEventingBasicConsumer.ReceivedAsync or sub-classing AsyncDefaultBasicConsumer, the ReadOnlyMemory<byte> provided in the message body is owned by the library. This memory is only valid during the execution of the ReceivedAsync event or the HandleBasicDeliverAsync method.

If you need to use the message body outside of these specific methods, you MUST copy the data to a new buffer (e.g., using .ToArray()) to avoid accessing invalid memory.

On net472 (targeting netstandard2.0) on native Windows, the failure is a cold-start race. The abort code path is un-JITted and takes longer to reach SetCloseReason, allowing the MainLoop to win the race. To reproduce this reliably, you must run exactly one iteration per fresh process.

Use the provided PowerShell script repro.ps1 to automate building and running multiple cold iterations.

Usage:

# Run with default settings
.\projects\Applications\GH-1960\repro.ps1

# Run with custom host and iteration count
.\projects\Applications\GH-1960\repro.ps1 -Host_ localhost -Count 50

The GH-1921 cancellation repro is a standalone console application used to reproduce and verify fixes for Windows-specific test failures related to CancellationToken firing during connection opening.

Requirements:

• Must be run on native Windows (WSL will not manifest the specific WSA* socket behaviors).
• A reachable RabbitMQ broker must be available (e.g., a Docker container publishing port 5672 to the Windows host).

Execution: Build and run the application using the dotnet run command, specifying the target framework and the broker hostname as an optional argument.

# Run for .NET 8.0
dotnet run -c Release -f net8.0 -- localhost

# Run for .NET Framework 4.7.2
dotnet run -c Release -f net472 -- localhost

The repro.ps1 script is used to measure the failure rate of Test.Integration.TestConnectionShutdown.TestCleanClosureWithSocketClosedOutOfBand on .NET Framework 4.7.2. This test specifically targets an intermittent OperationCanceledException that occurs during connection shutdown when the frame handler is closed out-of-band.

Requirements:

• Native Windows PowerShell.
• A RabbitMQ broker reachable at localhost:5672.
• If using WSL2, ensure localhost forwarding is configured from the Docker container.

Note on Configuration: Always use -Configuration Debug (the default) when trying to match the CI baseline. The CI integration-win32 job builds in Debug and passes this test. Using Release may trigger unrelated, deterministic failures (like ObjectDisposedException) that mask the intermittent issue being investigated.

To run integration or sequential-integration tests, you must have a RabbitMQ broker running. The CI environment uses a rabbitmq:management container.

To run specific integration tests (e.g., those related to TestCreateConnectionAsync) after setting up your broker, use the following command:

dotnet test projects/Test/Integration/Integration.csproj -c Release \
  --filter "FullyQualifiedName~TestCreateConnectionAsync"

The RabbitMQ .NET client is distributed as a NuGet artifact. You can add it to your project using the NuGet package manager or the dotnet CLI.

To install the package, use the following command:

dotnet add package RabbitMQ.Client