Azure Service Bus klientbibliotek för .NET – version 7.13.1

Azure Service Bus kan du skapa program som drar nytta av asynkrona meddelandemönster med hjälp av en mycket tillförlitlig tjänst för att förmedla meddelanden mellan producenter och konsumenter. Azure Service Bus tillhandahåller flexibla, asynkrona meddelanden mellan klient och server, tillsammans med strukturerade fifo-meddelanden (first-in, first-out) och funktioner för publicering/prenumeration med komplex routning. Om du vill veta mer om Azure Service Bus kanske du vill granska: Vad är Azure Service Bus?

Använd klientbiblioteket för Azure Service Bus för att:

• Överföra affärsdata: Använd meddelanden för varaktigt utbyte av information, till exempel försäljnings- eller inköpsorder, journaler eller lagerförflyttningar.

• Frikoppla program: förbättra tillförlitligheten och skalbarheten för program och tjänster, lindra avsändare och mottagare av behovet av att vara online samtidigt.

• Kontrollera hur meddelanden bearbetas: stöd för traditionella konkurrerande konsumenter för meddelanden som använder köer eller ge varje konsument sin egen instans av ett meddelande med hjälp av ämnen och prenumerationer.

• Implementera komplexa arbetsflöden: meddelandesessioner stöder scenarier som kräver meddelandeordning eller meddelandeförseläggande.

Källkod | Paket (NuGet) | API-referensdokumentation | Produktdokumentation | Migreringsguide | Felsökningsguide

Komma igång

Förutsättningar

• Microsoft Azure-prenumeration: Om du vill använda Azure-tjänster, inklusive Azure Service Bus, behöver du en prenumeration. Om du inte har ett befintligt Azure-konto kan du registrera dig för en kostnadsfri utvärderingsversion eller använda dina MSDN-prenumerantförmåner när du skapar ett konto.

• Service Bus-namnområde: Om du vill interagera med Azure Service Bus måste du också ha ett namnområde tillgängligt. Om du inte är bekant med att skapa Azure-resurser kan du följa den stegvisa guiden för att skapa ett Service Bus-namnområde med hjälp av Azure Portal. Där finns även detaljerade instruktioner för hur du använder Azure CLI-, Azure PowerShell- eller Azure Resource Manager-mallar (ARM) för att skapa en Service Bus-entitet.

• C# 8.0: Azure Service Bus-klientbiblioteket använder nya funktioner som introducerades i C# 8.0. För att kunna dra nytta av C# 8.0-syntaxen rekommenderar vi att du kompilerar med .NET Core SDK 3.0 eller senare med en språkversion av latest.

  Visual Studio-användare som vill dra full nytta av C# 8.0-syntaxen måste använda Visual Studio 2019 eller senare. Visual Studio 2019, inklusive den kostnadsfria Community Edition, kan laddas ned här. Användare av Visual Studio 2017 kan dra nytta av C# 8-syntaxen genom att använda NuGet-paketet Microsoft.Net.Compilers och ange språkversionen, även om redigeringsupplevelsen kanske inte är idealisk.

  Du kan fortfarande använda biblioteket med tidigare C#-språkversioner, men du måste hantera asynkrona uppräkningsbara och asynkrona engångsmedlemmar manuellt i stället för att dra nytta av den nya syntaxen. Du kan fortfarande rikta in dig på alla ramverksversioner som stöds av .NET Core SDK, inklusive tidigare versioner av .NET Core eller .NET Framework. Mer information finns i: så här anger du målramverk.

  Viktigt: För att skapa eller köra exemplen och exemplen utan ändring är det obligatoriskt att använda C# 8.0. Du kan fortfarande köra exemplen om du bestämmer dig för att justera dem för andra språkversioner.

Om du snabbt vill skapa nödvändiga Service Bus-resurser i Azure och ta emot en anslutningssträng för dem kan du distribuera vår exempelmall genom att klicka på:

Installera paketet

Installera Azure Service Bus-klientbiblioteket för .NET med NuGet:

dotnet add package Azure.Messaging.ServiceBus

Autentisera klienten

För att Service Bus-klientbiblioteket ska kunna interagera med en kö eller ett ämne måste det förstå hur du ansluter och auktoriserar med det. Det enklaste sättet att göra detta är att använda en anslutningssträng, som skapas automatiskt när du skapar ett Service Bus-namnområde. Om du inte är bekant med principer för delad åtkomst i Azure kanske du vill följa den stegvisa guiden för att hämta en Service Bus-anslutningssträng.

När du har en anslutningssträng kan du autentisera klienten med den.

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

Om du vill se hur du autentiserar med Azure.Identity kan du se det här exemplet.

Om du vill se hur du initierar anslutningen med en anpassad slutpunkt kan du visa det här exemplet.

ASP.NET Core

