事件中心消息传送异常 - .NET（旧版）

本部分列出了 .NET Framework API 生成的 .NET 异常。

重要

本文中列出的一些异常仅适用于旧版 Event Hubs .NET 库。 例如：Microsoft.ServiceBus.* 异常。

有关新 .NET 库引发的 EventHubsException 的信息，请参阅 EventHubsException - .NET

重要

WindowsAzure.ServiceBus 已于 2026 年 9 月 30 日在 Event Hubs 中退役，不再获得官方支持或更新。 该参考资料仍可用于诊断现有应用。 迁移到 Azure.Messaging.EventHubs 并使用其异常处理指导。 详情请参见 退休公告。

异常类别

事件中心 .NET API 会生成以下类别的异常，以及在尝试修复这些异常时可以采取的相关操作：

异常类型

下表列出了消息异常的类型及其原因，并说明您可以采取的建议措施。

异常类型 说明/原因/示例 建议的操作 自动/立即重试注意事项
TimeoutException 服务器在 OperationTimeout 控制的指定时间内未响应请求的操作。 服务器可能已完成请求的操作。 此异常可能是由于网络或其他基础结构延迟造成的。 检查系统状态是否一致，并根据需要重试。
请参阅 TimeoutException。		 在某些情况下，重试可能会有帮助；在代码中添加重试逻辑。
InvalidOperationException 服务器或服务不允许执行请求的用户操作。 有关详细信息，请查看异常消息。 例如，如果在 ReceiveAndDelete 模式下收到消息，则 Complete 将生成此异常。 检查代码和文档。 确保请求的操作有效。 重试没有帮助。
OperationCanceledException 尝试对已关闭、中止或释放的对象调用某个操作。 在极少数情况下，上下文事务已处置。 检查代码并确保代码不会对已释放的对象调用操作。 重试没有帮助。
UnauthorizedAccessException TokenProvider 对象无法获取令牌，该令牌无效，或者令牌不包含执行操作所需的声明。 确保使用正确的值创建令牌提供程序。 检查访问控制服务的配置。 在某些情况下，重试可能会有帮助；在代码中添加重试逻辑。
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 提供给该方法的一个或多个参数均无效。 提供给 NamespaceManager 或 Create 的 URI 包含路径段。 提供给 NamespaceManager 或 Create 的 URI 方案无效。 属性值大于 32 KB。 检查调用代码并确保参数正确。 重试不会解决问题。
Microsoft.ServiceBus.Messaging MessagingEntityNotFoundException

Microsoft.Azure.EventHubs MessagingEntityNotFoundException		 与操作关联的实体不存在或已被删除。 确保该实体存在。 重试不会解决问题。
MessagingCommunicationException 客户端无法与 Event Hubs 建立连接。 确保提供的主机名正确并且主机可访问。 如果存在间歇性的连接问题，重试可能会有帮助。
Microsoft.ServiceBus.Messaging ServerBusyException

Microsoft.Azure.EventHubs ServerBusyException		 服务目前无法处理请求。 客户端可以等待一段时间，并重试操作。
请参阅 ServerBusyException。		 客户端可在特定的时间间隔后重试操作。 如果重试导致其他异常，请检查该异常的重试行为。
MessagingException 在以下情况下，可能会引发一般消息异常：尝试使用属于其他实体类型（例如主题）的名称或路径创建 QueueClient。 尝试发送大于 1 MB 的消息。 服务器或服务在处理请求期间遇到错误。 有关详细信息，请查看异常消息。 此异常通常是暂时性的异常。 检查代码，并确保只对消息正文使用可序列化对象（或使用自定义序列化程序）。 在文档中查看属性支持的值类型，并只使用支持的类型。 检查 IsTransient 属性。 如果为 true，可以重试操作。 重试行为的效果不确定，可能不会解决问题。
MessagingEntityAlreadyExistsException 尝试使用已被该服务命名空间中另一实体使用的名称创建实体。 删除现有的实体，或者为要创建的实体选择不同的名称。 重试不会解决问题。
QuotaExceededException 消息实体已达到其最大允许大小。 如果已经在每使用者组级别上打开最大接收方数（即 5），则可能会发生此异常。 通过从实体或其子队列接收消息在该实体中创建空间。
请参阅 QuotaExceededException		 如果消息在此期间已被删除，则重试可能会有帮助。
MessagingEntityDisabledException 对已禁用的实体请求运行时操作。 激活实体。 如果在此期间该实体已被激活，则重试可能会有帮助。
Microsoft.ServiceBus.Messaging MessageSizeExceededException

Microsoft.Azure.EventHubs MessageSizeExceededException		 消息有效负载超出 1 MB 限制。 1 MB 限制适用于总消息大小，可能包括系统属性和任何 .NET 开销。 减少消息负载的大小，并重试操作。 重试不会解决问题。

QuotaExceededException

QuotaExceededException 指示已超出某个特定实体的配额。

