Biblioteca de clientes do Barramento de Serviço do Azure WebJobs para .NET – versão 5.13.3

  • Artigo

Essa extensão fornece funcionalidade para acessar Barramento de Serviço do Azure de uma Função do Azure.

Introdução

Instalar o pacote

Instale a extensão do Barramento de Serviço com o NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus

Pré-requisitos

  • Assinatura do Azure: Para usar os serviços do Azure, incluindo Barramento de Serviço do Azure, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar os benefícios da assinatura do Visual Studio ao criar uma conta.

  • Namespace do Barramento de Serviço: Para interagir com Barramento de Serviço do Azure, você também precisará ter um namespace disponível. Se você não estiver familiarizado com a criação de recursos do Azure, convém seguir o guia passo a passo para criar um namespace do Barramento de Serviço usando o portal do Azure. Lá, você também pode encontrar instruções detalhadas para usar os modelos da CLI do Azure, Azure PowerShell ou ARM (Azure Resource Manager) para criar uma entidade de barramento de serviço.

Para criar rapidamente os recursos necessários do Barramento de Serviço no Azure e receber um cadeia de conexão para eles, você pode implantar nosso modelo de exemplo clicando em:

Implantar no Azure

Autenticar o Cliente

Para que a biblioteca de clientes do Barramento de Serviço interaja com uma fila ou tópico, ela precisará entender como se conectar e autorizar com ela. O meio mais fácil para fazer isso é usar um cadeia de conexão, que é criado automaticamente ao criar um namespace do Barramento de Serviço. Se você não estiver familiarizado com políticas de acesso compartilhado no Azure, convém seguir o guia passo a passo para obter uma cadeia de conexão do Barramento de Serviço.

A Connection propriedade de ServiceBusAttribute e ServiceBusTriggerAttribute é usada para especificar a propriedade de configuração que armazena o cadeia de conexão. Se não for especificado, espera-se que a propriedade AzureWebJobsServiceBus contenha o cadeia de conexão.

Para desenvolvimento local, use o local.settings.json arquivo para armazenar o cadeia de conexão:

{
  "Values": {
    "<connection_name>": "Endpoint=sb://<service_bus_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=<access key>"
  }
}

Quando implantado, use as configurações do aplicativo para definir o cadeia de conexão.

Autenticação baseada em identidade

Se o ambiente tiver a identidade gerenciada habilitada, você poderá usá-la para autenticar a extensão do Barramento de Serviço. Antes de fazer isso, você precisará garantir que as permissões tenham sido configuradas conforme descrito no guia do desenvolvedor do Azure Functions. Para usar a autenticação baseada em identidade, forneça a <connection_name>__fullyQualifiedNamespace configuração.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>__fullyQualifiedNamespace": "<service_bus_namespace>.servicebus.windows.net"
  }
}

Ou, no caso do aplicativo implantado, defina a mesma configuração nas configurações do aplicativo:

<connection_name>__fullyQualifiedNamespace=<service_bus_namespace>.servicebus.windows.net

Mais detalhes sobre como configurar uma conexão baseada em identidade podem ser encontrados aqui.

Principais conceitos

Gatilho do Barramento de Serviço

O Gatilho do Barramento de Serviço permite que uma função seja executada quando uma mensagem é enviada para uma fila ou tópico do Barramento de Serviço.

Siga o tutorial Barramento de Serviço do Azure gatilho para saber mais sobre gatilhos do Barramento de Serviço.

Associação de saída do Barramento de Serviço

A Associação de Saída do Barramento de Serviço permite que uma função envie mensagens do Barramento de Serviço.

Siga a Barramento de Serviço do Azure associação de saída para saber mais sobre as associações do Barramento de Serviço.

Exemplos

Enviando mensagens individuais

Você pode enviar mensagens individuais para uma fila ou tópico aplicando o ServiceBus atributo ao valor retornado da função. O valor retornado pode ser do tipo string, byte[]ou ServiceBusMessage.

[FunctionName("BindingToReturnValue")]
[return: ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
public static string BindToReturnValue([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
    // This value would get stored in Service Bus message body.
    // The string would be UTF8 encoded.
    return $"C# Timer trigger function executed at: {DateTime.Now}";
}

Você também pode usar um out parâmetro do tipo string, byte[]ou ServiceBusMessage.

[FunctionName("BindingToOutputParameter")]
public static void Run(
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] out ServiceBusMessage message)
{
    message = new ServiceBusMessage($"C# Timer trigger function executed at: {DateTime.Now}");
}

Enviando várias mensagens

Para enviar várias mensagens de uma única invocação de Função do Azure, você pode aplicar o ServiceBus atributo ao IAsyncCollector<string> parâmetro ou IAsyncCollector<ServiceBusReceivedMessage> .

[FunctionName("BindingToCollector")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] IAsyncCollector<ServiceBusMessage> collector)
{
    // IAsyncCollector allows sending multiple messages in a single function invocation
    await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")));
    await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}")));
}

Usando a associação a modelos fortemente tipado

Para usar classes de modelo fortemente tipdas com a associação ServiceBus, aplique o ServiceBus atributo ao parâmetro de modelo. Isso tentará desserializar o ServiceBusMessage.Bodyno modelo fortemente tipado.

