你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Event Hubs 消息异常 - .NET（遗留）

本节列出了由 .NET 框架 API 生成的 .NET 异常。

Important

文章中列出的一些例外仅适用于遗留的Event Hubs .NET库。 例如：Microsoft.ServiceBus.* 异常。

关于新 .NET 库引发的 EventHubsException 的信息，请参见 EventHubsException - .NET

Important

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

例外类别

Event Hubs 的 .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，你可以重新尝试操作。 重试行为未定义，可能无效。
消息实体已存在异常 尝试创建具有该服务命名空间中另一个实体已使用的名称的实体。 删除现有实体或为要创建的实体选择其他名称。 重试也没用。
QuotaExceededException 消息实体已达到允许的最大大小。 如果每个消费者组层面已经开启了最大接收器数量（即5个），此异常就会发生。 通过从实体或其子队列接收消息在该实体中创建空间。
参见 QuotaExceededException		 如果同时已删除消息，则重试可能会有帮助。
消息实体禁用异常 (MessagingEntityDisabledException) 请求对已禁用的实体执行运行时操作。 激活实体。 如果在此期间该实体已激活，则重试可能会有帮助。
Microsoft.ServiceBus.Messaging MessageSizeExceededException

Microsoft.Azure.EventHubs MessageSizeExceededException		 消息负载超过1-MB限制。 这个1MB限制适用于总消息，可以包括系统属性和任何.NET开销。 减少消息负载的大小，并重试操作。 重试也没用。

QuotaExceededException (配额超限异常)

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

如果每个消费者群体层面已开启最大接收器数量（5个）时，该异常就会发生。

事件中心

Event Hubs每个Event Hub最多可容纳20个消费者组。 当你尝试创建更多时，会收到 一个QuotaExceededException。

TimeoutException

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

对于事件中心，超时可以在连接字符串中指定，也可以通过 ServiceBusConnectionStringBuilder 指定。 错误消息本身可能有所不同，但它总是包含当前操作指定的超时值。

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

常见原因

这种错误常见原因有两种：配置错误或临时服务错误。

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

ServerBusyException

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

错误代码50002

该错误可能由以下两种原因之一产生：

  • 负载在 Event Hubs 的所有分区中分布不均，其中一个分区会达到单个分区的吞吐量单位限制。

    解决办法：修改分区分发策略或尝试 EventHubClient.Send（eventDataWithOutPartitionKey） 可能有帮助。

  • Event Hubs 命名空间的吞吐量单元不足（你可以在 Azure 门户的 Event Hubs 命名空间窗口里查看 指标 界面确认）。 门户显示的是汇总的（1分钟）信息，但我们实时测量吞吐量——这只是估计。

    解决方法：增加命名空间的吞吐量单元会有帮助。

    你可以在 Azure 门户的事件中心命名空间页面的“规模”页面或“概览”页面配置吞吐量单元。 或者，你也可以使用 自动扩展功能，它通过增加吞吐量单元数量自动扩展，以满足使用需求。

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

    • 每秒最多1MB的入口事件（发送到事件中心的事件），但每秒最多1000次入口事件、管理操作或控制API调用。
    • 最高每秒 2 MB 的出口事件（从事件中心读取的事件），但最多 4096 个出口事件。
    • 最多 84 GB 的事件存储（足够支持默认的 1 小时保留期）。

    在 “概览 ”页面的 “显示指标 ”部分，切换到 吞吐量 标签页。选择图表，在一个较大的窗口中打开，横轴上有1分钟间隔。 看峰值值，除以60，得到输入字节/秒或输出字节/秒。 在 请求 标签页上，使用类似方法计算高峰时段每秒请求数。

    如果你看到的值高于 TU 数量 * 限制（入口为每秒 1 MB 或每秒 1000 个请求，出口为每秒 2 MB），可以通过 Event Hubs 命名空间左侧菜单中的 缩放 页面手动增加 TU 数量，或使用 Event Hubs 的 自动扩展 功能。 手动缩放或自动缩放命名空间时，最多可以扩容到 40 个 TU。

错误代码50008

这种错误很少发生。 当运行你的命名空间代码的容器 CPU 不足时，就会发生这种情况——在 Event Hubs 负载均衡器开始之前的几秒内。

解决：限制对 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.

后续步骤

访问以下链接可以了解有关事件中心的详细信息：

  • 上次更新时间为