Azure Service Bus klientské knihovny pro .NET – verze 7.13.1

Článek
04/03/2023

Azure Service Bus umožňuje vytvářet aplikace, které využívají asynchronní vzory zasílání zpráv pomocí vysoce spolehlivé služby pro zprostředkování zpráv mezi producenty a příjemci. Azure Service Bus poskytuje flexibilní zprostředkované zasílání zpráv mezi klientem a serverem spolu se strukturovaným zasíláním zpráv FIFO (first-in, first-out) a funkcemi publikování a odběru se složitým směrováním. Pokud se chcete o Azure Service Bus dozvědět více, můžete si projít téma Co je Azure Service Bus?

Pomocí klientské knihovny můžete Azure Service Bus:

Přenos obchodních dat: Využijte zasílání zpráv k trvalé výměně informací, jako jsou prodejní nebo nákupní objednávky, deníky nebo přesuny zásob.
Oddělení aplikací: Zlepšení spolehlivosti a škálovatelnosti aplikací a služeb a omezení odesílatelů a příjemců od potřeby být online ve stejnou dobu.
Řízení způsobu zpracování zpráv: podpora tradičních konkurenčních příjemců zpráv pomocí front nebo povolení vlastní instance zprávy každému příjemci pomocí témat a odběrů.
Implementace složitých pracovních postupů: Relace zpráv podporují scénáře, které vyžadují řazení zpráv nebo odložení zpráv.

Začínáme

Požadavky

Předplatné Microsoft Azure: Pokud chcete používat služby Azure, včetně Azure Service Bus, budete potřebovat předplatné. Pokud nemáte účet Azure, můžete si při vytváření účtu zaregistrovat bezplatnou zkušební verzi nebo využít výhody pro předplatitele MSDN.
Obor názvů služby Service Bus: Pokud chcete pracovat s Azure Service Bus, musíte mít k dispozici také obor názvů. Pokud nejste obeznámeni s vytvářením prostředků Azure, možná budete chtít postupovat podle podrobného průvodce vytvořením oboru názvů služby Service Bus pomocí Azure Portal. Najdete tam také podrobné pokyny k vytvoření entity služby Service Bus pomocí Azure CLI, Azure PowerShell nebo šablon Azure Resource Manager (ARM).
C# 8.0: Klientská knihovna Azure Service Bus využívá nové funkce, které byly představeny v jazyce C# 8.0. Abyste mohli využít syntaxi jazyka C# 8.0, doporučujeme kompilaci pomocí sady .NET Core SDK 3.0 nebo vyšší s jazykovou verzí nástroje latest.

Uživatelé sady Visual Studio, kteří chtějí plně využít syntaxi jazyka C# 8.0, budou muset použít sadu Visual Studio 2019 nebo novější. Visual Studio 2019, včetně bezplatné edice Community, si můžete stáhnout tady. Uživatelé sady Visual Studio 2017 můžou využít syntaxi jazyka C# 8 tím, že využijí balíček NuGet Microsoft.Net.Compilers a nastaví jazykovou verzi, i když prostředí pro úpravy nemusí být ideální.

Knihovnu můžete stále používat s předchozími verzemi jazyka C#, ale budete muset spravovat asynchronní výčtové a asynchronní jednorázové členy ručně a nebudete tak využívat výhod nové syntaxe. Stále můžete cílit na libovolnou verzi architektury, kterou vaše sada .NET Core SDK podporuje, včetně starších verzí .NET Core nebo .NET Framework. Další informace najdete v tématu Určení cílových architektur.

Důležitá poznámka: Aby bylo možné sestavit nebo spustit příklady a ukázky bez úprav, je použití jazyka C# 8.0 povinné. Pokud se rozhodnete ukázky upravit pro jiné jazykové verze, můžete je přesto spustit.

Pokud chcete rychle vytvořit potřebné prostředky služby Service Bus v Azure a získat pro ně připojovací řetězec, můžete naši ukázkovou šablonu nasadit kliknutím na:

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Service Bus pro .NET pomocí NuGetu:

dotnet add package Azure.Messaging.ServiceBus

Ověření klienta

Aby klientská knihovna služby Service Bus pracovala s frontou nebo tématem, musí pochopit, jak se k ní připojit a autorizovat s nimi. Nejjednodušším způsobem je použít připojovací řetězec, který se vytvoří automaticky při vytváření oboru názvů služby Service Bus. Pokud neznáte zásady sdíleného přístupu v Azure, možná budete chtít získat připojovací řetězec služby Service Bus podle podrobného průvodce.

