Merge pull request #236096 from pauljewellmsft/pauljewell-v11-queues

Move deprecated client library samples for queues

Author: AnnaMHuff

articles/storage/queues/TOC.yml

@@ -207,11 +207,7 @@
     - name: Change how data is replicated
       href: ../common/redundancy-migration.md?toc=/azure/storage/queues/toc.json
     - name: Design highly available applications
-      items:
-      - name: .NET (v12 SDK)
-        href: ../common/geo-redundant-design.md?toc=/azure/storage/queues/toc.json
-      - name: .NET (v11 SDK)
-        href: ../common/geo-redundant-design-legacy.md?toc=/azure/storage/queues/toc.json
+      href: ../common/geo-redundant-design.md?toc=/azure/storage/queues/toc.json
   - name: Manage disaster recovery
     items:
     - name: Check the Last Sync Time property
@@ -367,5 +363,17 @@
         href: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage
       - name: Azure Storage client library version 2.1
         href: https://github.com/Azure/azure-storage-python
+  - name: Code samples using deprecated SDKs
+    items:
+      - name: .NET
+        items:
+          - name: Version 11.x samples
+            href: queues-v11-samples-dotnet.md
+          - name: Design highly available applications (.NET version 11.x)
+            href: ../common/geo-redundant-design-legacy.md?toc=/azure/storage/queues/toc.json
+      - name: Java version 8 samples
+        href: queues-v8-samples-java.md
+      - name: Python version 2 samples
+        href: queues-v2-samples-python.md
   - name: Compliance offerings
     href: ../common/storage-compliance-offerings.md

articles/storage/queues/queues-v11-samples-dotnet.md