如果已在每个消费者组级别上打开了最大接收器数 (5)，则可能会发生此异常。

事件中心

每个 Event Hubs 最多只能有 20 个使用者组。 尝试创建更多内容时，会收到 QuotaExceededException。

TimeoutException

TimeoutException 指示用户启动的操作所用的时间超过操作超时值。

对于事件中心，超时作为连接字符串的一部分指定，或通过 ServiceBusConnectionStringBuilder 指定。 错误消息本身可能会有所不同，但它始终包含当前操作的指定超时值。

预计会在维护操作（例如，Event Hubs 服务更新或运行该服务的资源上的 OS 更新）期间或操作间隙发生超时。 在 OS 更新期间，实体会被迁移，节点会更新或重启，这可能会导致超时。 有关 Azure 事件中心服务的服务级别协议 (SLA) 详细信息，请参阅事件中心的 SLA。

常见原因

此错误有两个常见的原因：配置不正确或暂时性服务错误。

  • 配置错误：操作超时对于该运行条件而言可能设置得过短。 客户端 SDK 的操作超时默认值为 60 秒。 请查看代码是否将该值设置得过小。 网络和 CPU 使用率的状况可能会影响完成特定操作所用的时间，因此，操作超时不应设置为很小的值。
  • 暂时性服务错误：有时 Event Hubs 服务在处理请求时可能会出现延迟；例如，在流量高峰期间。 在这种情况下，可以在延迟后重试操作，直到操作成功为止。 如果多次尝试同一操作后仍然失败，请访问 Azure 服务状态站点，看是否有任何已知的服务中断。

ServerBusyException

Microsoft.ServiceBus.Messaging.ServerBusyException 或 Microsoft.Azure.EventHubs.ServerBusyException 指示服务器已过载。 此异常有两个相关的错误代码。

错误代码 50002

此错误发生的原因可能是以下之一：

  • 负载未均匀分布在事件中心的所有分区上，并且一个分区达到了本地吞吐量单位限制。

    解决方法：修改分区分发策略，或尝试 EventHubClient.Send(eventDataWithOutPartitionKey) 可能会有所帮助。

  • 事件中心命名空间没有足够的吞吐量单位（可以通过在 Azure 门户 中检查事件中心命名空间窗口中的 指标 屏幕来确认）。 门户显示聚合（1 分钟）的信息，但我们会实时测量吞吐量，因此它只是一个估计值。

    解决方法：增加命名空间上的吞吐量单位可有所帮助。

    可以在 Azure 门户中的“事件中心命名空间”页的“缩放”页或“概述”页上配置吞吐量单位。 或者，可以使用 “自动扩充” 功能，通过增加吞吐量单位的数量自动扩展，以满足使用需求。

    吞吐量单位 (TU) 适用于事件中心命名空间中的所有事件中心。 这意味着，TU 是在命名空间级别购买的，并在该命名空间下的事件中心之间共享。 每个 TU 为命名空间赋予以下功能：

    • 入口事件（发送到事件中心的事件）最多为每秒 1 MB，但每秒不超过 1000 个入口事件、管理操作或控制 API 调用。
    • 出口事件（从事件中心读取的事件）最多达每秒 2 MB，但不超过 4096 个出口事件。
    • 事件存储空间最多为 84 GB（对于默认 1 小时保持期而言已足够）。

    在 “概述” 页面上的 “显示指标” 部分，切换到 “吞吐量” 选项卡。选择图表以在较大的窗口中将其打开，x 轴以 1 分钟为间隔。 查看高峰值并将其除以 60，以获得传入字节数/秒或传出字节数/秒。 在“请求”选项卡上，使用类似的方法计算高峰时每秒的请求数。

    如果你看到的值大于 TU 的数量 * 限制（每秒 1 MB 的流入量或 1000 个流入请求/秒、每秒 2 MB 的流出量），请使用事件中心命名空间的“缩放”（在左侧菜单上）页进行手动扩展或使用事件中心的“自动扩充”功能来增加 TU 的数量。 手动扩展或自动扩展命名空间时，最多可扩展到 40 TU。

错误代码 50008

此错误很少发生。 但如果为命名空间运行代码的容器的 CPU 比较低时（在事件中心负载均衡器开始前几秒钟内），则可能发生。

解决方法：限制对 GetRuntimeInformation 方法的调用。 Azure 事件中心每秒每个使用者组最多支持 50 次对 GetRuntimeInfo 的调用。 达到限制后，你可能会收到类似于以下内容的异常：

ExceptionId: 00000000000-00000-0000-a48a-9c908fbe84f6-ServerBusyException: The request was terminated because the namespace 75248:aaa-default-eventhub-ns-prodb2b is being throttled. Error code : 50008. Please wait 10 seconds and try again.

后续步骤

访问以下链接可以了解有关 Event Hubs 的详细信息：

  • 上次更新时间为