Jakmile máte připojovací řetězec, můžete pomocí něj ověřit svého klienta.

// Create a ServiceBusClient that will authenticate using a connection string
string connectionString = "<connection_string>";
await using var client = new ServiceBusClient(connectionString);

Postup ověřování pomocí Azure.Identity najdete v tomto příkladu.

Pokud chcete zjistit, jak zahájit připojení pomocí vlastního koncového bodu, podívejte se na tuto ukázku.

ASP.NET Core

Pokud chcete do aplikace ASP.NET Core vložit ServiceBusClient závislost, nainstalujte integraci klientské knihovny Azure pro ASP.NET Core balíček.

dotnet add package Microsoft.Extensions.Azure

Pak zaregistrujte klienta v Startup.ConfigureServices metodě :

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddServiceBusClient(Configuration.GetConnectionString("ServiceBus"));
    });
  
    services.AddControllers();
}

Pokud chcete použít předchozí kód, přidejte do konfigurace tento kód:

{
  "ConnectionStrings": {
    "ServiceBus": "<connection_string>"
  }
}

Další podrobnosti najdete v tématu Injektáž závislostí pomocí sady Azure SDK pro .NET.

Klíčové koncepty

Jakmile inicializujete ServiceBusClient, můžete interagovat s primárními typy prostředků v rámci oboru názvů služby Service Bus, kterých může existovat více a na kterých probíhá skutečný přenos zpráv. Obor názvů často slouží jako kontejner aplikace:

Fronta: Umožňuje odesílání a příjem zpráv. Často se používá pro komunikaci typu point-to-point.
Téma: Na rozdíl od front jsou témata vhodnější pro scénáře publikování a odběru. Téma je možné odeslat na adresu, ale vyžaduje odběr, jehož odběr může být paralelně více.
Odběr: Mechanismus pro využívání z tématu. Každý odběr je nezávislý a obdrží kopii každé zprávy odeslané do tématu. Pravidla a filtry se dají použít k přizpůsobení toho, které zprávy mají být přijímány konkrétním odběrem.

Další informace o těchto prostředcích najdete v tématu Co je Azure Service Bus?.

Pokud chcete s těmito prostředky pracovat, měli byste znát následující koncepty sady SDK:

Klient Služby Service Bus je primárním rozhraním pro vývojáře, kteří komunikují s klientskou knihovnou služby Service Bus. Slouží jako brána, ze které budou probíhat všechny interakce s knihovnou.
Odesílatel služby Service Bus je vymezený na konkrétní frontu nebo téma a vytvoří se pomocí klienta Služby Service Bus. Odesílatel umožňuje odesílat zprávy do fronty nebo tématu. Umožňuje také plánování zpráv, které mají být k dispozici k doručení k určitému datu.
Příjemce služby Service Bus je vymezený na konkrétní frontu nebo předplatné a vytvoří se pomocí klienta Služby Service Bus. Příjemce umožňuje přijímat zprávy z fronty nebo odběru. Umožňuje také vyřídit zprávy po jejich přijetí. Existují čtyři způsoby, jak zprávy vyřešit:
- Dokončeno – způsobí odstranění zprávy z fronty nebo tématu.
- Opuštění – uvolní zámek příjemce zprávy, což umožňuje přijetí zprávy ostatními příjemci.
- Odložení – normálním způsobem odloží přijetí zprávy. Aby bylo možné přijímat odložené zprávy, musí být pořadové číslo zprávy zachováno.
- DeadLetter – přesune zprávu do fronty nedoručených zpráv. Tím zabráníte opětovnému přijetí zprávy. Aby bylo možné přijímat zprávy z fronty nedoručených zpráv, je potřeba příjemce vymezený na frontu nedoručených zpráv.
Příjemce relace Service Bus je vymezený na konkrétní frontu nebo předplatné s povolenou relací a vytvoří se pomocí klienta Service Bus. Příjemce relace je téměř shodný se standardním příjemcem s tím rozdílem, že jsou zpřístupněny operace správy relací, které se vztahují pouze na entity s povolenými relacemi. Tyto operace zahrnují získání a nastavení stavu relace a také obnovení zámků relací.
Procesor Service Bus je vymezený na konkrétní frontu nebo předplatné a vytvoří se pomocí klienta Služby Service Bus. Objekt ServiceBusProcessor lze považovat za abstrakci kolem sady přijímačů. Používá model zpětného volání, který umožňuje zadat kód při přijetí zprávy a při výskytu výjimky. Nabízí automatické dokončování zpracovaných zpráv, automatické obnovení zámku zpráv a souběžné spouštění obslužných rutin událostí zadaných uživatelem. Vzhledem k sadě funkcí by to měl být nástroj pro psaní aplikací, které přijímají entity služby Service Bus. ServiceBusReceiver se doporučuje pro složitější scénáře, ve kterých procesor není schopen poskytnout jemně odstupňovanou kontrolu, kterou lze očekávat při přímém použití ServiceBusReceiver.
Procesor relace Service Bus je vymezený na konkrétní frontu nebo předplatné s povolenou relací a vytvoří se pomocí klienta Služby Service Bus. Procesor relací je téměř shodný se standardním procesorem. Rozdíl je v tom, že jsou zpřístupněny operace správy relací, které se vztahují pouze na entity s povolenými relacemi.

