你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文列出了 .NET Framework API 生成的 .NET 异常。
2026 年 9 月 30 日，我们将停用 Azure 服务总线 SDK 库 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus，这些库不符合 Azure SDK 准则。 我们还将结束对 SBMP 协议的支持，因此在 2026 年 9 月 30 日之后，你将无法再使用此协议。 请在该日期之前迁移到最新的 Azure SDK 库，新库提供了关键安全更新和改进功能。
尽管 2026 年 9 月 30 日之后仍然可以使用较旧的库，但它们将不再获得 Microsoft 的官方支持和更新。 有关详细信息，请参阅 支持停用公告。
异常类别
消息传送 API 会生成以下类别的异常，以及在尝试修复这些异常时可以采取的相关操作。 异常的含义和原因可能因消息实体的类型而异：
- 用户编码错误（System.ArgumentException、 System.InvalidOperationException、 System.OperationCanceledException、 System.Runtime.Serialization.SerializationException）。 一般操作：在继续之前尝试修复代码。
- 设置/配置错误（Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException、System.UnauthorizedAccessException）。 一般操作：查看您的配置，并在必要时进行更改。
- 暂时性异常（Microsoft.ServiceBus.Messaging.MessagingException、 Microsoft.ServiceBus.Messaging.ServerBusyException、 Microsoft.ServiceBus.Messaging.MessagingCommunicationException）。 常规操作：重试操作或通知用户。
RetryPolicy可以将客户端 SDK 中的类配置为自动处理重试。 有关详细信息，请参阅 重试指南。 - 其他异常（System.Transactions.TransactionException、 System.TimeoutException、 Microsoft.ServiceBus.Messaging.MessageLockLostException、 Microsoft.ServiceBus.Messaging.SessionLockLostException）。 常规操作：特定于异常类型；请参考以下部分中的表：
重要
- 当在事务范围内执行的操作发生异常时，Azure 服务总线不会重试该操作。
- 有关特定于 Azure 服务总线的重试指南，请参阅 服务总线的重试指南。
异常类型
下表列出了消息传送异常类型及其原因，以及可以采取的建议作。
| 异常类型 | 说明/原因/示例 | 建议的行动 | 有关自动/立即重试的说明 |
|---|---|---|---|
| TimeoutException | 服务器未在指定时间内对请求的操作进行响应，而该操作由 OperationTimeout 控制。 服务器可能已完成请求的操作。 由于网络或其他基础结构延迟，可能会发生这种情况。 | 检查系统状态是否一致性，并在必要时重试。 请参阅超时异常。 | 在某些情况下，重试可能会有帮助；在代码中添加重试逻辑。 |
| InvalidOperationException | 不允许在服务器或服务中执行请求的用户操作。 有关详细信息，请查看异常消息。 例如， Complete（） 如果在 ReceiveAndDelete 模式下收到消息，则生成此异常。 | 检查代码和文档。 确保请求的操作有效。 | 重试不起作用。 |
| OperationCanceledException | 尝试对已关闭、中止或释放的对象调用某个操作。 在极少数情况下，环境事务已释放。 | 检查代码并确保代码不会对已释放的对象调用操作。 | 重试不起作用。 |
| UnauthorizedAccessException（未授权访问异常） | TokenProvider 对象无法获取令牌、令牌无效或令牌不包含执行作所需的声明。 | 确保使用正确的值创建令牌提供程序。 检查访问控制服务的配置。 | 在某些情况下，重试可能会有帮助；在代码中添加重试逻辑。 |
| ArgumentException ArgumentNullException ArgumentOutOfRangeException |
提供给该方法的一个或多个参数均无效。 提供给 NamespaceManager 或 Create 的 URI 包含路径段。 提供给 NamespaceManager 或 Create 的 URI 方案无效。 属性值大于 32 KB。 |
检查调用代码并确保参数正确。 | 重试不起作用。 |
| MessagingEntityNotFoundException | 与作关联的实体不存在或已被删除。 | 确保实体存在。 | 重试不起作用。 |
| MessageNotFoundException | 尝试接收具有特定序列号的消息。 找不到此消息。 | 确保该消息尚未接收。 检查死信队列，以确定该消息是否被视为死信。 | 重试不起作用。 |
| 消息通信异常 (MessagingCommunicationException) | 客户端无法与服务总线建立连接。 | 确保提供的主机名正确，并且主机可访问。 如果代码在防火墙或代理环境中运行，请确保服务总线的域名/IP地址和端口的流量未被阻止。 |
如果出现间歇性连接问题，重试可能会有所帮助。 |
| ServerBusyException | 服务目前无法处理请求。 | 客户端可以等待一段时间，然后重试该作。 | 客户端可能会在特定间隔后重试。 如果重试导致其他异常，请检查该异常的重试行为。 |
| MessagingException | 在以下情况下，可能会引发一般消息异常： 尝试使用属于不同实体类型的名称或路径（例如主题）创建 QueueClient 。 尝试发送大于 256 KB 的消息。 服务器或服务在处理请求期间遇到错误。 有关详细信息，请查看异常消息。 这通常是暂时性异常。由于实体正受到限制，因此已终止请求。 错误代码：50001、50002、50008。 |
检查代码并确保仅对消息正文使用可序列化的对象（或使用自定义序列化程序）。 查看文档，了解属性支持的值类型，并且仅使用支持的类型。 检查 IsTransient 属性。 如果为 true，则可以重试该操作。 |
如果异常是由于限制导致的，请等待几秒钟，然后重试该操作。 重试行为未定义，在其他方案中可能没有帮助。 |
| 消息实体已存在异常 | 尝试创建具有该服务命名空间中另一个实体已使用的名称的实体。 | 删除现有实体或为要创建的实体选择其他名称。 | 重试不起作用。 |
| QuotaExceededException | 消息传送实体已达到其允许的最大大小，或者已超出与命名空间的最大连接数。 | 通过从实体或其子队列接收消息在该实体中创建空间。 请参阅 QuotaExceededException。 | 如果同时已删除消息，则重试可能会有帮助。 |
| RuleActionException | 如果您尝试创建无效的规则操作，服务总线将返回此异常。 如果在处理该消息的规则操作时出错，服务总线会将此异常附加到死信消息。 | 检查规则操作是否正确。 | 重试不起作用。 |
| FilterException | 如果尝试创建无效筛选器，服务总线将返回此异常。 如果在处理该消息的筛选器时出错，服务总线会将此异常附加到死信消息。 | 检查筛选器是否正确。 | 重试不起作用。 |
| SessionCannotBeLockedException | 尝试接受具有特定会话 ID 的会话，但会话当前被另一个客户端锁定。 | 确保会话已由其他客户端解锁。 | 如果在此期间会话已释放，则重试可能会有帮助。 |
| 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.
常见原因
此错误有两个常见原因：死信队列和无法正常运行的消息接收器。
死信队列 读取器无法完成消息，锁过期时，消息将返回到队列/主题。 如果读取器遇到阻止其调用 BrokeredMessage.Complete 的异常，则可能会发生这种情况。 消息读取 10 次后，默认移至死信队列。 此行为由 QueueDescription.MaxDeliveryCount 属性控制，默认值为 10。 随着消息在死信队列中堆积，它们会占用越来越多的空间。
若要解决此问题，请读取并完成死信队列中的消息，就像处理任何其他队列一样。 可以使用 FormatDeadLetterPath 方法来帮助格式化死信队列路径。
接收方已停止。 接收方已停止从队列或订阅接收消息。 标识它的方式是查看 QueueDescription.MessageCountDetails 属性，该属性显示消息的完整细分。 如果 ActiveMessageCount 属性较高或不断增加，则消息的读取速度不会超过写入速度。
TimeoutException
TimeoutException 表示用户启动的操作花费的时间超过了操作超时的时限。
应检查 ServicePointManager.DefaultConnectionLimit 属性的值，因为达到此限制也会导致 TimeoutException。
预计会在维护操作（例如，服务总线服务更新或运行服务的资源上的 OS 更新）期间或操作间隙发生超时。 在 OS 更新期间，实体四处移动，节点会更新或重新启动，这可能会导致超时。 有关 Azure 服务总线服务的服务级别协议（SLA）详细信息，请参阅 服务总线的 SLA。
队列和主题
对于队列和主题，超时在 MessagingFactorySettings.OperationTimeout 属性中作为连接字符串的一部分指定，或通过 ServiceBusConnectionStringBuilder 指定。 错误消息本身可能会有所不同，但它始终包含为当前操作中指定的超时值。
MessageLockLostException
原因
当使用 PeekLock 接收模式接收到消息并且客户端持有的消息锁在服务端过期时，将引发 MessageLockLostException。
消息锁定可能会因多种原因而过期：
- 锁计时器在客户端应用程序续订之前已过期。
- 客户端应用程序获取了锁，将其保存到持久存储区，然后重新启动。 重新启动后，客户端应用程序会查看即时消息并尝试完成这些操作。
在以下情况下，也可能会收到此异常：
- 服务更新
- OS 更新
- 在持有锁时更改实体（队列、主题、订阅）的属性。
决议
当客户端应用程序收到 MessageLockLostException 时，它无法再处理该消息。 客户端应用程序可以选择记录异常进行分析，但客户端 必须 释放消息。
由于消息上的锁定已过期，因此它将返回到队列（或订阅），可由调用接收的下一个客户端应用程序进行处理。
如果 MaxDeliveryCount 已超过，则消息可能会移动到 DeadLetterQueue。
SessionLockLostException
原因
当会话被接受且客户端持有的锁在服务端过期时，将抛出 SessionLockLostException。
会话上的锁可能会因多种原因过期：
- 锁计时器在客户端应用程序续订之前已过期。
- 客户端应用程序获取了锁，将其保存到持久存储区，然后重新启动。 重新启动后，客户端应用程序会查看即时会话，并尝试处理这些会话中的消息。
在以下情况下，也可能会收到此异常：
- 服务更新
- OS 更新
- 在持有锁时更改实体（队列、主题、订阅）的属性。
决议
当客户端应用程序收到 SessionLockLostException 时，它无法再处理会话上的消息。 客户端应用程序可能会考虑记录异常进行分析，但客户端 必须 释放消息。
由于会话上的锁定已过期，因此它将返回到队列（或订阅），并且可由接受会话的下一个客户端应用程序锁定。 由于会话锁由单个客户端应用程序在任意给定的时间持有，因此保证了有序处理。
SocketException
原因
以下情况下会引发 SocketException：
- 当由于主机在指定时间后没有正确响应而导致连接尝试失败时（TCP 错误代码 10060）。
- 建立的连接失败，因为连接的主机未能响应。
- 处理消息时发生错误或远程主机超时。
- 基础网络资源问题。
决议
SocketException 错误表明承载应用程序的 VM 无法将名称 转换为相应的 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 是一个泛型异常，可能出于各种原因引发。 一些原因包括：
- 尝试在主题或订阅上创建 QueueClient。
- 发送的消息的大小大于给定层的限制。 阅读有关服务总线配额和限制的详细信息。
- 由于限制，特定的数据平面请求（发送、接收、完成、放弃）已终止。
- 由于服务升级和重启而导致的暂时性问题。
注释
异常列表并不详尽。
决议
解决方法步骤取决于引发 MessagingException 的原因。
- 对于 暂时性问题 （其中 isTransient 设置为 true）或限制 问题，重试作可能会解决此问题。 可以使用 SDK 上的默认重试策略。
- 对于其他问题，异常中的详细信息表明可以从中得出问题和解决步骤。
StorageQuotaExceededException
原因
当高级命名空间中的实体总大小超过每个消息传送单元 1 TB 的限制时，将生成 StorageQuotaExceededException。
决议
- 增加分配给高级命名空间的消息传送单元数
- 如果当前命名空间已达到允许的最大消息单元限制，请创建一个新的命名空间。
后续步骤
有关完整的服务总线 .NET API 参考，请参阅 Azure .NET API 参考。 有关故障排除提示，请参阅 故障排除指南。