@@ -0,0 +1,271 @@
+---
+title: Azure Queue Storage code samples using .NET version 11.x client libraries
+titleSuffix: Azure Storage
+description: View code samples that use the Azure Queue Storage client library for .NET version 11.x.
+services: storage
+author: pauljewellmsft
+ms.service: storage
+ms.subservice: queues
+ms.topic: how-to
+ms.date: 04/26/2023
+ms.author: pauljewell
+---
+
+# Azure Queue Storage code samples using .NET version 11.x client libraries
+
+This article shows code samples that use version 11.x of the Azure Queue Storage client library for .NET.
+
+[!INCLUDE [storage-v11-sdk-support-retirement](../../../includes/storage-v11-sdk-support-retirement.md)]
+
+## Create a Queue Storage client
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#create-the-queue-storage-client)
+
+The [`CloudQueueClient`](/dotnet/api/microsoft.azure.storage.queue.cloudqueueclient?view=azure-dotnet-legacy&preserve-view=true) class enables you to retrieve queues stored in Queue Storage. Here's one way to create the service client:
+
+```csharp
+// Retrieve storage account from connection string
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+```
+
+## Create a queue
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#create-a-queue)
+
+This example shows how to create a queue:
+
+```csharp
+// Retrieve storage account from connection string
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Create the queue if it doesn't already exist
+queue.CreateIfNotExists();
+```
+
+## Insert a message into a queue
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#insert-a-message-into-a-queue)
+
+To insert a message into an existing queue, first create a new [`CloudQueueMessage`](/dotnet/api/microsoft.azure.storage.queue.cloudqueuemessage?view=azure-dotnet-legacy&preserve-view=true). Next, call the [`AddMessage`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.addmessage?view=azure-dotnet-legacy&preserve-view=true) method. A `CloudQueueMessage` can be created from either a string (in UTF-8 format) or a byte array. The following code example creates a queue (if it doesn't already exist) and inserts the message `Hello, World`:
+
+```csharp
+// Retrieve storage account from connection string
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Create the queue if it doesn't already exist
+queue.CreateIfNotExists();
+
+// Create a message and add it to the queue
+CloudQueueMessage message = new CloudQueueMessage("Hello, World");
+queue.AddMessage(message);
+```
+
+## Peek at the next message
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#peek-at-the-next-message)
+
+You can peek at the message in the front of a queue without removing it from the queue by calling the [`PeekMessage`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.peekmessage?view=azure-dotnet-legacy&preserve-view=true) method.
+
+```csharp
+// Retrieve storage account from connection string
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Peek at the next message
+CloudQueueMessage peekedMessage = queue.PeekMessage();
+
+// Display message.
+Console.WriteLine(peekedMessage.AsString);
+```
+
+## Change the contents of a queued message
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#change-the-contents-of-a-queued-message)
+
+```csharp
+// Retrieve storage account from connection string.
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client.
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue.
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Get the message from the queue and update the message contents.
+CloudQueueMessage message = queue.GetMessage();
+message.SetMessageContent2("Updated contents.", false);
+queue.UpdateMessage(message,
+    TimeSpan.FromSeconds(60.0),  // Make it invisible for another 60 seconds.
+    MessageUpdateFields.Content | MessageUpdateFields.Visibility);
+```
+
+## Dequeue the next message
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#dequeue-the-next-message)
+
+Your code dequeues a message from a queue in two steps. When you call [`GetMessage`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.getmessage?view=azure-dotnet-legacy&preserve-view=true), you get the next message in a queue. A message returned from `GetMessage` becomes invisible to any other code reading messages from this queue. By default, this message stays invisible for 30 seconds. To finish removing the message from the queue, you must also call [`DeleteMessage`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.deletemessage?view=azure-dotnet-legacy&preserve-view=true). This two-step process of removing a message assures that if your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. Your code calls `DeleteMessage` right after the message has been processed.
+
+```csharp
+// Retrieve storage account from connection string
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Get the next message
+CloudQueueMessage retrievedMessage = queue.GetMessage();
+
+//Process the message in less than 30 seconds, and then delete the message
+queue.DeleteMessage(retrievedMessage);
+```
+
+## Use the async-await pattern with common Queue Storage APIs
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#use-the-async-await-pattern-with-common-queue-storage-apis)
+
+```csharp
+// Create the queue if it doesn't already exist
+if(await queue.CreateIfNotExistsAsync())
+{
+    Console.WriteLine("Queue '{0}' Created", queue.Name);
+}
+else
+{
+    Console.WriteLine("Queue '{0}' Exists", queue.Name);
+}
+
+// Create a message to put in the queue
+CloudQueueMessage cloudQueueMessage = new CloudQueueMessage("My message");
+
+// Async enqueue the message
+await queue.AddMessageAsync(cloudQueueMessage);
+Console.WriteLine("Message added");
+
+// Async dequeue the message
+CloudQueueMessage retrievedMessage = await queue.GetMessageAsync();
+Console.WriteLine("Retrieved message with content '{0}'", retrievedMessage.AsString);
+
+// Async delete the message
+await queue.DeleteMessageAsync(retrievedMessage);
+Console.WriteLine("Deleted message");
+```
+
+## Use additional options for dequeuing messages
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#use-additional-options-for-dequeuing-messages)
+
+The following code example uses the [`GetMessages`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.getmessages?view=azure-dotnet-legacy&preserve-view=true) method to get 20 messages in one call. Then it processes each message using a `foreach` loop. It also sets the invisibility timeout to five minutes for each message. The timeout starts for all messages at the same time, so after five minutes have passed since the call to `GetMessages`, any messages that haven't been deleted will become visible again.
+
+```csharp
+// Retrieve storage account from connection string.
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client.
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue.
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+foreach (CloudQueueMessage message in queue.GetMessages(20, TimeSpan.FromMinutes(5)))
+{
+    // Process all messages in less than 5 minutes, deleting each message after processing.
+    queue.DeleteMessage(message);
+}
+```
+
+## Get the queue length
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#get-the-queue-length)
+
+You can get an estimate of the number of messages in a queue. The [`FetchAttributes`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.fetchattributes?view=azure-dotnet-legacy&preserve-view=true) method returns queue attributes including the message count. The [`ApproximateMessageCount`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.approximatemessagecount?view=azure-dotnet-legacy&preserve-view=true) property returns the last value retrieved by the `FetchAttributes` method, without calling Queue Storage.
+
+```csharp
+// Retrieve storage account from connection string.
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client.
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue.
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Fetch the queue attributes.
+queue.FetchAttributes();
+
+// Retrieve the cached approximate message count.
+int cachedMessageCount = queue.ApproximateMessageCount;
+
+// Display number of messages.
+Console.WriteLine("Number of messages in queue: " + cachedMessageCount);
+```
+
+## Delete a queue
+
+Related article: [Get started with Azure Queue Storage using .NET](storage-dotnet-how-to-use-queues.md#delete-a-queue)
+
+To delete a queue and all the messages contained in it, call the [`Delete`](/dotnet/api/microsoft.azure.storage.queue.cloudqueue.delete?view=azure-dotnet-legacy&preserve-view=true) method on the queue object.
+
+```csharp
+// Retrieve storage account from connection string.
+CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
+    CloudConfigurationManager.GetSetting("StorageConnectionString"));
+
+// Create the queue client.
+CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
+
+// Retrieve a reference to a queue.
+CloudQueue queue = queueClient.GetQueueReference("myqueue");
+
+// Delete the queue.
+queue.Delete();
+```
+
+## Work with queues
+
+Related article: [Work with Azure Queue Storage queues in .NET](storage-tutorial-queues.md)
+
+In your project directory, add the following packages using the `dotnet add package` command:
+
+   ```console
+   dotnet add package Microsoft.Azure.Storage.Common
+   ```
+
+   ```console
+   dotnet add package Microsoft.Azure.Storage.Queue
+   ```
+
+Full code sample:
+
+:::code language="csharp" source="~/azure-storage-snippets/queues/tutorial/dotnet/dotnet-v11/QueueApp/Program.cs" id="snippet_AllCode":::