Om du vill mata in ServiceBusClient som ett beroende i en ASP.NET Core app installerar du Azure-klientbiblioteksintegrering för ASP.NET Core-paketet.

dotnet add package Microsoft.Extensions.Azure

Registrera sedan klienten i Startup.ConfigureServices -metoden:

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

Om du vill använda koden ovan lägger du till detta i konfigurationen:

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

Mer information finns i Beroendeinmatning med Azure SDK för .NET.

Viktiga begrepp

När du har initierat en ServiceBusClientkan du interagera med de primära resurstyperna i ett Service Bus-namnområde, där flera kan finnas och där den faktiska meddelandeöverföringen sker, namnområdet som ofta fungerar som en programcontainer:

• Kö: Tillåter att meddelanden skickas och tas emot. Används ofta för punkt-till-punkt-kommunikation.

• Ämne: I motsats till köer är ämnen bättre lämpade för publicerings-/prenumerationsscenarier. Ett ämne kan skickas till, men kräver en prenumeration, där det kan finnas flera parallellt, att använda från.

• Prenumeration: Mekanismen för att använda från ett ämne. Varje prenumeration är oberoende och tar emot en kopia av varje meddelande som skickas till ämnet. Regler och filter kan användas för att skräddarsy vilka meddelanden som tas emot av en specifik prenumeration.

Mer information om dessa resurser finns i Vad är Azure Service Bus?.

För att interagera med dessa resurser bör man känna till följande SDK-begrepp:

• En Service Bus-klient är det primära gränssnittet för utvecklare som interagerar med Service Bus-klientbiblioteket. Den fungerar som den gateway från vilken all interaktion med biblioteket sker.

• En Service Bus-avsändare är begränsad till en viss kö eller ett visst ämne och skapas med service bus-klienten. Med avsändaren kan du skicka meddelanden till en kö eller ett ämne. Det gör det också möjligt att schemalägga meddelanden för leverans vid ett angivet datum.

• En Service Bus-mottagare är begränsad till en viss kö eller prenumeration och skapas med service bus-klienten. Med mottagaren kan du ta emot meddelanden från en kö eller prenumeration. Det gör också att meddelandena kan åtgärdas när de har tagits emot. Det finns fyra sätt att lösa meddelanden:

  • Slutfört – gör att meddelandet tas bort från kön eller ämnet.
  • Avbryt – släpper mottagarens lås på meddelandet så att meddelandet kan tas emot av andra mottagare.
  • Skjut upp – skjuter upp meddelandet från att tas emot på normalt sätt. För att kunna ta emot uppskjutna meddelanden måste sekvensnumret för meddelandet behållas.
  • DeadLetter – flyttar meddelandet till kön För obeställbara brev. Detta förhindrar att meddelandet tas emot igen. För att kunna ta emot meddelanden från kön För obeställbara brev krävs en mottagare som är begränsad till kön För obeställbara brev.

• En Service Bus-sessionsmottagare är begränsad till en viss sessionsaktiverad kö eller prenumeration och skapas med Service Bus-klienten. Sessionsmottagaren är nästan identisk med standardmottagaren, och skillnaden är att sessionshanteringsåtgärder exponeras som endast gäller för sessionsaktiverade entiteter. Dessa åtgärder omfattar att hämta och ange sessionstillstånd samt förnya sessionslås.

• En Service Bus-processor är begränsad till en viss kö eller prenumeration och skapas med service bus-klienten. Kan ServiceBusProcessor ses som en abstraktion runt en uppsättning mottagare. Den använder en motringningsmodell för att tillåta att kod anges när ett meddelande tas emot och när ett undantag inträffar. Den erbjuder automatisk slutförande av bearbetade meddelanden, automatisk förnyelse av meddelandelås och samtidig körning av användardefinierade händelsehanterare. På grund av dess funktionsuppsättning bör det vara verktyget gå till för att skriva program som tar emot från Service Bus-entiteter. ServiceBusReceiver rekommenderas för mer komplexa scenarier där processorn inte kan ge den detaljerade kontroll som man kan förvänta sig när du använder ServiceBusReceiver direkt.

• En Service Bus-sessionsprocessor är begränsad till en viss sessionsaktiverad kö eller prenumeration och skapas med Service Bus-klienten. Sessionsprocessorn är nästan identisk med standardprocessorn, och skillnaden är att sessionshanteringsåtgärder exponeras som endast gäller för sessionsaktiverade entiteter.

Fler begrepp och djupare diskussion finns i: Avancerade funktioner i Service Bus.

Klientlivslängd

Avsändare ServiceBusClient, mottagare och processorer är säkra att cachelagrar och använder som en singleton under programmets livslängd, vilket är bästa praxis när meddelanden skickas eller tas emot regelbundet. De ansvarar för effektiv hantering av nätverks-, CPU- och minnesanvändning och arbetar för att hålla användningen låg under perioder av inaktivitet.

Dessa typer är disponibla och anropar antingen DisposeAsync eller CloseAsync krävs för att säkerställa att nätverksresurser och andra ohanterade objekt rensas korrekt. Observera att när en ServiceBusClient instans tas bort stängs och rensas automatiskt alla avsändare, mottagare och processorer som har skapats med den.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Diagnostik | Gäckande

Exempel

• Skicka och ta emot ett meddelande
• Skicka en batch med meddelanden
• Ta emot en batch med meddelanden
• Slutför ett meddelande
• Överge ett meddelande
• Skjut upp ett meddelande
• Obeställbara meddelanden
• Använda processorn
• Autentisera med Azure.Identity
• Arbeta med sessioner
• Fler exempel

Skicka och ta emot ett meddelande

Meddelandesändning utförs med hjälp av ServiceBusSender. Mottagande utförs med hjälp av 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);

Skicka en batch med meddelanden

Det finns två sätt att skicka flera meddelanden samtidigt. Det första sättet att göra detta är att använda säker batchbearbetning. Med säker batchbearbetning kan du skapa ett ServiceBusMessageBatch -objekt, vilket gör att du kan försöka lägga till meddelanden en i taget till batchen TryAdd med hjälp av metoden . Om meddelandet inte får plats i batchen TryAdd returneras falskt.

// 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
}

Det andra sättet använder överlagringen SendMessagesAsync som accepterar en IEnumerable för ServiceBusMessage. Med den här metoden försöker vi anpassa alla angivna meddelanden i en enda meddelandebatch som vi ska skicka till tjänsten. Om meddelandena är för stora för att få plats i en enda batch utlöser åtgärden ett undantag.

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

Ta emot en batch med meddelanden

// 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();
}

Slutför ett meddelande

För att ta bort ett meddelande från en kö eller prenumeration kan vi anropa CompleteAsync metoden .

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);

Överge ett meddelande

Om du överger ett meddelande frigörs mottagarens lås, vilket gör att meddelandet kan tas emot av den här eller andra mottagare.

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);

Skjut upp ett meddelande

Om du skjuter upp ett meddelande förhindras det från att tas emot igen med metoderna ReceiveMessageAsync eller ReceiveMessagesAsync . Det finns i stället separata metoder ReceiveDeferredMessageAsync och ReceiveDeferredMessagesAsync för att ta emot uppskjutna meddelanden.

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);

Obeställbara meddelanden

Obeställbara meddelanden liknar att skjuta upp med en stor skillnad eftersom meddelanden automatiskt kommer att skrivas ut av tjänsten efter att de har tagits emot ett visst antal gånger. Program kan välja att manuellt skicka meddelanden med obeställbara meddelanden baserat på deras krav. När ett meddelande är obeställt flyttas det faktiskt till en underfråga av den ursprungliga kön. Observera att ServiceBusReceiver används för att ta emot meddelanden från underfrågan med obeställbara meddelanden oavsett om huvudkön är sessionsaktiverad eller inte.

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;

Mer information finns i översikten över Köer med obeställbara ServiceBus-meddelanden.

Använda processorn

ServiceBusProcessor kan betraktas som en abstraktion runt en uppsättning mottagare. Den använder en motringningsmodell för att tillåta att kod anges när ett meddelande tas emot och när ett undantag inträffar. Den erbjuder automatiskt slutförande av bearbetade meddelanden, automatisk förnyelse av meddelandelås och samtidig körning av användardefinierade händelsehanterare. På grund av dess funktionsuppsättning bör det vara verktyget gå till för att skriva program som tar emot från Service Bus-entiteter. ServiceBusReceiver rekommenderas för mer komplexa scenarier där processorn inte kan ge den detaljerade kontroll som man kan förvänta sig när du använder ServiceBusReceiver direkt.

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();

Autentisera med Azure.Identity

Azure Identity-biblioteket tillhandahåller enkelt Azure Active Directory-stöd för autentisering.

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

Arbeta med sessioner

Sessioner ger en mekanism för att gruppera relaterade meddelanden. För att kunna använda sessioner måste du arbeta med en sessionsaktiverad entitet.

• Skicka och ta emot sessionsmeddelanden
• Använda sessionsprocessorn

Felsökning

Se felsökningsguiden för Service Bus.

Nästa steg

Utöver de inledande scenarier som diskuteras erbjuder Azure Service Bus-klientbiblioteket stöd för ytterligare scenarier för att dra nytta av den fullständiga funktionsuppsättningen i Azure Service Bus-tjänsten. För att hjälpa till att utforska några av dessa scenarier erbjuder Service Bus-klientbiblioteket ett projekt med exempel som fungerar som en illustration för vanliga scenarier. Mer information finns i README-exempel .

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Mer information finns i vår bidragsguide .