Azure · Eldert Grootenboer (EldertGrootenboer) · Aug 14, 2026 · Jun 18, 2026 · Jun 18, 2026 · Jun 19, 2026
@@ -5,6 +5,7 @@
 ### Features Added
 
 - Added `GetMessageSessionsAsync` overloads on `ServiceBusClient` for queues and subscriptions. The no-filter overload returns the IDs of sessions that have active messages or session state, and the `sessionStateUpdatedAfter` overload returns session IDs whose session state was updated after the specified timestamp. Implements the `com.microsoft:get-message-sessions` AMQP management operation. ([#58761](https://github.com/Azure/azure-sdk-for-net/pull/58761))
+- Added opt-in support for non-exclusive session locking on `ServiceBusSessionReceiver`, allowing a session to be cooperatively taken over by another receiver. Set `ServiceBusSessionReceiverOptions.EnableNonExclusiveSession` to accept a session non-exclusively, then read the token from `ServiceBusSessionReceiver.SessionLockToken` and pass it as `ServiceBusSessionReceiverOptions.SessionLockToken = Guid.Parse(token)` to take that session over. `ServiceBusSessionReceiver.IsSessionExclusive` reports the mode the session was established under. Dispositions for a non-exclusive session are routed over the management link so that settlement keeps working across a takeover, which lowers settlement throughput compared to an exclusive session. This applies to `ServiceBusSessionReceiver` only; `ServiceBusSessionProcessor` continues to lock sessions exclusively. Accepting a session with `EnableNonExclusiveSession` set throws `NotSupportedException` when the endpoint declines it, either by refusing the request outright or by accepting it without assigning a lock token, which is how a caller detects whether the feature is available for a namespace. An endpoint that declines in some other way surfaces the exception its own error maps to. ([#60060](https://github.com/Azure/azure-sdk-for-net/pull/60060))
 
 ### Breaking Changes
 

@@ -499,18 +499,22 @@ public partial class ServiceBusSessionReceiver : Azure.Messaging.ServiceBus.Serv
     {
         protected ServiceBusSessionReceiver() { }
         public override bool IsClosed { get { throw null; } }
+        public virtual bool IsSessionExclusive { get { throw null; } }
         public virtual string SessionId { get { throw null; } }
         public virtual System.DateTimeOffset SessionLockedUntil { get { throw null; } }
+        public virtual string SessionLockToken { get { throw null; } }
         public virtual System.Threading.Tasks.Task<System.BinaryData> GetSessionStateAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task RenewSessionLockAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task SetSessionStateAsync(System.BinaryData sessionState, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class ServiceBusSessionReceiverOptions
     {
         public ServiceBusSessionReceiverOptions() { }
+        public bool EnableNonExclusiveSession { get { throw null; } set { } }
         public string Identifier { get { throw null; } set { } }
         public int PrefetchCount { get { throw null; } set { } }
         public Azure.Messaging.ServiceBus.ServiceBusReceiveMode ReceiveMode { get { throw null; } set { } }
+        public System.Guid? SessionLockToken { get { throw null; } set { } }
         public override bool Equals(object obj) { throw null; }
         public override int GetHashCode() { throw null; }
         public override string ToString() { throw null; }

@@ -499,18 +499,22 @@ public partial class ServiceBusSessionReceiver : Azure.Messaging.ServiceBus.Serv
     {
         protected ServiceBusSessionReceiver() { }
         public override bool IsClosed { get { throw null; } }
+        public virtual bool IsSessionExclusive { get { throw null; } }
         public virtual string SessionId { get { throw null; } }
         public virtual System.DateTimeOffset SessionLockedUntil { get { throw null; } }
+        public virtual string SessionLockToken { get { throw null; } }
         public virtual System.Threading.Tasks.Task<System.BinaryData> GetSessionStateAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task RenewSessionLockAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task SetSessionStateAsync(System.BinaryData sessionState, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class ServiceBusSessionReceiverOptions
     {
         public ServiceBusSessionReceiverOptions() { }
+        public bool EnableNonExclusiveSession { get { throw null; } set { } }
         public string Identifier { get { throw null; } set { } }
         public int PrefetchCount { get { throw null; } set { } }
         public Azure.Messaging.ServiceBus.ServiceBusReceiveMode ReceiveMode { get { throw null; } set { } }
+        public System.Guid? SessionLockToken { get { throw null; } set { } }
         public override bool Equals(object obj) { throw null; }
         public override int GetHashCode() { throw null; }
         public override string ToString() { throw null; }

@@ -499,18 +499,22 @@ public partial class ServiceBusSessionReceiver : Azure.Messaging.ServiceBus.Serv
     {
         protected ServiceBusSessionReceiver() { }
         public override bool IsClosed { get { throw null; } }
+        public virtual bool IsSessionExclusive { get { throw null; } }
         public virtual string SessionId { get { throw null; } }
         public virtual System.DateTimeOffset SessionLockedUntil { get { throw null; } }
+        public virtual string SessionLockToken { get { throw null; } }
         public virtual System.Threading.Tasks.Task<System.BinaryData> GetSessionStateAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task RenewSessionLockAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task SetSessionStateAsync(System.BinaryData sessionState, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class ServiceBusSessionReceiverOptions
     {
         public ServiceBusSessionReceiverOptions() { }
+        public bool EnableNonExclusiveSession { get { throw null; } set { } }
         public string Identifier { get { throw null; } set { } }
         public int PrefetchCount { get { throw null; } set { } }
         public Azure.Messaging.ServiceBus.ServiceBusReceiveMode ReceiveMode { get { throw null; } set { } }
+        public System.Guid? SessionLockToken { get { throw null; } set { } }
         public override bool Equals(object obj) { throw null; }
         public override int GetHashCode() { throw null; }
         public override string ToString() { throw null; }

@@ -168,6 +168,8 @@ public override TransportSender CreateSender(
         /// <param name="sessionId">The session ID to receive messages for.</param>
         /// <param name="isSessionReceiver">Whether or not this is a sessionful receiver link.</param>
         /// <param name="isProcessor">Whether or not the receiver is being created for a processor.</param>
+        /// <param name="isSessionExclusive">Whether or not the session is locked exclusively. Only applicable for session receivers.</param>
+        /// <param name="sessionLockToken">The session lock token to present when cooperatively taking over a non-exclusive session. Only applicable for session receivers.</param>
         /// <param name="cancellationToken">An optional <see cref="CancellationToken"/> instance to signal the request to cancel the
         ///     open link operation. Only applicable for session receivers.</param>
         /// <returns>A <see cref="TransportReceiver" /> configured in the requested manner.</returns>
@@ -180,7 +182,9 @@ public override TransportReceiver CreateReceiver(
             string sessionId,
             bool isSessionReceiver,
             bool isProcessor,
-            CancellationToken cancellationToken)
+            bool isSessionExclusive = true,
+            Guid? sessionLockToken = null,
+            CancellationToken cancellationToken = default)
         {
             Argument.AssertNotDisposed(_closed, nameof(AmqpClient));
 
@@ -196,6 +200,8 @@ public override TransportReceiver CreateReceiver(
                 isSessionReceiver,
                 isProcessor,
                 _messageConverter,
+                isSessionExclusive,
+                sessionLockToken,
                 cancellationToken
             );
         }

@@ -30,6 +30,17 @@ internal class AmqpClientConstants
         public const string FilterReceivedAt = FilterReceivedAtPartNameV2 + " > ";
         public const string FilterReceivedAtFormatString = FilterReceivedAt + "{0}";
         public static readonly AmqpSymbol SessionFilterName = AmqpConstants.Vendor + ":session-filter";
+        public static readonly AmqpSymbol NonExclusiveSessionFilterName = AmqpConstants.Vendor + ":non-exclusive-session-filter";
+
+        /// <summary>
+        /// The portion of an attach rejection that names the filter as one the endpoint does not recognize. An
+        /// endpoint without non-exclusive session locking refuses <see cref="NonExclusiveSessionFilterName" /> with
+        /// a description carrying this. The service authors the wording under no contract, so a rewording returns
+        /// callers to the exception the refusal's condition maps to. Observed in the form "The link '&lt;name&gt;'
+        /// contains invalid filter type. System only support Jms or Apache selector filter type."
+        /// </summary>
+        public const string UnrecognizedFilterErrorFragment = "invalid filter type";
+
         public static readonly AmqpSymbol MessageReceiptsFilterName = AmqpConstants.Vendor + ":message-receipts-filter";
         public static readonly AmqpSymbol ClientSideCursorFilterName = AmqpConstants.Vendor + ":client-side-filter";
         public static readonly TimeSpan ClientMinimumTokenRefreshInterval = TimeSpan.FromMinutes(4);

@@ -13,6 +13,7 @@
 using System.Threading.Tasks;
 using Azure.Core;
 using Azure.Core.Diagnostics;
+using Azure.Messaging.ServiceBus.Amqp.Framing;
 using Azure.Messaging.ServiceBus.Authorization;
 using Azure.Messaging.ServiceBus.Core;
 using Azure.Messaging.ServiceBus.Diagnostics;
@@ -362,6 +363,8 @@ public virtual async Task<RequestResponseAmqpLink> OpenManagementLinkAsync(
         /// <param name="receiveMode">The <see cref="ServiceBusReceiveMode"/> used to specify how messages are received. Defaults to PeekLock mode.</param>
         /// <param name="sessionId">The session to connect to.</param>
         /// <param name="isSessionReceiver">Whether or not this is a sessionful receiver.</param>
+        /// <param name="isSessionExclusive">Whether or not the session is locked exclusively. Only applicable for session receivers.</param>
+        /// <param name="sessionLockToken">The session lock token to present when cooperatively taking over a non-exclusive session. Only applicable for session receivers.</param>
         /// <param name="cancellationToken">An optional <see cref="CancellationToken"/> instance to signal the request to cancel the operation.</param>
         /// <returns>A link for use with consumer operations.</returns>
         public virtual async Task<ReceivingAmqpLink> OpenReceiverLinkAsync(
@@ -372,7 +375,9 @@ public virtual async Task<ReceivingAmqpLink> OpenReceiverLinkAsync(
             ServiceBusReceiveMode receiveMode,
             string sessionId,
             bool isSessionReceiver,
-            CancellationToken cancellationToken)
+            bool isSessionExclusive = true,
+            Guid? sessionLockToken = null,
+            CancellationToken cancellationToken = default)
         {
             Argument.AssertNotDisposed(_disposed, nameof(AmqpConnectionScope));
             cancellationToken.ThrowIfCancellationRequested<TaskCanceledException>();
@@ -392,6 +397,8 @@ public virtual async Task<ReceivingAmqpLink> OpenReceiverLinkAsync(
                 receiveMode: receiveMode,
                 sessionId: sessionId,
                 isSessionReceiver: isSessionReceiver,
+                isSessionExclusive: isSessionExclusive,
+                sessionLockToken: sessionLockToken,
                 cancellationToken: cancellationToken
             ).ConfigureAwait(false);
 
@@ -637,6 +644,8 @@ protected virtual async Task<RequestResponseAmqpLink> CreateManagementLinkAsync(
         /// <param name="receiveMode">The <see cref="ServiceBusReceiveMode"/> used to specify how messages are received. Defaults to PeekLock mode.</param>
         /// <param name="sessionId">The session to receive from.</param>
         /// <param name="isSessionReceiver">Whether or not this is a sessionful receiver.</param>
+        /// <param name="isSessionExclusive">Whether or not the session is locked exclusively. Only applicable for session receivers.</param>
+        /// <param name="sessionLockToken">The session lock token to present when cooperatively taking over a non-exclusive session. Only applicable for session receivers.</param>
         /// <param name="cancellationToken">An optional <see cref="CancellationToken"/> instance to signal the request to cancel the operation.</param>
         /// <returns>A link for use for operations related to receiving events.</returns>
         protected virtual async Task<ReceivingAmqpLink> CreateReceivingLinkAsync(
@@ -649,7 +658,9 @@ protected virtual async Task<ReceivingAmqpLink> CreateReceivingLinkAsync(
             ServiceBusReceiveMode receiveMode,
             string sessionId,
             bool isSessionReceiver,
-            CancellationToken cancellationToken)
+            bool isSessionExclusive = true,
+            Guid? sessionLockToken = null,
+            CancellationToken cancellationToken = default)
         {
             Argument.AssertNotDisposed(IsDisposed, nameof(AmqpConnectionScope));
             cancellationToken.ThrowIfCancellationRequested<TaskCanceledException>();
@@ -683,10 +694,25 @@ protected virtual async Task<ReceivingAmqpLink> CreateReceivingLinkAsync(
 
                 var filters = new FilterSet();
 
-                // even if supplied sessionId is null, we need to add the Session filter if it is a session receiver
+                // even if the supplied sessionId is null, a session receiver needs a session filter on the link:
+                // the plain session filter for an exclusive session, or the composite non-exclusive session filter otherwise.
                 if (isSessionReceiver)
                 {
-                    filters.Add(AmqpClientConstants.SessionFilterName, sessionId);
+                    if (isSessionExclusive)
+                    {
+                        filters.Add(AmqpClientConstants.SessionFilterName, sessionId);
+                    }
+                    else
+                    {
+                        // Non-exclusive locking: a single composite filter carries the session id and (for takeover)
+                        // the lock token. Presence of this filter implies non-exclusive mode. The plain session
+                        // filter is omitted. A service that predates this change does not silently ignore the unknown
+                        // filter - it rejects the attach with an "invalid filter type" error - so this path depends on
+                        // the service-side change being deployed in the target region.
+                        filters.Add(
+                            AmqpClientConstants.NonExclusiveSessionFilterName,
+                            new AmqpNonExclusiveSessionFilterCodec { SessionId = sessionId, LockToken = sessionLockToken });
+                    }
                 }
 
                 var linkSettings = new AmqpLinkSettings

@@ -112,6 +112,9 @@ public static Exception ToMessagingContractException(string condition, string me
                 return new NotSupportedException(EnrichMessage(message));
             }
 
+            // A receiver opening a non-exclusive session link reports one refusal carrying this condition as a
+            // NotSupportedException instead, because that refusal is the endpoint declining the feature rather than
+            // the operation. See AmqpReceiver.IsUnrecognizedFilterRejection; every other refusal maps here.
             if (string.Equals(condition, AmqpErrorCode.NotAllowed.Value, StringComparison.InvariantCultureIgnoreCase))
             {
                 return new InvalidOperationException(EnrichMessage(message));