Další koncepty a hlubší diskuzi najdete v tématu Pokročilé funkce služby Service Bus.

Životnost klienta

, ServiceBusClientodesílatelé, příjemci a procesory lze bezpečně ukládat do mezipaměti a používat je jako jednoúčel po celou dobu životnosti aplikace, což je osvědčený postup, když se zprávy odesílají nebo přijímají pravidelně. Zodpovídají za efektivní správu využití sítě, procesoru a paměti a pracují na tom, aby během období nečinnosti udržovaly nízké využití.

Tyto typy jsou jednorázové a volání buď DisposeAsync , nebo CloseAsync se vyžaduje k zajištění správného vyčištění síťových prostředků a jiných nespravovaných objektů. Je důležité si uvědomit, že při ServiceBusClient odstranění instance se automaticky zavře a vyčistí všechny odesílatele, příjemce a procesory vytvořené pomocí této instance.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaně používat instance klienta je vždy bezpečné, a to i napříč vlákny.

Další koncepty

Možnosti | klienta Diagnostika | Zesměšňovat

Odeslání a přijetí zprávy

Odesílání zpráv se provádí pomocí ServiceBusSender. Příjem se provádí pomocí ServiceBusReceiver.

string connectionString = "<connection_string>";
string queueName = "<queue_name>";
// since ServiceBusClient implements IAsyncDisposable we create it with "await using"
await using var client = new ServiceBusClient(connectionString);

// create the sender
ServiceBusSender sender = client.CreateSender(queueName);

// create a message that we can send. UTF-8 encoding is used when providing a string.
ServiceBusMessage message = new ServiceBusMessage("Hello world!");

// send the message
await sender.SendMessageAsync(message);

// create a receiver that we can use to receive the message
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// get the message body as a string
string body = receivedMessage.Body.ToString();
Console.WriteLine(body);

Odesílání dávky zpráv

Existují dva způsoby odeslání několika zpráv najednou. První způsob, jak to udělat, používá bezpečné dávkování. Pomocí bezpečného dávkování můžete vytvořit ServiceBusMessageBatch objekt, který vám umožní přidávat zprávy do dávky jednu po druhé pomocí TryAdd metody . Pokud se zpráva nevejde do dávky, TryAdd vrátí hodnotu false.

// add the messages that we plan to send to a local queue
Queue<ServiceBusMessage> messages = new Queue<ServiceBusMessage>();
messages.Enqueue(new ServiceBusMessage("First message"));
messages.Enqueue(new ServiceBusMessage("Second message"));
messages.Enqueue(new ServiceBusMessage("Third message"));

// create a message batch that we can send
// total number of messages to be sent to the Service Bus queue
int messageCount = messages.Count;

// while all messages are not sent to the Service Bus queue
while (messages.Count > 0)
{
    // start a new batch
    using ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();

    // add the first message to the batch
    if (messageBatch.TryAddMessage(messages.Peek()))
    {
        // dequeue the message from the .NET queue once the message is added to the batch
        messages.Dequeue();
    }
    else
    {
        // if the first message can't fit, then it is too large for the batch
        throw new Exception($"Message {messageCount - messages.Count} is too large and cannot be sent.");
    }

    // add as many messages as possible to the current batch
    while (messages.Count > 0 && messageBatch.TryAddMessage(messages.Peek()))
    {
        // dequeue the message from the .NET queue as it has been added to the batch
        messages.Dequeue();
    }

    // now, send the batch
    await sender.SendMessagesAsync(messageBatch);

    // if there are any remaining messages in the .NET queue, the while loop repeats
}

