Guia de início rápido: biblioteca de cliente do Armazenamento de Filas do Azure para .NET

  • Artigo

Introdução à biblioteca de cliente do Armazenamento de Filas do Azure para .NET. O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens para recuperação e processamento posteriores. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Documentação | de referência da API Pacote de código-fonte | da biblioteca (NuGet)Exemplos |

Use a biblioteca de cliente do Armazenamento de Filas do Azure para .NET para:

  • Criar uma fila
  • Adicionar mensagens a uma fila
  • Espreitar mensagens numa fila
  • Atualizar uma mensagem em uma fila
  • Obter o comprimento da fila
  • Receber mensagens de uma fila
  • Excluir mensagens de uma fila
  • Eliminar uma fila

Pré-requisitos

Configuração

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Filas do Azure para .NET.

Criar o projeto

Crie um aplicativo .NET chamado QueuesQuickstart.

  1. Em uma janela de console (como cmd, PowerShell ou Bash), use o comando para criar um novo aplicativo de console com o dotnet new nome QueuesQuickstart. Este comando cria um projeto C# simples "hello world" com um único arquivo de origem chamado Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Alterne para o diretório recém-criado QueuesQuickstart .

    cd QueuesQuickstart

Instalar os pacotes

Enquanto ainda estiver no diretório do aplicativo, instale a biblioteca de cliente do Armazenamento de Filas do Azure para o pacote .NET usando o dotnet add package comando.

dotnet add package Azure.Storage.Queues

O pacote de biblioteca de cliente do Azure Identity também é necessário para conexões sem senha com os serviços do Azure.

dotnet add package Azure.Identity

Configurar a estrutura do aplicativo

  1. Abra o projeto no editor de sua escolha
  2. Abra o arquivo .cs programa
  3. Atualize o código existente para corresponder ao seguinte:
using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Autenticar no Azure

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a classe fornecida pela biblioteca de cliente do Azure Identity é a DefaultAzureCredential abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código.

Você também pode autorizar solicitações aos serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local inseguro. Qualquer pessoa que obtenha acesso à senha ou chave secreta é capaz de autenticar. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma classe fornecida pela biblioteca de cliente do Azure Identity para .NET. Para saber mais sobre DefaultAzureCredentialo , consulte a visão geral de DefaultAzureCredential. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Por exemplo, seu aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio ao desenvolver localmente e, em seguida, usar uma identidade gerenciada depois de implantada no Azure. Não são necessárias alterações de código para esta transição.

Ao desenvolver localmente, certifique-se de que a conta de usuário que está acessando os dados da fila tenha as permissões corretas. Você precisará do Storage Queue Data Contributor para ler e gravar dados da fila. Para atribuir essa função a si mesmo, você precisará receber a função de Administrador de Acesso de Usuário ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. Você pode atribuir funções do RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, com escopo para a conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados da Fila de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados da fila em sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para que a atribuição de função se propague no Azure, mas, em casos raros, pode levar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

A screenshot showing how to assign a role.

  1. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure por Colaborador de Dados da Fila de Armazenamento , selecione o resultado correspondente e escolha Avançar.

  2. Em Atribuir acesso a, selecione Utilizador, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  3. Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.

  4. Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.

Modelo de objeto

O Armazenamento de Filas do Azure é um serviço para alojar grandes quantidades de mensagens. Uma mensagem de fila pode ter até 64 KB de tamanho. Uma fila pode conter milhões de mensagens, até o limite de capacidade total de uma conta de armazenamento. As filas são comumente usadas para criar uma lista de pendências de trabalho para processar de forma assíncrona. O armazenamento em fila oferece três tipos de recursos:

  • Conta de armazenamento: todo o acesso ao Armazenamento do Azure é feito por meio de uma conta de armazenamento. Para obter mais informações sobre contas de armazenamento, consulte Visão geral da conta de armazenamento
  • Fila: uma fila contém um conjunto de mensagens. Todas as mensagens têm de estar numa fila. Tenha em atenção que o nome da fila tem de estar todo em minúsculas. Para obter informações sobre a nomenclatura de filas, veja Nomenclatura de Filas e Metadados.
  • Mensagem: uma mensagem, em qualquer formato, até 64 KB. Uma mensagem pode permanecer na fila por no máximo 7 dias. Para a versão 2017-07-29 ou posterior, o tempo máximo de vida pode ser qualquer número positivo ou -1 indicando que a mensagem não expira. Se esse parâmetro for omitido, o tempo de vida padrão será de sete dias.

O diagrama seguinte mostra a relação entre estes recursos.

Diagram of Queue storage architecture

Use as seguintes classes .NET para interagir com esses recursos:

  • QueueServiceClient: O QueueServiceClient permite que você gerencie todas as filas em sua conta de armazenamento.
  • QueueClient: A QueueClient classe permite que você gerencie e manipule uma fila individual e suas mensagens.
  • QueueMessage: A QueueMessage classe representa os objetos individuais retornados ao chamar ReceiveMessages em uma fila.

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes ações com a biblioteca de cliente do Armazenamento de Filas do Azure para .NET:

Autorizar o acesso e criar um objeto cliente

Para desenvolvimento local, certifique-se de que está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função. Você pode autenticar por meio de ferramentas de desenvolvimento populares, como a CLI do Azure ou o Azure PowerShell. As ferramentas de desenvolvimento com as quais você pode autenticar variam entre os idiomas.

Entre no Azure por meio da CLI do Azure usando o seguinte comando:

az login

Uma vez autenticado, você pode criar e autorizar um QueueClient objeto usando DefaultAzureCredential para acessar dados de fila na conta de armazenamento. DefaultAzureCredential Descobre e utiliza automaticamente a conta com a qual iniciou sessão no passo anterior.

Para autorizar o uso DefaultAzureCredentialdo , verifique se você adicionou o pacote Azure.Identity , conforme descrito em Instalar os pacotes. Além disso, certifique-se de adicionar uma diretiva using para o Azure.Identity namespace no arquivo Program.cs :

using Azure.Identity;

Em seguida, decida um nome para a fila e crie uma instância da QueueClient classe, usando DefaultAzureCredential para autorização. Usamos esse objeto de cliente para criar e interagir com o recurso de fila na conta de armazenamento.

Importante

Os nomes das filas só podem conter letras minúsculas, números e hífenes, e devem começar com uma letra ou um número. Cada hífen tem de ser precedido e seguido de um caráter que não seja um hífen. O nome também deve ter entre 3 e 63 caracteres. Para obter mais informações, consulte Nomeando filas e metadados.

Adicione o seguinte código ao final do arquivo .cs programa. Certifique-se de substituir o valor do <storage-account-name> espaço reservado:

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

Nota

As mensagens enviadas usando a QueueClient classe devem estar em um formato que possa ser incluído em uma solicitação XML com codificação UTF-8. Opcionalmente, você pode definir a opção MessageEncoding como Base64 para lidar com mensagens não compatíveis.

Criar uma fila

Usando o objeto, chame o QueueClientCreateAsync método para criar a fila em sua conta de armazenamento.

Adicione este código ao final do método Program.cs :

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

Adicionar mensagens a uma fila

O trecho de código a seguir adiciona mensagens de forma assíncrona à fila chamando o SendMessageAsync método. Ele também salva um SendReceipt retorno de uma SendMessageAsync chamada. O recibo é usado para atualizar a mensagem posteriormente no programa.

Adicione este código ao final do arquivo .cs programa:

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

Espreitar mensagens numa fila

Espreite as mensagens na fila chamando o PeekMessagesAsync método. Esse método recupera uma ou mais mensagens da frente da fila, mas não altera a visibilidade da mensagem.

Adicione este código ao final do arquivo .cs programa:

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

Atualizar uma mensagem em uma fila

Atualize o conteúdo de uma mensagem chamando o UpdateMessageAsync método. Esse método pode alterar o tempo limite de visibilidade e o conteúdo de uma mensagem. O conteúdo da mensagem deve ser uma cadeia de caracteres codificada UTF-8 com até 64 KB de tamanho. Junto com o novo conteúdo da mensagem, passe os valores do SendReceipt que foi salvo anteriormente no código. Os SendReceipt valores identificam qual mensagem atualizar.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

Obter o comprimento da fila

Pode obter uma estimativa do número de mensagens numa fila. O GetProperties método retorna propriedades de fila, incluindo a contagem de mensagens. A ApproximateMessagesCount propriedade contém o número aproximado de mensagens na fila. Esse número não é menor do que o número real de mensagens na fila, mas pode ser maior.

Adicione este código ao final do arquivo .cs programa:

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

Receber mensagens de uma fila

Baixe mensagens adicionadas anteriormente chamando o ReceiveMessagesAsync método.

Adicione este código ao final do arquivo .cs programa:

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

Opcionalmente, você pode especificar um valor para maxMessages, que é o número de mensagens a serem recuperadas da fila. O padrão é 1 mensagem e o máximo é 32 mensagens. Você também pode especificar um valor para , que oculta as mensagens de outras operações para visibilityTimeouto período de tempo limite. A predefinição é 30 segundos.

Excluir mensagens de uma fila

Exclua mensagens da fila depois que elas forem processadas. Neste caso, o processamento é apenas exibir a mensagem no console.

O aplicativo pausa para entrada do usuário chamando Console.ReadLine antes de processar e excluir as mensagens. Verifique no seu portal do Azure se os recursos foram criados corretamente, antes de serem excluídos. Quaisquer mensagens não excluídas explicitamente eventualmente se tornam visíveis na fila novamente para outra chance de processá-las.

Adicione este código ao final do arquivo .cs programa:

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

Eliminar uma fila

O código a seguir limpa os recursos que o aplicativo criou excluindo a fila usando o DeleteAsync método.

Adicione este código ao final do arquivo .cs programa:

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

Executar o código

Este aplicativo cria e adiciona três mensagens a uma fila do Azure. O código lista as mensagens na fila, recupera-as e exclui-as antes de finalmente excluir a fila.

Na janela do console, navegue até o diretório do aplicativo e, em seguida, compile e execute o aplicativo.

dotnet build

dotnet run

A saída do aplicativo é semelhante ao exemplo a seguir:

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

Quando o aplicativo pausa antes de receber mensagens, verifique sua conta de armazenamento no portal do Azure. Verifique se as mensagens estão na fila.

Pressione a Enter tecla para receber e excluir as mensagens. Quando solicitado, pressione a tecla novamente para excluir a fila e concluir a Enter demonstração.

Próximos passos

Neste guia de início rápido, você aprendeu como criar uma fila e adicionar mensagens a ela usando código .NET assíncrono. Então você aprendeu a espiar, recuperar e excluir mensagens. Finalmente, você aprendeu como excluir uma fila de mensagens.

Para tutoriais, exemplos, inícios rápidos e outra documentação, visite:

Azure for .NET and .NET Core developers (Azure para programadores de .NET e .NET Core)