共用方式為

Azure 服務匯流排的疑難排解指南

  • 發行項

本文提供使用 Azure 服務匯流排時發生一些問題的疑難排解指南和建議。

連線能力問題

連線至服務時逾時

根據主機環境和網路，連線問題可能會以 TimeoutException、OperationCanceledException 或 ServiceBusException (Reason 為 ServiceTimeout) 的形式呈現給應用程式，而且在用戶端找不到服務的網路路徑時，最常發生此情況。

若要進行疑難排解：

  • 確認您在建立用戶端時指定的連接字串或完整網域名稱正確無誤。 如需如何取得連接字串的相關資訊，請參閱取得服務匯流連接字串。
  • 檢查裝載環境中的防火牆和連接埠權限。 檢查進階訊息佇列通訊協定 (AMQP) 連接埠 5671 和 5672 是否已開啟，以及檢查是否允許端點通過防火牆。
  • 嘗試使用 Web 通訊端傳輸選項，此選項會使用連接埠 443 進行連線。 如需詳細資料，請參閱設定傳輸。
  • 查看您的網路是否封鎖特定 IP 位址。 如需詳細資料，請參閱需要允許哪些 IP 位址？
  • 如果適用，請驗證 Proxy 設定。 如需詳細資料，請參閱：設定傳輸
  • 如需對網路連線能力進行疑難排解的詳細資訊，請參閱：[連線能力、憑證或逾時問題][#connectivity-certificate-or-timeout-issues]。

安全通訊端層 (SSL) 交握失敗

使用攔截 Proxy 時，可能會發生此錯誤。 若要驗證，建議您在 Proxy 停用的主機環境中測試應用程式。

通訊端耗盡錯誤

應用程式應該偏好將服務匯流排類型視為單例，在應用程式的存留期建立和使用單一執行個體。 每次建立新的 ServiceBusClient 都會產生新的 AMQP 連線，其會使用通訊端。 ServiceBusClient 類型會管理從該執行個體建立的所有類型連線。 每個 ServiceBusReceiver、ServiceBusSessionReceiver、ServiceBusSender 和 ServiceBusProcessor 都會針對相關聯服務匯流排實體管理自己的 AMQP 連結。 使用 ServiceBusSessionProcessor時，會建立多個 AMQP 連結，取決於同時處理的工作階段數目。

用戶端在閒置時可以安全地進行快取；其確保有效率地管理網路、CPU 和記憶體使用，這可在非使用期間將其影響降到最低。 當不再需要用戶端時，呼叫 CloseAsync 或 DisposeAsync 以確保已適當清除網路資源，也很重要。

將元件新增至連接字串無法運作

目前世代的服務匯流排用戶端程式庫僅支援 Azure 入口網站所發佈形式的連接字串。 連接字串旨在僅供提供基本位置和共用金鑰資訊。 設定用戶端的行為是透過其選項來完成。

舊世代的服務匯流排用戶端僅被允許透過將金鑰/值元件新增至連接字串來設定某些行為。 再也無法辨識這些元件，而且其不會影響用戶端行為。

"TransportType=AmqpWebSockets" alternative

若要將 Web 通訊端設定為傳輸類型，請參閱設定傳輸。

"Authentication=Managed Identity" Alternative

若要使用受控識別進行驗證，請參閱：身分識別和共用存取認證。 如需 Azure.Identity 程式庫的詳細資訊，請參閱驗證和 Azure SDK。

記錄和診斷

服務匯流排用戶端程式庫會使用 .NET EventSource 來發出資訊，針對各種層級的詳細資料記錄資訊進行完整檢測。 系統會針對每個作業執行記錄，並遵循模式標記作業起點、其完成和遇到的任何例外狀況。 可能提供見解的其他資訊也會記錄在相關聯作業的內容中。

啟用 記錄

服務匯流排用戶端記錄可供任何 EventListener 使用，方法是加入從 Azure-Messaging-ServiceBus 開始的來源，或加入具有特徵 AzureEventSource 的所有來源。 為了更輕鬆地從 Azure 用戶端程式庫擷取記錄，服務匯流排所使用的 Azure.Core 程式庫提供 AzureEventSourceListener。

如需詳細資訊，請參閱使用 Azure SDK for .NET 進行記錄。

分散式追蹤

服務匯流排用戶端程式庫透過與 Application Insights SDK 整合支援分散式追蹤。 其也透過 .NET 5 中引進的 .NET ActivitySource 類型，具有 OpenTelemetry 規格的實驗性支援。 若要啟用與 OpenTelemetry 搭配使用的 ActivitySource 支援，請參閱 ActivitySource 支援。

若要使用 GA DiagnosticActivity 支援，您可以與 Application Insights SDK 整合。 在配有 Azure 監視器的 Application Insights 中可以找到更多的詳細資料。

程式庫會建立下列範圍：

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

大部分範圍都是自我說明的，而且會在以其名稱命名的作業期間啟動和停止。 將其他範圍繋結在一起的範圍為 Message。 訊息的追蹤方式是透過在傳送和排程作業期間程式庫於 ServiceBusMessage.ApplicationProperties 屬性中設定的 Diagnostic-Id。 在 Application Insights 中，Message 範圍會顯示為各種其他範圍的外部連結，而這些範圍用來與訊息互動，例如，ServiceBusReceiver.Receive 範圍、ServiceBusSender.Send 範圍和 ServiceBusReceiver.Complete 範圍全都會從 Message 範圍進行連結。 以下範例顯示此類範圍在 Application Insights 中看起來的樣子：

顯示範例分散式追蹤的影像。

在上述螢幕擷取畫面中，您會看到可在入口網站中 Application Insights 中檢視的端對端交易。 在此情節中，應用程式會傳送訊息，並使用 ServiceBusSessionProcessor 來處理這些訊息。 Message 活動會連結至 ServiceBusSender.Send、ServiceBusReceiver.Receive、ServiceBusSessionProcessor.ProcessSessionMessage 和 ServiceBusReceiver.Complete。

注意

如需詳細資訊，請參閱透過服務匯流排傳訊的分散式追蹤和相互關聯。

針對傳送者問題進行疑難解答

無法傳送具有多個分割區索引鍵的批次

當應用程式將批次傳送至已啟用分割區的實體時，單一傳送作業中包含的所有訊息都必須具有相同的 PartitionKey。 如果您的實體已啟用工作階段，相同需求也適用於 SessionId 屬性。 若要傳送具有不同 PartitionKey 或 SessionId 值的訊息，請將訊息分組在個別 ServiceBusMessageBatch 執行個體中，或將訊息包含在 SendMessagesAsync 多載的個別呼叫中，此多載接受一組 ServiceBusMessage 執行個體。

批次無法傳送

訊息批次為包含兩則以上訊息的 ServiceBusMessageBatch，或為 SendMessagesAsync 的呼叫，其中傳入兩則以上的訊息。 服務不允許訊息批次超過 1 MB。 不論是否啟用進階大型訊息支援功能，此行為都成立。 如果您想要傳送大於 1 MB 的訊息，則必須個別傳送該訊息，而不是與其他訊息群組在一起。 可惜的是，ServiceBusMessageBatch 類型目前不支援驗證批次是否不包含任何大於 1 MB 的訊息，因為大小受到服務限制，而且可能會變更。 因此，如果您想要使用進階大型訊息支援功能，請確定您個別傳送超過 1 MB 的訊息。

針對接收者問題進行疑難排解

所傳回的訊息數目不符合批次接收中所要求的數目

嘗試執行批次接收作業時，也就是說，將值為 2 或更大的 maxMessages 傳遞至 ReceiveMessagesAsync 方法，也不保證您會收到所要求的訊息數目，即使佇列或訂用帳戶當時有那麼多的可用訊息，以及即使尚未過了整個設定的 maxWaitTime 也一様。 為了將輸送量最大化並避免鎖定到期，一旦第一則訊息通過網路傳輸，接收者就會針對任何額外的訊息等待額外的 20 毫秒，然後再分派訊息進行處理。 maxWaitTime 控制接收者等待接收第一則訊息的時間長度 - 後續訊息的等待時間為 20 毫秒。 因此，您的應用程式不應該假設一次呼叫中收到所有可用的訊息。

鎖定到期時間之前遺失訊息或工作階段鎖定

服務匯流排服務會使用具狀態的 AMQP 通訊協定。 由於通訊協定的本質，如果連線用戶端與服務的連結在收到訊息之後，但在確定訊息之前中斷連結，就無法在重新連線連結時確定訊息。 連結可能會因為短期暫時性網路失敗、網路中斷，或由於服務強制執行 10 分鐘閒置逾時而中斷。 重新連線連結會自動發生，做為任何需要連結的作業一部分，也就是確定或接收訊息。 在此情況下，您會收到 Reason 為 MessageLockLost 或 SessionLockLost 的 ServiceBusException，即使尚未過了鎖定到期時間。

如何瀏覽排程或延遲的訊息

查看訊息時會包含排程和延遲的訊息。 您可以透過 serviceBusReceivedMessage.State 屬性來識別這些訊息。 一旦您具有延遲訊息的 SequenceNumber，就可以透過 ReceiveDeferredMessagesAsync 方法搭配鎖定來接收該訊息。

使用主題時，您無法查看訂用帳戶上的排程訊息，因為這些訊息會保留在主題中，直到排程的加入佇列時間。 因應措施是，您可以建構 ServiceBusReceiver 傳入主題名稱，以便查看這類訊息。 使用主題名稱時，接收者沒有其他作業可以運作。

如何跨所有工作階段瀏覽工作階段訊息

您可以使用一般 ServiceBusReceiver，跨所有工作階段進行查看。 若要查看特定工作階段，您可以使用 ServiceBusSessionReceiver，但需要取得工作階段鎖定。

存取訊息內文時擲回 NotSupportedException

在收到從使用不同 AMQP 訊息內文格式的不同程式庫傳送的訊息時，此問題最常發生在 Interop 情節中。 如果您要與這些類型的訊息互動，請參閱 AMQP 訊息內文範例，以了解如何存取訊息內文。

針對處理器問題進行疑難排解

自動鎖定更新無法運作

自動鎖定更新依賴系統時間來判斷何時更新訊息或工作階段的鎖定。 如果您的系統時間不正確，例如，您的時鐘慢了，則鎖定更新可能不會在鎖定遺失之前發生。 如果自動鎖定更新無法運作，請確定您的系統時間正確無誤。

處理器在使用高並行時似乎停止回應或發生延遲問題

此行為通常是由執行緒耗盡所造成，特別是當使用工作階段處理器，以及針對 MaxConcurrentSessions 使用非常高的值時，此值相對於機器上的核心數目。 首先要檢查的是確定您未在任何事件處理常式中執行非同步的同步。 非同步的同步是容易造成鎖死和執行緒耗盡的方式。 即使您未執行非同步的同步，處理常式中的任何純同步程式碼都可能導致執行緒耗盡。 如果您已判斷這不是問題，例如，因為您具有純非同步程式碼，則可以嘗試增加 [TryTimeout][TryTimeout]。 其會藉由減少特別在使用工作階段處理器時發生的內容切換和逾時數目，來減輕執行緒集區的壓力。 [TryTimeout][TryTimeout] 的預設值為 60 秒，但最高可以設定 1 小時。 我們建議將 TryTimeout 設定為 5 分鐘進行測試，做為起點並從該處進行逐一查看。 如果上述任何建議都無法運作，您只需要擴增至多部主機，減少應用程式中的並行，但在多部主機上執行應用程式，以實現所需的整體並行。

進階閱讀：

工作階段處理器切換工作階段花費太長的時間

這可以使用 [SessionIdleTimeout][SessionIdleTimeout] 來設定，其會告訴處理器在放棄並移至另一個工作階段之前，從工作階段接收訊息要等待多長時間。 如果您具有許多稀疏填入的工作階段，其中每個工作階段只有一些訊息，這會很有用。 如果您預期每個工作階段都會具有許多緩慢移動的訊息，將其設定太低可能會適得其反，因為其會導致不必要的工作階段關閉。

處理器立即停止

通常會在示範或測試案例中觀察到此情況。 StartProcessingAsync 會在處理器啟動之後立即返回。 呼叫這個方法並不會在處理器執行時封鎖並讓應用程式保持運作，因此您需要一些其他機制來執行此動作。 針對示範或測試，只要在啟動處理器之後新增 Console.ReadKey() 呼叫即可。 針對生產案例，您可能會想要使用某種架構整合，例如 [BackgroundService][BackgroundService]，以提供方便的應用程式生命周期掛勾，其可用於啟動和處置處理器。

針對交易進行疑難排解

如需服務匯流排中交易的一般資訊，請參閱 [服務匯流排交易處理概觀][Transactions]。

支援的作業

使用交易時，並非所有作業都受到支援。 若要查看支援的交易清單，請參閱 [交易範圍內的作業][TransactionOperations]。

Timeout

交易會在 [期間][TransactionTimeout] 之後逾時，因此，在交易範圍內發生的處理必須遵守此逾時。

不會重試交易中的作業

這是原廠設定。 請考慮下列案例 - 您嘗試在交易內完成訊息，但發生一些暫時性錯誤，例如，ServiceBusException，Reason 為 ServiceCommunicationProblem。 假設確實對服務提出要求。 如果用戶端要重試，服務會看到兩個完成要求。 將不會完成第一個完成要求，直到認可交易為止。 第二個完成要求甚至無法在第一個完成整要求完成之前進行評估。 用戶端上的交易正在等待完成要求完成。 這會建立死結，其中服務正在等待用戶端完成交易，但用戶端正在等候服務確認第二個完成作業。 交易最終會在 2 分鐘後逾時，但這是不好的使用者體驗。 基於這個原因，我們不會在交易內重試作業。

跨實體的交易無法運作

若要執行涉及多個實體的交易，您必須將 ServiceBusClientOptions.EnableCrossEntityTransactions 屬性設定為 true。 如需詳細資料，請參閱 [跨實體的交易][CrossEntityTransactions] 範例。

配額

可在 [這裡][ServiceBusQuotas] 找到服務匯流排配額的相關資訊。

連線、憑證或逾時問題

下列步驟會協助您針對 *.servicebus.windows.net 下所有服務的連線/憑證/逾時問題進行疑難排解。

  • 瀏覽至或 wget https://<yournamespace>.servicebus.windows.net/。 其有助於檢查您是否有 IP 篩選或虛擬網路或憑證鏈結方面的問題 (這些是使用 Java SDK 時常見的問題)。

    成功訊息的範例：

    <feed xmlns="http://www.w3.org/2005/Atom"><title type="text">Publicly Listed Services</title><subtitle type="text">This is the list of publicly-listed services currently available.</subtitle><id>uuid:27fcd1e2-3a99-44b1-8f1e-3e92b52f0171;id=30</id><updated>2019-12-27T13:11:47Z</updated><generator>Service Bus 1.1</generator></feed>

    失敗錯誤訊息的範例：

    <Error>
    <Code>400</Code>
    <Detail>
        Bad Request. To know more visit https://aka.ms/sbResourceMgrExceptions. . TrackingId:b786d4d1-cbaf-47a8-a3d1-be689cda2a98_G22, SystemTracker:NoSystemTracker, Timestamp:2019-12-27T13:12:40
    </Detail>
</Error>

  • 執行下列命令，檢查防火牆上是否有任何連接埠遭到封鎖。 使用的連接埠為 443 (HTTPS)、5671 和 5672 (AMQP) 以及 9354 (網路傳訊/SBMP)。 取決於所使用的程式庫，也會使用其他連接埠。 以下是檢查 5671 連接埠是否遭到封鎖的範例命令。 C

    tnc <yournamespacename>.servicebus.windows.net -port 5671

    在 Linux 上：

    telnet <yournamespacename>.servicebus.windows.net 5671

  • 如果有間歇性的連線問題，請執行下列命令來檢查是否有任何封包遭到捨棄。 此命令會嘗試每隔 1 秒便與服務建立 25 個不同的 TCP 連線。 然後，您可以檢查其中有多少連線成功/失敗，另外也可以查看 TCP 連線延遲。 您可以從這裡下載 psping 工具。

    .\psping.exe -n 25 -i 1 -q <yournamespace>.servicebus.windows.net:5671 -nobanner

    如果您使用的是 tnc、ping 等其他工具，則可以使用對等的命令。

  • 如果先前的步驟無法提供協助，請取得網路追蹤，然後使用 Wireshark 等工具進行分析。 如有需要，請連絡 Microsoft 支援服務。

  • 若要尋找正確 IP 位址以新增至允許清單以供連線，請參閱需要將哪些 IP 位址新增至允許清單？。

2026 年 9 月 30 日我們將淘汰 Azure 服務匯流排的 SBMP 通訊協定支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。 請在該日期之前移轉至使用 AMQP 通訊協定的最新 Azure 服務匯流排 SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

如需詳細資訊，請參閱支援淘汰公告。

服務升級/重新啟動時可能發生的問題

徵兆

  • 要求可能會短暫節流。
  • 傳入的訊息/要求中可能有捨棄情形。
  • 記錄檔可能包含錯誤訊息。
  • 應用程式與服務的連線可能會中斷幾秒鐘。

原因

後端服務升級和重新啟動可能會導致應用程式中發生這些問題。

解決方法

如果應用程式程式碼使用 SDK，便已內建並啟用重試原則。 該應用程式會重新連線，不會對應用程式/工作流程產生重大影響。

未經授權的存取：傳送宣告為必要

徵兆

嘗試使用具備傳送權限的使用者指派受控識別，從內部部署電腦上的 Visual Studio 存取服務匯流排主題時，你可能會看到此錯誤。

Service Bus Error: Unauthorized access. 'Send' claim\(s\) are required to perform this operation.

原因

身分識別沒有存取服務匯流排主題的權限。

解決方法

若要解決此錯誤，請安裝 Microsoft.Azure.Services.AppAuthentication 程式庫。 如需詳細資訊，請參閱本機開發驗證。

若要了解如何將權限指派給角色，請參閱使用 Microsoft Entra ID 驗證受控識別以存取 Azure 服務匯流排資源。

服務匯流排例外狀況：放置權杖失敗

徵兆

您收到下列錯誤訊息：

Microsoft.Azure.ServiceBus.ServiceBusException: Put token failed. status-code: 403, status-description: The maximum number of '1000' tokens per connection has been reached.

在 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 的官方支援和更新。 如需詳細資訊，請參閱支援淘汰公告。

原因

在與服務匯流排命名空間的單一連線中，並行連結的驗證權杖數目已超過限制：1000。

解決方法

執行下列其中一個步驟：

  • 減少單一連線中的並行連結數目，或使用新的連線
  • 使用 Azure 服務匯流排的 SDK，可確保您不會遇到這類狀況 (建議)

使用資料平面 SDK 時，資源鎖定無法運作

徵兆

您已在服務匯流排命名空間上設定刪除鎖定，但您能夠使用 Service Bus Explorer 來刪除命名空間中的資源 (佇列、主題等)。

原因

資源鎖定會保留在 Azure Resource Manager (控制平面) 中，而且不會阻止資料平面 SDK 呼叫直接從命名空間刪除資源。 獨立 Service Bus Explorer 會使用資料平面 SDK，因此刪除會執行。

解決方法

建議您透過 Azure 入口網站、PowerShell、CLI 或 Resource Manager 範本使用 Azure Resource Manager 型 API 來刪除實體，讓資源鎖定防止資源遭到意外刪除。

再也無法使用實體

徵兆

您會看到再也無法使用實體的錯誤。

原因

資源可能已遭刪除。 請遵循下列步驟來識別刪除實體的原因。

  • 檢查活動記錄檔，以查看是否有 Azure Resource Manager 要求刪除。
  • 檢查作業記錄檔，以查看是否有直接 API 呼叫進行刪除。 若要了解如何收集作業記錄，請參閱監視 Azure 服務匯流排。 如需作業記錄的結構描述和範例，請參閱作業記錄
  • 檢查作業記錄檔，以查看是否有 autodeleteonidle 相關的刪除。

下一步

請參閱以下文章：

  • Azure Resource Manager 例外狀況。 文章列出使用 Azure Resource Manager 與 Azure 服務匯流排互動 (透過範本或直接呼叫) 時產生的例外狀況。
  • 傳訊例外狀況。 文章提供 .NET Framework 所產生的 Azure 服務匯流排例外狀況清單。