Druhý způsob používá SendMessagesAsync přetížení, které přijímá IEnumerable .ServiceBusMessage Pomocí této metody se pokusíme umístit všechny zadané zprávy do jedné dávky zpráv, kterou odešleme do služby. Pokud jsou zprávy příliš velké a nevejdou se do jedné dávky, operace vyvolá výjimku.

IList<ServiceBusMessage> messages = new List<ServiceBusMessage>();
messages.Add(new ServiceBusMessage("First"));
messages.Add(new ServiceBusMessage("Second"));
// send the messages
await sender.SendMessagesAsync(messages);

Příjem dávky zpráv

// create a receiver that we can use to receive the messages
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
// a batch of messages (maximum of 2 in this case) are received
IReadOnlyList<ServiceBusReceivedMessage> receivedMessages = await receiver.ReceiveMessagesAsync(maxMessages: 2);

// go through each of the messages received
foreach (ServiceBusReceivedMessage receivedMessage in receivedMessages)
{
    // get the message body as a string
    string body = receivedMessage.Body.ToString();
}

Dokončení zprávy

Abychom mohli zprávu z fronty nebo odběru odebrat, můžeme volat metodu CompleteAsync .

string connectionString = "<connection_string>";
string queueName = "<queue_name>";
// since ServiceBusClient implements IAsyncDisposable we create it with "await using"
await using var client = new ServiceBusClient(connectionString);

// create the sender
ServiceBusSender sender = client.CreateSender(queueName);

// create a message that we can send
ServiceBusMessage message = new ServiceBusMessage("Hello world!");

// send the message
await sender.SendMessageAsync(message);

// create a receiver that we can use to receive and settle the message
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// complete the message, thereby deleting it from the service
await receiver.CompleteMessageAsync(receivedMessage);

Opuštění zprávy

Opuštění zprávy uvolní zámek příjemce, který umožňuje přijetí zprávy tímto nebo jiným příjemcem.

ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// abandon the message, thereby releasing the lock and allowing it to be received again by this or other receivers
await receiver.AbandonMessageAsync(receivedMessage);

Odložení zprávy

Odložení zprávy zabrání jejímu opětovnému přijetí pomocí ReceiveMessageAsync metod nebo ReceiveMessagesAsync . Místo toho existují samostatné metody ReceiveDeferredMessageAsync a ReceiveDeferredMessagesAsync pro příjem odložených zpráv.

ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// defer the message, thereby preventing the message from being received again without using
// the received deferred message API.
await receiver.DeferMessageAsync(receivedMessage);

// receive the deferred message by specifying the service set sequence number of the original
// received message
ServiceBusReceivedMessage deferredMessage = await receiver.ReceiveDeferredMessageAsync(receivedMessage.SequenceNumber);

Nedoručených zpráv

Nedoručené zprávy se podobají odložení. Jeden hlavní rozdíl spočívá v tom, že služba po určitém počtu přijetí zpráv automaticky odešle nedoručené zprávy. Aplikace můžou na základě svých požadavků zvolit ruční zasílání nedoručených zpráv. Když je zpráva nedoručené, ve skutečnosti se přesune do podnabídky původní fronty. Všimněte si, že ServiceBusReceiver se používá k příjmu zpráv z podpřísežné fronty nedoručených zpráv bez ohledu na to, jestli je hlavní fronta povolená relace.

ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// Dead-letter the message, thereby preventing the message from being received again without receiving from the dead letter queue.
// We can optionally pass a dead letter reason and dead letter description to further describe the reason for dead-lettering the message.
await receiver.DeadLetterMessageAsync(receivedMessage, "sample reason", "sample description");

// receive the dead lettered message with receiver scoped to the dead letter queue.
ServiceBusReceiver dlqReceiver = client.CreateReceiver(queueName, new ServiceBusReceiverOptions
{
    SubQueue = SubQueue.DeadLetter
});
ServiceBusReceivedMessage dlqMessage = await dlqReceiver.ReceiveMessageAsync();

