Wyjątki obsługi komunikatów usługi Service Bus (przestarzałe)

W tym artykule wymieniono wyjątki platformy .NET wygenerowane przez interfejsy API programu .NET Framework.

30 września 2026 r. wycofamy biblioteki zestawu SDK usługi Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus i com.microsoft.azure.servicebus, które nie są zgodne z wytycznymi dotyczącymi zestawu Azure SDK. Zakończymy również obsługę protokołu SBMP, więc nie będzie można już używać tego protokołu po 30 września 2026 r. Przeprowadź migrację do najnowszych bibliotek zestawu Azure SDK, które oferują krytyczne aktualizacje zabezpieczeń i ulepszone możliwości przed tą datą.

Mimo że starsze biblioteki mogą być nadal używane poza 30 września 2026 r., nie będą już otrzymywać oficjalnej pomocy technicznej i aktualizacji od firmy Microsoft. Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu pomocy technicznej.

Kategorie wyjątków

Interfejsy API obsługi komunikatów generują wyjątki, które mogą należeć do następujących kategorii, wraz ze skojarzona akcjami, które można wykonać, aby spróbować je naprawić. Znaczenie i przyczyny wyjątku mogą się różnić w zależności od typu jednostki obsługi komunikatów:

1. Błąd kodowania użytkownika (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). Akcja ogólna: spróbuj naprawić kod przed kontynuowaniem.
2. Błąd setup/configuration (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. Akcja ogólna: przejrzyj konfigurację i w razie potrzeby zmień.
3. Wyjątki przejściowe (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Akcja ogólna: spróbuj ponownie wykonać operację lub powiadomić użytkowników. Klasę RetryPolicy w zestawie SDK klienta można skonfigurować do automatycznego obsługi ponownych prób. Aby uzyskać więcej informacji, zobacz Wskazówki dotyczące ponawiania prób.
4. Inne wyjątki (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). Akcja ogólna: specyficzna dla typu wyjątku; zapoznaj się z tabelą w następującej sekcji:

Ważne

• Usługa Azure Service Bus nie ponawia próby wykonania operacji w przypadku wyjątku, gdy operacja znajduje się w zakresie transakcji.
• Aby uzyskać wskazówki dotyczące ponawiania prób specyficznych dla usługi Azure Service Bus, zobacz Wskazówki dotyczące ponawiania prób dla usługi Service Bus.

Typy wyjątków

W poniższej tabeli wymieniono typy wyjątków obsługi komunikatów oraz ich przyczyny oraz sugerowane działania, które można wykonać.

Typ wyjątku	Opis/przyczyna/przykłady	Sugerowana akcja	Uwaga dotycząca automatycznego/natychmiastowego ponawiania próby
TimeoutException	Serwer nie odpowiedział na żądaną operację w określonym czasie, która jest kontrolowana przez operację OperationTimeout. Serwer mógł ukończyć żądaną operację. Może się to zdarzyć z powodu opóźnień sieci lub innej infrastruktury.	Sprawdź stan systemu pod kątem spójności i spróbuj ponownie, jeśli to konieczne. Zobacz Wyjątki limitu czasu.	Ponów próbę może pomóc w niektórych przypadkach; dodaj logikę ponawiania prób do kodu.
InvalidOperationException	Żądana operacja użytkownika nie jest dozwolona na serwerze ani w usłudze. Aby uzyskać szczegółowe informacje, zobacz komunikat o wyjątku. Na przykład Complete() generuje ten wyjątek, jeśli komunikat został odebrany w trybie ReceiveAndDelete.	Sprawdź kod i dokumentację. Upewnij się, że żądana operacja jest prawidłowa.	Ponawianie próby nie pomaga.
Operationcanceledexception	Podjęto próbę wywołania operacji na obiekcie, który został już zamknięty, przerwany lub usunięty. W rzadkich przypadkach transakcja otoczenia jest już usuwana.	Sprawdź kod i upewnij się, że nie wywołuje operacji na usuniętym obiekcie.	Ponawianie próby nie pomaga.
Unauthorizedaccessexception	Obiekt TokenProvider nie może uzyskać tokenu, token jest nieprawidłowy lub token nie zawiera oświadczeń wymaganych do wykonania operacji.	Upewnij się, że dostawca tokenu został utworzony przy użyciu poprawnych wartości. Sprawdź konfigurację usługi kontroli dostępu.	Ponów próbę może pomóc w niektórych przypadkach; dodaj logikę ponawiania prób do kodu.
ArgumentException Argumentnullexception ArgumentOutOfRangeException	Co najmniej jeden argument dostarczony do metody jest nieprawidłowy. Identyfikator URI dostarczony do elementu NamespaceManager lub Create zawiera segmenty ścieżki. Schemat identyfikatora URI dostarczony do elementu NamespaceManager lub Create jest nieprawidłowy. Wartość właściwości jest większa niż 32 KB.	Sprawdź kod wywołujący i upewnij się, że argumenty są poprawne.	Ponawianie próby nie pomaga.
MessagingEntityNotFoundException	Jednostka skojarzona z operacją nie istnieje lub została usunięta.	Upewnij się, że jednostka istnieje.	Ponawianie próby nie pomaga.
MessageNotFoundException	Spróbuj odebrać komunikat z określonym numerem sekwencji. Nie można odnaleźć tego komunikatu.	Upewnij się, że wiadomość nie została już odebrana. Sprawdź kolejkę deadletter, aby sprawdzić, czy komunikat został utracony.	Ponawianie próby nie pomaga.
MessagingCommunicationException	Klient nie może nawiązać połączenia z usługą Service Bus.	Upewnij się, że podana nazwa hosta jest poprawna, a host jest osiągalny. Jeśli kod działa w środowisku z zaporą/serwerem proxy, upewnij się, że ruch do domeny/adresu IP usługi Service Bus i portów nie jest blokowany.	Ponów próbę może pomóc, jeśli występują sporadyczne problemy z łącznością.
ServerBusyException	Usługa nie może obecnie przetworzyć żądania.	Klient może czekać przez pewien czas, a następnie ponowić próbę wykonania operacji.	Klient może ponowić próbę po pewnym interwale. Jeśli ponowienie próby spowoduje wystąpienie innego wyjątku, sprawdź zachowanie ponawiania próby dla tego wyjątku.
MessagingException	Ogólny wyjątek obsługi komunikatów, który może zostać zgłoszony w następujących przypadkach: Podjęto próbę utworzenia obiektu QueueClient przy użyciu nazwy lub ścieżki należącej do innego typu jednostki (na przykład tematu). Podjęto próbę wysłania komunikatu o rozmiarze większym niż 256 KB. Serwer lub usługa napotkała błąd podczas przetwarzania żądania. Aby uzyskać szczegółowe informacje, zobacz komunikat o wyjątku. Zazwyczaj jest to wyjątek przejściowy. Żądanie zostało zakończone, ponieważ jednostka jest ograniczana. Kod błędu: 50001, 50002, 50008.	Sprawdź kod i upewnij się, że dla treści komunikatu są używane tylko obiekty możliwe do serializacji (lub użyj niestandardowego serializatora). Zapoznaj się z dokumentacją obsługiwanych typów wartości właściwości i użyj tylko obsługiwanych typów. Sprawdź właściwość IsTransient. Jeśli to prawda, możesz ponowić próbę wykonania operacji.	Jeśli wyjątek jest spowodowany ograniczaniem przepustowości, poczekaj kilka sekund i spróbuj ponownie wykonać operację. Zachowanie ponawiania prób jest niezdefiniowane i może nie pomóc w innych scenariuszach.
MessagingEntityAlreadyExistsException	Spróbuj utworzyć jednostkę o nazwie, która jest już używana przez inną jednostkę w tej przestrzeni nazw usługi.	Usuń istniejącą jednostkę lub wybierz inną nazwę jednostki do utworzenia.	Ponawianie próby nie pomaga.
Quotaexceededexception	Jednostka obsługi komunikatów osiągnęła maksymalny dozwolony rozmiar lub przekroczono maksymalną liczbę połączeń z przestrzenią nazw.	Utwórz miejsce w jednostce, odbierając komunikaty z jednostki lub jej podzapytania. Zobacz QuotaExceededException.	Ponów próbę może pomóc, jeśli komunikaty zostały usunięte w międzyczasie.
RuleActionException	Usługa Service Bus zwraca ten wyjątek, jeśli próbujesz utworzyć nieprawidłową akcję reguły. Usługa Service Bus dołącza ten wyjątek do komunikatu nieaktywnego, jeśli wystąpi błąd podczas przetwarzania akcji reguły dla tego komunikatu.	Sprawdź akcję reguły, aby uzyskać poprawność.	Ponawianie próby nie pomaga.
FilterException	Usługa Service Bus zwraca ten wyjątek w przypadku próby utworzenia nieprawidłowego filtru. Usługa Service Bus dołącza ten wyjątek do komunikatu nieużywanego, jeśli wystąpił błąd podczas przetwarzania filtru dla tego komunikatu.	Sprawdź filtr pod kątem poprawności.	Ponawianie próby nie pomaga.
SessionCannotBeLockedException	Próba zaakceptowania sesji z określonym identyfikatorem sesji, ale sesja jest obecnie zablokowana przez innego klienta.	Upewnij się, że sesja jest odblokowana przez innych klientów.	Ponów próbę może pomóc, jeśli sesja została zwolniona w międzyczasie.
TransactionSizeExceededException	Zbyt wiele operacji jest częścią transakcji.	Zmniejsz liczbę operacji, które są częścią tej transakcji.	Ponawianie próby nie pomaga.
MessagingEntityDisabledException	Żądanie wykonania operacji na wyłączonej jednostce.	Aktywuj jednostkę.	Ponów próbę może pomóc, jeśli jednostka została aktywowana w międzyczasie.
NoMatchingSubscriptionException	Usługa Service Bus zwraca ten wyjątek w przypadku wysłania komunikatu do tematu, który ma włączone wstępne filtrowanie i żaden z filtrów nie jest zgodny.	Upewnij się, że co najmniej jeden filtr jest zgodny.	Ponawianie próby nie pomaga.
MessageSizeExceededException	Ładunek komunikatu przekracza limit 256 KB. Limit 256 KB to całkowity rozmiar komunikatu, który może obejmować właściwości systemu i wszelkie obciążenie platformy .NET.	Zmniejsz rozmiar ładunku komunikatu, a następnie spróbuj ponownie wykonać operację.	Ponawianie próby nie pomaga.
Transactionexception	Transakcja otoczenia (Transaction.Current) jest nieprawidłowa. Mógł zostać ukończony lub przerwany. Wyjątek wewnętrzny może zawierać dodatkowe informacje.		Ponawianie próby nie pomaga.
Transactionindoubtexception	Operacja jest podejmowana na transakcji, która jest wątpliwa lub próbuje zatwierdzić transakcję, a transakcja staje się wątpliwa.	Aplikacja musi obsługiwać ten wyjątek (jako specjalny przypadek), ponieważ transakcja mogła już zostać zatwierdzona.	-

Quotaexceededexception

Wyjątek QuotaExceededException wskazuje, że przekroczono limit przydziału dla określonej jednostki.

Uwaga

Aby zapoznać się z limitami przydziału usługi Service Bus, zobacz Limity przydziału.

Kolejki i tematy

W przypadku kolejek i tematów często jest to rozmiar kolejki. Właściwość komunikatu o błędzie zawiera dalsze szczegóły, jak w poniższym przykładzie:

Microsoft.ServiceBus.Messaging.QuotaExceededException
Message: The maximum entity size has been reached or exceeded for Topic: 'xxx-xxx-xxx'. 
    Size of entity in bytes:1073742326, Max entity size in bytes:
1073741824..TrackingId:xxxxxxxxxxxxxxxxxxxxxxxxxx, TimeStamp:3/15/2013 7:50:18 AM

Komunikat informuje, że temat przekroczył limit rozmiaru, w tym przypadku 1 GB (domyślny limit rozmiaru).

Przestrzenie nazw

W przypadku przestrzeni nazw wyjątek QuotaExceededException może wskazywać, że aplikacja przekroczyła maksymalną liczbę połączeń z przestrzenią nazw. Przykład:

Microsoft.ServiceBus.Messaging.QuotaExceededException: ConnectionsQuotaExceeded for namespace xxx.
<tracking-id-guid>_G12 ---> 
System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: 
ConnectionsQuotaExceeded for namespace xxx.

Typowe przyczyny

Istnieją dwie typowe przyczyny tego błędu: kolejka utraconych komunikatów i niefunkcjonujące odbiorniki komunikatów.

1. Kolejka utraconych komunikatów Czytnik kończy się niepowodzeniem, a komunikaty są zwracane do kolejki/tematu po wygaśnięciu blokady. Może się to zdarzyć, jeśli czytelnik napotka wyjątek uniemożliwiający wywołanie brokeredMessage.Complete. Po odczytaniu komunikatu 10 razy domyślnie przechodzi do kolejki utraconych komunikatów. To zachowanie jest kontrolowane przez właściwość QueueDescription.MaxDeliveryCount i ma wartość domyślną 10. W miarę stosu komunikatów w kolejce utraconych wiadomości zajmują miejsce.

   Aby rozwiązać ten problem, przeczytaj i ukończ komunikaty z kolejki utraconych komunikatów, tak jak w przypadku każdej innej kolejki. Możesz użyć metody FormatDeadLetterPath , aby ułatwić formatowanie ścieżki kolejki utraconych komunikatów.

2. Odbiornik został zatrzymany. Odbiorca przestał odbierać komunikaty z kolejki lub subskrypcji. Sposobem identyfikacji jest przyjrzenie się właściwości QueueDescription.MessageCountDetails , która pokazuje pełny podział komunikatów. Jeśli właściwość ActiveMessageCount jest wysoka lub rośnie, komunikaty nie są odczytywane tak szybko, jak są zapisywane.

TimeoutException

Wyjątek TimeoutException zazwyczaj wskazuje na to, że operacja zainicjowana przez użytkownika zajmuje więcej czasu niż wynosi limit czasu dla operacji.

Należy sprawdzić wartość właściwości ServicePointManager.Default Połączenie ionLimit, ponieważ przekroczenie tego limitu może również spowodować wyjątek TimeoutException.

Oczekuje się, że przekroczenia limitów czasu będą mieć miejsce podczas operacji konserwacji lub między nimi, takich jak aktualizacje usługi Service Bus (lub) aktualizacje systemu operacyjnego dotyczące zasobów, na których jest uruchamiana usługa. Podczas aktualizacji systemu operacyjnego jednostki są przenoszone, a węzły aktualizowane lub ponownie uruchamiane, co może powodować przekraczanie limitów czasu. Aby uzyskać szczegółowe informacje o umowie dotyczącej poziomu usługi (SLA) dla usługi Azure Service Bus, zobacz Umowa SLA dla usługi Service Bus.

Kolejki i tematy

W przypadku kolejek i tematów limit czasu jest określony w elemecie MessagingFactory Ustawienia. Właściwość OperationTimeout, w ramach parametry połączenia lub za pośrednictwem serviceBus Połączenie ionStringBuilder. Sam komunikat o błędzie może się różnić, ale zawsze zawiera wartość limitu czasu określoną dla bieżącej operacji.

MessageLockLostException

Przyczyna

Komunikat MessageLockLostException jest zgłaszany po odebraniu komunikatu przy użyciu trybu odbierania PeekLock, a blokada przechowywana przez klienta wygasa po stronie usługi.

Blokada komunikatu może wygasnąć z różnych powodów:

• Czasomierz blokady wygasł przed jego odnowieniem przez aplikację kliencą.
• Aplikacja kliencka uzyskała blokadę, zapisała ją w magazynie trwałym, a następnie została ponownie uruchomiona. Po ponownym uruchomieniu aplikacja kliencka spojrzała na komunikaty inflight i próbowała je ukończyć.

Ten wyjątek może również zostać wyświetlony w następujących scenariuszach:

• Aktualizacja usługi
• Aktualizacja systemu operacyjnego
• Zmiana właściwości jednostki (kolejka, temat, subskrypcja) podczas przechowywania blokady.

Rozwiązanie

Gdy aplikacja kliencka odbiera komunikat MessageLockLostException, nie może już przetworzyć komunikatu. Aplikacja kliencka może opcjonalnie rozważyć rejestrowanie wyjątku do analizy, ale klient musi usunąć komunikat.

Ponieważ blokada komunikatu wygasła, nastąpi powrót do kolejki (lub subskrypcji) i może zostać przetworzona przez następną aplikację kliencką, która wywołuje odbieranie.

Jeśli parametr MaxDeliveryCount został przekroczony, komunikat może zostać przeniesiony do kolejki DeadLetterQueue.

SessionLockLostException

Przyczyna

Wyjątek SessionLockLostException jest zgłaszany po zaakceptowaniu sesji, a blokada przechowywana przez klienta wygasa po stronie usługi.

Blokada sesji może wygasnąć z różnych powodów:

• Czasomierz blokady wygasł przed jego odnowieniem przez aplikację kliencą.
• Aplikacja kliencka uzyskała blokadę, zapisała ją w magazynie trwałym, a następnie została ponownie uruchomiona. Po ponownym uruchomieniu aplikacja kliencka spojrzała na sesje inflight i próbowała przetworzyć komunikaty w tych sesjach.

Ten wyjątek może również zostać wyświetlony w następujących scenariuszach:

• Aktualizacja usługi
• Aktualizacja systemu operacyjnego
• Zmiana właściwości jednostki (kolejka, temat, subskrypcja) podczas przechowywania blokady.

Rozwiązanie

Gdy aplikacja kliencka odbiera wyjątek SessionLockLostException, nie może już przetwarzać komunikatów w sesji. Aplikacja kliencka może rozważyć rejestrowanie wyjątku do analizy, ale klient musi usunąć komunikat.

Ponieważ blokada sesji wygasła, nastąpi powrót do kolejki (lub subskrypcji) i może zostać zablokowana przez następną aplikację kliencką, która akceptuje sesję. Ponieważ blokada sesji jest przechowywana przez jedną aplikację kliencką w danym momencie, gwarantowane jest przetwarzanie w kolejności.

SocketException

Przyczyna

Wyjątek SocketException jest zgłaszany w następujących przypadkach:

• Gdy próba połączenia zakończy się niepowodzeniem, ponieważ host nie odpowiedział prawidłowo po upływie określonego czasu (kod błędu TCP 10060).
• Nawiązane połączenie nie powiodło się, ponieważ nie można odpowiedzieć na połączony host.
• Wystąpił błąd podczas przetwarzania komunikatu lub przekroczenie limitu czasu przez hosta zdalnego.
• Problem z podstawowym zasobem sieci.

Rozwiązanie

Błędy SocketException wskazują, że maszyna wirtualna hostująca aplikacje nie może przekonwertować nazwy <mynamespace>.servicebus.windows.net na odpowiedni adres IP.

Sprawdź, czy następujące polecenie zakończy się pomyślnie mapowaniem na adres IP.

PS C:\> nslookup <mynamespace>.servicebus.windows.net

Które powinny dostarczyć dane wyjściowe, takie jak:

Name:    <cloudappinstance>.cloudapp.net
Address:  XX.XX.XXX.240
Aliases:  <mynamespace>.servicebus.windows.net

Jeśli powyższa nazwa nie jest rozpoznawana jako adres IP i alias przestrzeni nazw, zapoznaj się z administratorem sieci, aby dokładniej zbadać problem. Rozpoznawanie nazw odbywa się za pośrednictwem serwera DNS zazwyczaj zasobu w sieci klienta. Jeśli rozpoznawanie nazw DNS jest wykonywane przez usługę Azure DNS, skontaktuj się z pomoc techniczna platformy Azure.

Jeśli rozpoznawanie nazw działa zgodnie z oczekiwaniami, sprawdź, czy połączenia z usługą Azure Service Bus są dozwolone tutaj.

MessagingException

Przyczyna

MessagingException to ogólny wyjątek, który może zostać zgłoszony z różnych powodów. Oto niektóre z powodów:

• Podjęto próbę utworzenia elementu QueueClient w temacielub subskrypcji.
• Rozmiar wysłanej wiadomości jest większy niż limit dla danej warstwy. Przeczytaj więcej na temat limitów przydziałów i limitów usługi Service Bus.
• Określone żądanie płaszczyzny danych (wysyłanie, odbieranie, kończenie, porzucenie) zostało zakończone z powodu ograniczania przepustowości.
• Przejściowe problemy spowodowane uaktualnieniami i ponownymi uruchomieniami usługi.

Uwaga

Powyższa lista wyjątków nie jest wyczerpująca.

Rozwiązanie

Kroki rozwiązywania zależą od tego, co spowodowało zgłoszenie wyjątku MessagingException .

• W przypadku przejściowych problemów (gdzie parametr isTransient ma wartość true) lub w przypadku problemów z ograniczaniem przepustowości spróbuj ponownie wykonać operację. W tym celu można użyć domyślnych zasad ponawiania prób w zestawie SDK.
• W przypadku innych problemów szczegóły w wyjątku wskazują, że kroki problemu i rozwiązywania problemów można wywnioskować z tego samego.

StorageQuotaExceededException

Przyczyna

Wyjątek StorageQuotaExceededException jest generowany, gdy całkowity rozmiar jednostek w przestrzeni nazw w warstwie Premium przekracza limit 1 TB na jednostkę obsługi komunikatów.

Rozwiązanie

• Zwiększanie liczby jednostek obsługi komunikatów przypisanych do przestrzeni nazw w warstwie Premium
• Jeśli już używasz maksymalnych dozwolonych jednostek obsługi komunikatów dla przestrzeni nazw, utwórz oddzielną przestrzeń nazw.

Następne kroki

Aby uzyskać pełną dokumentację interfejsu API platformy .NET usługi Service Bus, zobacz dokumentację interfejsu API platformy .NET platformy Azure. Aby uzyskać porady dotyczące rozwiązywania problemów, zobacz Przewodnik rozwiązywania problemów.