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 skojarzonymi akcjami, które można podjąć, 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 konfiguracji (ustawień) (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 klient można skonfigurować do automatycznej 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, gdy podczas operacji wystąpi wyjątek, jeśli 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 komunikatów, 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
Wyjątek limitu czasu	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.
Wyjątek 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.
Wyjątek braku autoryzacji dostępu	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.
Wyjątek ArgumentException Wyjątek ArgumentNullException Wyjątek ArgumentOutOfRangeException	Co najmniej jeden argument dostarczony do metody jest nieprawidłowy. Identyfikator URI dostarczony do NamespaceManager lub Create zawiera segmenty ścieżki. Schemat identyfikatora URI dostarczony do NamespaceManager lub funkcji 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ę wiadomości błędnych, aby zobaczyć, czy komunikat został oznaczony jako martwa wiadomość.	Ponawianie próby nie pomaga.
WyjątekKomunikacjiWiadomości	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.	Może pomóc ponowienie próby, 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.
Wyjątek wiadomości	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 zakończono, ponieważ jednostka podlega ograniczeniom. 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 (Przekroczyony limit przydziału)	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.
Wyjątek 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 pod kątem poprawności.	Ponawianie próby nie pomaga.
Wyjątek filtru	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 odrzuconego, 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.	Ponowienie próby może pomóc, jeśli sesja została zwolniona w międzyczasie.
WyjątekPrzekroczeniaRozmiaruTransakcji	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ę.	Ponowienie próby 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.
Wyjątek od transakcji	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 (TransakcjaWątpliwość)	Podejmowana jest operacja na transakcji, która jest wątpliwa, albo podejmowana jest próba zatwierdzenia transakcji i transakcja staje się wątpliwa.	Aplikacja musi obsługiwać ten wyjątek (jako specjalny przypadek), ponieważ transakcja mogła już zostać zatwierdzona.	-

WyjątekPrzekroczeniaLimitu

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

Uwaga / Notatka

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

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. Martwa kolejka komunikatów Czytnik nie może dokończyć przetwarzania komunikatów, 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, która ułatwia formatowanie ścieżki kolejki martwych listó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 wskazuje, że operacja zainicjowana przez użytkownika trwa dłużej niż limit czasu operacji.

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

Oczekuje się, że przerwy czasowe będą występować podczas operacji konserwacji lub pomiędzy nimi, takich jak aktualizacje usługi Service Bus lub aktualizacje systemu operacyjnego dla zasobów, które obsługują usługę. Podczas aktualizacji systemu operacyjnego jednostki są przenoszone, a węzły aktualizowane lub ponownie uruchamiane, co może powodować wystąpienie timeoutu. Aby uzyskać szczegółowe informacje o umowie dotyczącej poziomu usług (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 właściwości MessagingFactorySettings.OperationTimeout, jako część parametrów połączenia lub za pośrednictwem ServiceBusConnectionStringBuilder. Sam komunikat o błędzie może się różnić, ale zawsze zawiera wartość limitu czasu określoną dla bieżącej operacji.

Wyjątek MessageLockLostException

Przyczyna

Wyjątek MessageLockLostException jest generowany, gdy komunikat jest odbierany przy użyciu trybu PeekLock, a blokada utrzymywana 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.

Rezolucja

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 (Utracono blokadę sesji)

Przyczyna

Wyjątek SessionLockLostException jest zgłaszany, gdy sesja jest akceptowana, a blokada przechowywana przez klienta wygasa po stronie serwisu.

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.

Rezolucja

Gdy aplikacja kliencka odbiera SessionLockLostException, nie może już przetwarzać komunikatów w ramach 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.

Wyjątek gniazda

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.

Rezolucja

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 nazwa nie jest rozpoznawana jako adres IP i alias przestrzeni nazw, zapoznaj się z administratorem sieci, aby dokładniej zbadać ten 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.

Wyjątek wiadomości

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 temacie lub subskrypcji.
• Rozmiar wysłanej wiadomości jest większy niż limit dla danej warstwy. Przeczytaj więcej na temat 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 / Notatka

Lista wyjątków nie jest wyczerpująca.

Rezolucja

Kroki rozwiązywania zależą od tego, co spowodowało wywołanie 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ę. Można użyć domyślnych zasad ponawiania prób w zestawie SDK.
• W przypadku innych problemów szczegóły w wyjątku wskazują na problem, a kroki potrzebne do jego rozwiązania można wywnioskować z nich.

Przekroczono limit przestrzeni dyskowej

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.

Rezolucja

• Zwiększ liczbę 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.

Dalsze 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.