[FunctionName("TriggerSingleModel")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] Dog dog,
    ILogger logger)
{
    logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}

Enviando várias mensagens usando ServiceBusSender

Você também pode associar ao ServiceBusSender diretamente para ter mais controle sobre o envio de mensagens.

[FunctionName("BindingToSender")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] ServiceBusSender sender)
{
    await sender.SendMessagesAsync(new[]
    {
        new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")),
        new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}"))
    });
}

Gatilhos por mensagem

Para executar uma função sempre que uma mensagem é enviada para uma fila ou assinatura do Barramento de Serviço, aplique o ServiceBusTrigger atributo a um stringparâmetro , byte[]ou ServiceBusReceivedMessage .

[FunctionName("TriggerSingle")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] string messageBodyAsString,
    ILogger logger)
{
    logger.LogInformation($"C# function triggered to process a message: {messageBodyAsString}");
}

Gatilhos do Lote

Para executar uma função para um lote de mensagens recebidas, aplique o ServiceBusTrigger atributo a um string[]parâmetro ou ServiceBusReceivedMessage[] .

[FunctionName("TriggerBatch")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] ServiceBusReceivedMessage[] messages,
    ILogger logger)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        logger.LogInformation($"C# function triggered to process a message: {message.Body}");
        logger.LogInformation($"EnqueuedTime={message.EnqueuedTime}");
    }
}

Liquidação de mensagens

Você pode configurar mensagens para serem concluídas automaticamente após a execução da função usando o ServiceBusOptions. Se você quiser mais controle sobre a liquidação de mensagens, poderá associar ao MessageActions com gatilhos por mensagem e em lotes.

[FunctionName("BindingToMessageActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")]
    ServiceBusReceivedMessage[] messages,
    ServiceBusMessageActions messageActions)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        if (message.MessageId == "1")
        {
            await messageActions.DeadLetterMessageAsync(message);
        }
        else
        {
            await messageActions.CompleteMessageAsync(message);
        }
    }
}

Gatilhos de sessão

Para receber mensagens de uma fila ou tópico habilitado para sessão, você pode definir a IsSessionsEnabled propriedade no ServiceBusTrigger atributo . Ao trabalhar com sessões, você pode associar ao SessionMessageActions para obter acesso aos métodos de liquidação de mensagens, além da funcionalidade específica da sessão.

[FunctionName("BindingToSessionMessageActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
    ServiceBusReceivedMessage[] messages,
    ServiceBusSessionMessageActions sessionActions)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        if (message.MessageId == "1")
        {
            await sessionActions.DeadLetterMessageAsync(message);
        }
        else
        {
            await sessionActions.CompleteMessageAsync(message);
        }
    }

    // We can also perform session-specific operations using the actions, such as setting state that is specific to this session.
    await sessionActions.SetSessionStateAsync(new BinaryData("<session state>"));
}

Associação ao ReceiveActions

É possível receber mensagens adicionais de dentro de sua invocação de função. Isso poderá ser útil se você precisar de mais controle sobre quantas mensagens processar em uma invocação de função com base em algumas características da mensagem inicial entregue à função por meio do parâmetro de associação. Todas as mensagens adicionais recebidas estarão sujeitas à mesma AutoCompleteMessages configuração e MaxAutoLockRenewalDuration à mensagem inicial entregue à sua função. Também é possível espiar mensagens. As mensagens espiadas não estão sujeitas à AutoCompleteMessages configuração e MaxAutoLockRenewalDuration porque essas mensagens não estão bloqueadas e, portanto, não podem ser concluídas.

[FunctionName("BindingToReceiveActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions,
    ServiceBusReceiveActions receiveActions)
{
    if (message.MessageId == "1")
    {
        await messageActions.DeadLetterMessageAsync(message);
    }
    else
    {
        await messageActions.CompleteMessageAsync(message);

        // attempt to receive additional messages in this session
        var receivedMessages = await receiveActions.ReceiveMessagesAsync(maxMessages: 10);

        // you can also use the receive actions to peek messages
        var peekedMessages = await receiveActions.PeekMessagesAsync(maxMessages: 10);
    }
}

Associação ao ServiceBusClient

Pode haver momentos em que você deseja associar ao mesmo ServiceBusClient que o gatilho está usando. Isso pode ser útil se você precisar criar dinamicamente um remetente com base na mensagem recebida.

[FunctionName("BindingToClient")]
public static async Task Run(
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
    ServiceBusReceivedMessage message,
    ServiceBusClient client)
{
    ServiceBusSender sender = client.CreateSender(message.To);
    await sender.SendMessageAsync(new ServiceBusMessage(message));
}

Solução de problemas

Se sua função disparar uma exceção sem tratamento e você ainda não tiver resolvido a mensagem, a extensão tentará abandonar a mensagem para que ela fique disponível para receber novamente imediatamente.

Consulte Monitorar Azure Functions para obter mais diretrizes de solução de problemas.

Próximas etapas

Leia a introdução ao Azure Functions ou criar um guia de funções do Azure.

Participante

Confira nosso CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões