Add documentation about native message access for ASQ

Snippets/ASQ/ASQN_10/AccessToNativeMessage.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using NServiceBus.Pipeline;
+using Azure.Storage.Queues.Models;
+
+namespace ASQN_10
+{
+    public class AccessToNativeMessage
+    {
+        #region access-native-incoming-message
+
+        class DoNotAttemptMessageProcessingIfMessageIsNotLocked : Behavior<ITransportReceiveContext>
+        {
+            public override Task Invoke(ITransportReceiveContext context, Func<Task> next)
+            {
+                var NextVisibleOnUtc = context.Extensions.Get<QueueMessage>().NextVisibleOn;
+
+                if (NextVisibleOnUtc <= DateTime.UtcNow)
+                {
+                    return next();
+                }
+
+                throw new Exception($"Message lock lost for MessageId {context.Message.MessageId} and it cannot be processed.");
+            }
+        }
+
+        #endregion
+    }
+}

Snippets/ASQ/ASQN_12/AccessToNativeMessage.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using NServiceBus.Pipeline;
+using Azure.Storage.Queues.Models;
+
+namespace ASQN_12
+{
+    public class AccessToNativeMessage
+    {
+        #region access-native-incoming-message
+
+        class DoNotAttemptMessageProcessingIfMessageIsNotLocked : Behavior<ITransportReceiveContext>
+        {
+            public override Task Invoke(ITransportReceiveContext context, Func<Task> next)
+            {
+                var NextVisibleOnUtc = context.Extensions.Get<QueueMessage>().NextVisibleOn;
+
+                if (NextVisibleOnUtc <= DateTime.UtcNow)
+                {
+                    return next();
+                }
+
+                throw new Exception($"Message lock lost for MessageId {context.Message.MessageId} and it cannot be processed.");
+            }
+        }
+
+        #endregion
+    }
+}

Snippets/ASQ/ASQN_13/AccessToNativeMessage.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using NServiceBus.Pipeline;
+using Azure.Storage.Queues.Models;
+
+namespace ASQN_13
+{
+    public class AccessToNativeMessage
+    {
+        #region access-native-incoming-message
+
+        class DoNotAttemptMessageProcessingIfMessageIsNotLocked : Behavior<ITransportReceiveContext>
+        {
+            public override Task Invoke(ITransportReceiveContext context, Func<Task> next)
+            {
+                var NextVisibleOnUtc = context.Extensions.Get<QueueMessage>().NextVisibleOn;
+
+                if (NextVisibleOnUtc <= DateTime.UtcNow)
+                {
+                    return next();
+                }
+
+                throw new Exception($"Message lock lost for MessageId {context.Message.MessageId} and it cannot be processed.");
+            }
+        }
+
+        #endregion
+    }
+}

menu/menu.yaml

@@ -965,6 +965,8 @@
       Title: Delayed Delivery
     - Url: transports/azure-storage-queues/native-integration
       Title: Native Integration
+    - Url: transports/azure-storage-queues/native-message-access
+      Title: Native Message Access
     - Url: transports/azure-storage-queues/native-publish-subscribe
       Title: Native Publish Subscribe
     - Url: transports/azure-storage-queues/sanitization

transports/azure-storage-queues/native-message-access.md

@@ -0,0 +1,9 @@
+---
+title: Native message access
+summary: Access native message information with the Azure Storage Queues transport
+reviewed: 2024-02-09
+component: ASQ
+versions: '[10,)'
+---
+
+partial: supported-versions

transports/azure-storage-queues/native-message-access_supported-versions_asqn_[10,11).partial.md

@@ -0,0 +1,7 @@
+## Access to the native Azure Storage Queue incoming message
+
+Accessing the native azure storage queue incoming message from behaviors and handlers can be beneficial for customizations and recoverability.  When a message is received, the transport includes the native `QueueMessage` in the message processing context. You can use the following code to retrieve the message details from a pipeline behavior:
+
+snippet: access-native-incoming-message
+
+The behavior above utilizes the native message’s `NextVisibleOn` property to identify when the message lost its lock due to aggressive prefetching and slow processing. If needed, a [custom recoverability policy](/nservicebus/recoverability/custom-recoverability-policy.md) can be implemented to bypass retry attempts that would inevitably fail because of the lost lock.

transports/azure-storage-queues/native-message-access_supported-versions_asqn_[11,12).partial.md

@@ -0,0 +1,3 @@
+This document describes how to access native message information with the Azure Storage Queue transport.
+
+- Incoming message access is available on versions 10.x, 12.x, and 13.x

transports/azure-storage-queues/native-message-access_supported-versions_asqn_[12,).partial.md

@@ -0,0 +1,7 @@
+## Access to the native Azure Storage Queues incoming message
+
+Accessing the native azure storage queue incoming message from behaviors and handlers can be beneficial for customizations and recoverability.  When a message is received, the transport includes the native `QueueMessage` in the message processing context. You can use the following code to retrieve the message details from a pipeline behavior:
+
+snippet: access-native-incoming-message
+
+The behavior above utilizes the native message’s `NextVisibleOn` property to identify when the message lost its lock due to aggressive prefetching and slow processing. If needed, a [custom recoverability policy](/nservicebus/recoverability/custom-recoverability-policy.md) can be implemented to bypass retry attempts that would inevitably fail because of the lost lock.