// The reason and the description that we specified when dead-lettering the message will be available in the received dead letter message.
string reason = dlqMessage.DeadLetterReason;
string description = dlqMessage.DeadLetterErrorDescription;

Další informace najdete v přehledu front nedoručených zpráv ServiceBus.

Použití procesoru

Objekt ServiceBusProcessor lze považovat za abstrakci kolem sady přijímačů. Používá model zpětného volání, který umožňuje zadat kód při přijetí zprávy a při výskytu výjimky. Nabízí automatické dokončování zpracovaných zpráv, automatické obnovení zámku zpráv a souběžné spouštění obslužných rutin událostí zadaných uživatelem. Vzhledem k sadě funkcí by to měl být nástroj pro psaní aplikací, které přijímají entity služby Service Bus. ServiceBusReceiver se doporučuje pro složitější scénáře, ve kterých procesor není schopen poskytnout jemně odstupňovanou kontrolu, kterou lze očekávat při přímém použití ServiceBusReceiver.

string connectionString = "<connection_string>";
string queueName = "<queue_name>";
// since ServiceBusClient implements IAsyncDisposable we create it with "await using"
await using var client = new ServiceBusClient(connectionString);

// create the sender
ServiceBusSender sender = client.CreateSender(queueName);

// create a set of messages that we can send
ServiceBusMessage[] messages = new ServiceBusMessage[]
{
    new ServiceBusMessage("First"),
    new ServiceBusMessage("Second")
};

// send the message batch
await sender.SendMessagesAsync(messages);

// create the options to use for configuring the processor
var options = new ServiceBusProcessorOptions
{
    // By default or when AutoCompleteMessages is set to true, the processor will complete the message after executing the message handler
    // Set AutoCompleteMessages to false to [settle messages](/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock) on your own.
    // In both cases, if the message handler throws an exception without settling the message, the processor will abandon the message.
    AutoCompleteMessages = false,

    // I can also allow for multi-threading
    MaxConcurrentCalls = 2
};

// create a processor that we can use to process the messages
await using ServiceBusProcessor processor = client.CreateProcessor(queueName, options);

// configure the message and error handler to use
processor.ProcessMessageAsync += MessageHandler;
processor.ProcessErrorAsync += ErrorHandler;

async Task MessageHandler(ProcessMessageEventArgs args)
{
    string body = args.Message.Body.ToString();
    Console.WriteLine(body);

    // we can evaluate application logic and use that to determine how to settle the message.
    await args.CompleteMessageAsync(args.Message);
}

Task ErrorHandler(ProcessErrorEventArgs args)
{
    // the error source tells me at what point in the processing an error occurred
    Console.WriteLine(args.ErrorSource);
    // the fully qualified namespace is available
    Console.WriteLine(args.FullyQualifiedNamespace);
    // as well as the entity path
    Console.WriteLine(args.EntityPath);
    Console.WriteLine(args.Exception.ToString());
    return Task.CompletedTask;
}

// start processing
await processor.StartProcessingAsync();

// since the processing happens in the background, we add a Console.ReadKey to allow the processing to continue until a key is pressed.
Console.ReadKey();

Ověřování pomocí Azure.Identity

Knihovna identit Azure poskytuje jednoduchou podporu azure Active Directory pro ověřování.

// Create a ServiceBusClient that will authenticate through Active Directory
string fullyQualifiedNamespace = "yournamespace.servicebus.windows.net";
await using var client = new ServiceBusClient(fullyQualifiedNamespace, new DefaultAzureCredential());

Práce s relacemi

Relace poskytují mechanismus pro seskupování souvisejících zpráv. Abyste mohli relace používat, musíte pracovat s entitou s povolenou relací.

Řešení potíží

Projděte si průvodce odstraňováním potíží se službou Service Bus.

Další kroky

Kromě probíraných úvodních scénářů nabízí klientská knihovna Azure Service Bus podporu pro další scénáře, které vám pomůžou využít úplnou sadu funkcí služby Azure Service Bus. Abychom vám pomohli prozkoumat některé z těchto scénářů, nabízí klientská knihovna služby Service Bus projekt ukázek, které budou sloužit jako ilustrace pro běžné scénáře. Podrobnosti najdete v souboru README s ukázkami .

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Další informace najdete v našem průvodci přispívání .

Imprese

Sdílet prostřednictvím