Biblioteca de cliente de Filas de Armazenamento do Azure para .NET – versão 12.13.1

Artigo
04/03/2023

Versão do Servidor: 2021-02-12, 2020-12-06, 2020-10-02, 2020-08-04, 2020-06-12, 2020-04-08, 2020-02-10, 2019-12-12, 2019-07-07 e 2019-02-02

O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens que podem ser acedidas a partir de qualquer local no mundo através de chamadas autenticadas com HTTP ou HTTPS. Uma mensagem de fila única pode ter até 64 KB e uma fila pode conter milhões de mensagens, até ao limite da capacidade total de uma conta de armazenamento.

Código fonte | Pacote (NuGet) | Documentação | de referência da API Documentação | da API REST Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de cliente filas de armazenamento do Azure para .NET com NuGet:

dotnet add package Azure.Storage.Queues

Pré-requisitos

Precisa de uma subscrição do Azure e de uma Conta de Armazenamento para utilizar este pacote.

Para criar uma nova Conta de Armazenamento, pode utilizar o Portal do Azure, Azure PowerShell ou a CLI do Azure. Eis um exemplo com a CLI do Azure:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Autenticar o cliente

Para interagir com o serviço Armazenamento de Filas do Azure, terá de criar uma instância da classe QueueClient. A biblioteca de Identidades do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com os respetivos serviços do Azure correspondentes.

// Create a QueueClient that will authenticate through Active Directory
Uri queueUri = new Uri("https://MYSTORAGEACCOUNT.queue.core.windows.net/QUEUENAME");
QueueClient queue = new QueueClient(queueUri, new DefaultAzureCredential());

Saiba mais sobre como ativar o Azure Active Directory para autenticação com o Armazenamento do Azure na nossa documentação e nos nossos exemplos.

Conceitos-chave

Utilizações comuns do Armazenamento de filas:

Criação de um registo de tarefas pendentes do trabalho para processamento de forma assíncrona
Transmitir mensagens entre diferentes partes de uma aplicação distribuída

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

Enviar mensagens

// We'll need a connection string to your Azure Storage account.
// You can obtain your connection string from the Azure Portal
// (click Access Keys under Settings in the Portal Storage account
// blade) or using the Azure CLI with:
//
//     az storage account show-connection-string --name <account_name> --resource-group <resource_group>
//
// You would normally provide the connection string to your
// application using an environment variable.
string connectionString = "<connection_string>";

// Name of the queue we'll send messages to
string queueName = "sample-queue";

// Get a reference to a queue and then create it
QueueClient queue = new QueueClient(connectionString, queueName);
queue.Create();

// Send a message to our queue
queue.SendMessage("Hello, Azure!");

Receber mensagens

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of an existing queue we'll operate on
string queueName = "sample-queue";

// Get a reference to a queue and then fill it with messages
QueueClient queue = new QueueClient(connectionString, queueName);
queue.SendMessage("first");
queue.SendMessage("second");
queue.SendMessage("third");

// Get the next messages from the queue
foreach (QueueMessage message in queue.ReceiveMessages(maxMessages: 10).Value)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.Body}");

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

APIs Assíncronas

Suportamos totalmente APIs síncronas e assíncronas.

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of the queue we'll send messages to
string queueName = "sample-queue";

// Get a reference to a queue and then create it
QueueClient queue = new QueueClient(connectionString, queueName);
await queue.CreateAsync();

// Send a message to our queue
await queue.SendMessageAsync("Hello, Azure!");

Codificação de mensagens

Esta versão da biblioteca não codifica a mensagem por predefinição. V11 e versões anteriores, bem como Funções do Azure utilizar mensagens codificadas com base64 por predefinição. Por conseguinte, é recomendado utilizar esta funcionalidade para cenários interop.

QueueClientOptions queueClientOptions = new QueueClientOptions()
{
    MessageEncoding = QueueMessageEncoding.Base64
};

QueueClient queueClient = new QueueClient(connectionString, queueName, queueClientOptions);

Resolução de problemas

Todas as operações do serviço Fila de Armazenamento do Azure irão lançar um RequestFailedException sobre a falha com s útilErrorCode. Muitos destes erros são recuperáveis.

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of an existing queue we'll operate on
string queueName = "sample-queue";

try
{
    // Try to create a queue that already exists
    QueueClient queue = new QueueClient(connectionString, queueName);
    queue.Create();
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == QueueErrorCode.QueueAlreadyExists)
{
    // Ignore any errors if the queue already exists
}

Passos seguintes

Introdução aos nossos exemplos de Fila:

Hello World: Enqueue, Dequeue, Peek e Atualizar mensagens de fila (ou de forma assíncrona)
Autenticação: autenticar com cadeias de ligação, chaves partilhadas, assinaturas de acesso partilhado e Azure Active Directory.

Contribuir

Veja o CONTRIBUTING.md de Armazenamento para obter detalhes sobre como criar, testar e contribuir para esta biblioteca.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões