服務匯流排傳訊例外狀況 (已被取代)

  • 發行項

本文列出 .NET Framework API 所產生的 .NET 例外狀況。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。 我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。 請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但這些程式庫將無法繼續收到 Microsoft 的官方支援和更新。 如需詳細資訊，請參閱支援淘汰公告。

例外狀況類別

傳訊 API 會產生下列類別的例外狀況，以及可用來嘗試修正它們的相關動作。 例外狀況的原因可能會因為訊息實體的類型而不同：

  1. 使用者程式碼撰寫錯誤 (System.ArgumentException、System.InvalidOperationException、System.OperationCanceledException、System.Runtime.Serialization.SerializationException)。 一般動作：請先嘗試修正此程式碼，再繼續執行。
  2. 設定/組態錯誤 (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException、System.UnauthorizedAccessException)。 一般動作：檢閱您的組態並視需要進行變更。
  3. 暫時性例外狀況 (Microsoft.ServiceBus.Messaging.MessagingException、Microsoft.ServiceBus.Messaging.ServerBusyException、Microsoft.ServiceBus.Messaging.MessagingCommunicationException)。 一般動作：重試此操作或通知使用者。 您可以設定用戶端 SDK 中的 RetryPolicy 類別來自動處理重試。 如需詳細資訊，請參閱重試指引。
  4. 其他例外狀況 (System.Transactions.TransactionException、System.TimeoutException、Microsoft.ServiceBus.Messaging.MessageLockLostException、Microsoft.ServiceBus.Messaging.SessionLockLostException)。 一般動作︰依例外狀況類型而異；請參閱下一節中的表格：

重要

  • 當作業位於交易範圍時，如果發生例外狀況，Azure 服務匯流排不會重試作業。
  • 如需 Azure 服務匯流排專屬的重試指引，請參閱服務匯流排的重試指引。

例外狀況類型

下表列出傳訊例外狀況類型及其原因，並指出您可以採取的建議動作。

例外狀況類型 描述/原因/範例 建議的動作 自動/立即重試附註
TimeoutException 伺服器未在 OperationTimeout 控制的指定時間內回應要求的作業。 伺服器可能已完成要求的作業。 此例外狀況可能是由於網路或其他基礎結構延遲所導致。 檢查系統狀態的一致性，並視需要重試。 請參閱 逾時例外狀況。 在某些情況下，重試也許有幫助；將重試邏輯新增至程式碼。
InvalidOperationException 不允許在伺服器或服務內執行要求的使用者作業。 如需詳細資訊，請參閱例外狀況訊息。 例如，如果是在 ReceiveAndDelete 模式收到訊息，Complete() 將會產生這個例外狀況。 檢查程式碼和文件。 確定要求的作業無效。 重試沒有用。
OperationCanceledException 嘗試在已關閉、中止或處置的物件上叫用作業。 極少數的情況下，環境交易是已處置狀態。 檢查程式碼，確定其不會在已處置物件上叫用作業。 重試沒有用。
UnauthorizedAccessException TokenProvider 物件無法取得權杖、權杖無效，或權杖不包含執行作業所需的宣告。 確定權杖提供者是以正確的值建立。 檢查存取控制服務的組態。 在某些情況下，重試也許有幫助；將重試邏輯新增至程式碼。
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 提供給方法的一個或多個引數無效。
提供給 NamespaceManager 或 Create 的 URI 包含路徑區段。
提供給 NamespaceManager 或 Create 的 URI 配置無效。
屬性值大於 32 KB。		 檢查呼叫程式碼，並確定引數正確無誤。 重試沒有用。
MessagingEntityNotFoundException 與作業相關聯的實體不存在或已遭刪除。 確定實體已存在。 重試沒有用。
MessageNotFoundException 嘗試接收具有特定序號的訊息。 找不到此訊息。 確定尚未收到訊息。 檢查寄不出信件佇列，查看訊息是否已停止傳送。 重試沒有用。
MessagingCommunicationException 用戶端無法建立服務匯流排連線。 確定提供的主機名稱正確，且主機可以連線。

如果您的程式碼在具有防火牆/Proxy 的環境中執行，請確定服務匯流排網域/IP 位址和連接埠的流量不會遭到封鎖。

 如果有間歇性的連線問題，重試也許有幫助。
ServerBusyException 服務目前無法處理要求。 用戶端可以等待一段時間，然後再重試作業。 用戶端可能會在特定間隔後重試。 如果重試產生不同的例外狀況，請檢查該例外狀況的重試行為。
MessagingException 可能會在下列情況中擲回的一般傳訊例外狀況：

利用屬於不同實體類型 (例如主題) 的名稱或路徑嘗試建立 QueueClient 。

嘗試傳送大於 256 KB 的訊息。

處理要求時伺服器或服務發生錯誤。 如需詳細資訊，請參閱例外狀況訊息。 通常為暫時性例外狀況。

要求已終止，因為實體正在受到節流。 錯誤碼：50001、50002、50008。

查看程式碼，並確定訊息內文只使用可序列化的物件 (或使用自訂序列化程式)。

查看文件來了解支援的屬性值類型，並且只使用支援的類型。

查看 IsTransient 屬性。 若為 true，您可以重試作業。

如果例外狀況是由於節流所致，請等待幾秒鐘，然後再次重試作業。 重試行為未定義，而且可能在其他案例中沒有用。
MessagingEntityAlreadyExistsException 嘗試在該服務命名空間中以另一個實體已在使用的名稱建立實體。 刪除現有的實體，或選擇不同的名稱來建立實體。 重試沒有用。
QuotaExceededException 傳訊實體已達到允許的大小上限，或已超過命名空間的連線數目上限。 從實體或其子佇列接收訊息，在實體中建立空間。 請參閱 QuotaExceededException。 如果在此同時已移除訊息，重試可能會有幫助。
RuleActionException 如果您嘗試建立無效的規則動作，服務匯流排會傳回此例外狀況。 如果處理停止傳送的訊息的規則動作時發生錯誤，服務匯流排會將此例外狀況附加至該訊息。 檢查規則動作的正確性。 重試沒有用。
FilterException 如果您嘗試建立無效的篩選，服務匯流排會傳回此例外狀況。 如果處理停止傳送的訊息的篩選時發生錯誤，服務匯流排會將此例外狀況附加至該訊息。 檢查篩選的正確性。 重試沒有用。
SessionCannotBeLockedException 嘗試接受含有特定工作階段識別碼的工作階段，但該工作階段目前被另一個用戶端鎖定。 確定其他用戶端已解除鎖定工作階段。 如果工作階段在過渡期間被解除鎖定，重試可能會有幫助。
TransactionSizeExceededException 交易包含太多作業。 減少此交易的作業數目。 重試沒有用。
MessagingEntityDisabledException 在停用的實體上要求執行階段作業。 啟用實體。 如實體在過渡期間被啟用，重試可能會有幫助。
NoMatchingSubscriptionException 如果您將訊息傳送至已啟用預先篩選的主題，但沒有符合的篩選，服務匯流排就會傳回此例外狀況。 確定至少有一個篩選相符。 重試沒有用。
MessageSizeExceededException 訊息承載超過 256 KB 的限制。 256 KB 的限制是總訊息大小，可包括系統屬性和任何 .NET 負荷。 減少訊息裝載大小，然後再重試作業。 重試沒有用。
TransactionException 環境交易 (Transaction.Current) 無效。 其可能已完成或中止。 內部例外狀況可能會提供其他資訊。 重試沒有用。
TransactionInDoubtException 嘗試在不確定的交易上執行作業，或嘗試認可交易而交易變得不確定。 應用程式必須處理這個例外狀況 (當成特殊狀況)，因為交易可能已被認可。 -

QuotaExceededException

QuotaExceededException 指出已超過某特定實體的配額。

注意

如需服務匯流排配額，請參閱配額。

佇列和主題

針對佇列和主題，其通常是佇列的大小。 錯誤訊息屬性會包含進一步的詳細資訊，如下例所示：

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

訊息指出主題超過其大小限制，本例為 1 GB (預設大小限制)。

命名空間

針對命名空間，QuotaExceededException 可能表示應用程式已超過命名空間的連線數目上限。 例如：

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

常見的原因

這個錯誤有兩個常見的原因︰無效信件佇列和訊息接收者無法正常運作。

  1. 無效信件佇列：讀取器無法完成訊息，當鎖定過期後，訊息會傳回佇列/主題。 如果讀取器遇到例外狀況，阻止其呼叫 BrokeredMessage.Complete，就會發生這個錯誤。 訊息讀取 10 次後，預設會移至無效信件佇列。 這種行為由 QueueDescription.MaxDeliveryCount 屬性控制，預設值是 10。 訊息堆積在無效信件佇列中會佔用空間。

    若要解決此問題，請閱讀和完成無效信件佇列中的訊息，就像您處理任何其他佇列一樣。 您可以使用 FormatDeadLetterPath 方法來協助格式化無效信件佇列路徑。

  2. 接收者停止。 收件者已停止接收佇列或訂用帳戶的訊息。 識別這個原因的方法是查看 QueueDescription.MessageCountDetails 屬性，它會顯示訊息的完整解析。 如果 ActiveMessageCount 屬性很高或不斷增加，表示訊息撰寫的速度超過讀取的速度。

TimeoutException

TimeoutException 表示使用者啟始作業所用的時間長過作業逾時。

您應該檢查 ServicePointManager.DefaultConnectionLimit 屬性的值，因為達到這個限制可能也會造成 TimeoutException。

在維護作業 (例如服務匯流排服務更新 (或) 執行服務資源上的作業系統更新) 期間或過程中，預期會發生逾時狀況。 在作業系統更新期間，實體會四處移動且節點會更新或重新開機，這可能會導致逾時。 如需 Azure 服務匯流排服務的服務等級協定 (SLA) 詳細資料，請參閱服務匯流排的 SLA。

佇列和主題

佇列和主題的逾時是在 MessagingFactorySettings.OperationTimeout 屬性中指定，作為連接字串的一部分，或透過 ServiceBusConnectionStringBuilder 指定。 錯誤訊息本身可能不盡相同，但它一定會包含目前作業的指定逾時值。

MessageLockLostException

原因

使用 PeekLock 接收模式接收訊息時，若用戶端所持有的鎖定在服務端到期，將會擲回 MessageLockLostException。

訊息上的鎖定可能會由於各種原因而到期：

  • 鎖定計時器已在用戶端應用程式更新鎖定之前到期。
  • 用戶端應用程式已取得鎖定、將其儲存至持續性存放區，然後重新啟動。 一旦重新啟動，用戶端應用程式就會查看處理中訊息，並嘗試完成這些訊息。

在下列案例中，您可能也會收到此例外狀況：

  • 服務更新
  • 作業系統更新
  • 在保留鎖定時變更實體 (佇列、主題、訂用帳戶) 上的屬性。

解決方法

當用戶端應用程式收到 MessageLockLostException 時，再也無法處理訊息。 用戶端應用程式可能會選擇性地考慮記錄例外狀況進行分析，但用戶端「必須」處置訊息。

由於訊息上的鎖定已過期，因此其會回到佇列 (或訂用帳戶)，並可由呼叫接收的下一個用戶端應用程式處理。

如果已超過 MaxDeliveryCount，則訊息可能會移至 DeadLetterQueue。

SessionLockLostException

原因

SessionLockLostException 會在接受工作階段且用戶端所持有的鎖定在服務端到期時擲回。

工作階段上的鎖定可能會由於各種原因而到期：

  • 鎖定計時器已在用戶端應用程式更新鎖定之前到期。
  • 用戶端應用程式已取得鎖定、將其儲存至持續性存放區，然後重新啟動。 一旦重新啟動，用戶端應用程式就會查看處理中工作階段，並嘗試處理這些訊息。

在下列案例中，您可能也會收到此例外狀況：

  • 服務更新
  • 作業系統更新
  • 在保留鎖定時變更實體 (佇列、主題、訂用帳戶) 上的屬性。

解決方法

當用戶端應用程式收到 MessageLockLostException 時，再也無法處理工作階段上的訊息。 用戶端應用程式可能會考慮記錄例外狀況進行分析，但用戶端「必須」處置訊息。

由於訊息上的鎖定已過期，因此其會回到佇列 (或訂用帳戶)，並可由接收工作階段的下一個用戶端應用程式鎖定。 由於工作階段鎖定由單一用戶端應用程式在任何給定時間持有，因此保證依序處理。

SocketException

原因

下列情況會擲回 SocketException：

  • 當連線嘗試因為主機未在指定的時間之後正確回應而失敗時 (TCP 錯誤碼 10060)。
  • 已建立的連線失敗，因為連線的主機無法回應。
  • 處理訊息時發生錯誤，或遠端主機超過逾時。
  • 基礎網路資源問題。

解決方法

SocketException 錯誤表示裝載應用程式的 VM 無法將名稱 <mynamespace>.servicebus.windows.net 轉換為對應的 IP 位址。

查看下列命令是否成功對應至 IP 位址。

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

哪一個應該提供如下的輸出：

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

如果上述名稱未解析為 IP 和命名空間別名，請洽詢網路管理員進一步調查。 名稱解析是透過 DNS 伺服器 (通常是客戶網路中的資源) 完成。 如果 DNS 解析是由 Azure DNS 完成，請連絡 Azure 支援。

如果名稱解析如預期般運作，請在這裡檢查是否允許連線至 Azure 服務匯流排。

MessagingException

原因

MessagingException 是一般例外狀況，可能會由於各種原因而擲回。 某些原因如下：

  • 嘗試在 Topic 或 Subscription 上建立 QueueClient。
  • 所傳送訊息的大小大於給定層的限制。 深入閱讀服務匯流排配額和限制。
  • 特定資料平面要求 (傳送、接收、完成、放棄) 由於節流而終止。
  • 由於服務升級和重新啟動所造成的暫時性問題。

注意

上述的例外狀況清單不完整。

解決方法

解析步驟取決於擲回 MessagingException 的原因。

  • 針對暫時性問題 (其中 isTransient 設定為 true)，或針對節流問題，重試作業可能會解決此問題。 SDK 上的預設重試原則可用於此情況。
  • 針對其他問題，例外狀況中的詳細資料表示問題與解決步驟可從相同的方式推斷。

StorageQuotaExceededException

原因

StorageQuotaExceededException 會在進階命名空間中的實體總大小超過每個傳訊單位 1 TB 的限制時產生。

解決方法

  • 增加指派給進階命名空間的傳訊單位數目
  • 如果您已經針對命名空間使用允許的傳訊單位上限，請建立個別的命名空間。

下一步

如需完整的服務匯流排 .NET API 參考資料，請參閱 Azure .NET API 參考資料。 如需疑難排解秘訣，請參閱疑難排解指南。