使用.NET API与PubSub+缓存

本节描述了如何使用 .NET 的消息应用程序编程接口（API），也称为 SolClient for .NET，通过事件代理网络执行缓存请求来开发应用程序。

在会话中发起缓存请求的基本步骤如下：

1. 创建缓存会话。参见“创建缓存会话”。
2. 发送缓存请求消息。参见“发送缓存请求”。
3. 接收请求的缓存消息。参见“接收缓存消息”。
4. 完成缓存请求后销毁缓存会话对象。参见“销毁缓存会话”。

创建缓存会话

一旦获取了 JCSMPSession，客户端就可以调用 createCacheSession(CacheSessionProperties) 方法，并传入“缓存会话属性参数”表中列出的缓存会话属性来创建缓存会话对象。

缓存会话对象允许存在多个未完成的缓存请求，并对这些请求进行同步。一个会话可以有多个缓存会话对象。

CacheSessionProperties cacheProps = new CacheSessionProperties();
cacheProps.CacheName = cacheName;
cacheProps.MaxMessagesPerTopic = maxMsgs;
cacheProps.MaxMessageAgeInSecs = maxAge;
cacheProps.CacheRequestTimeoutInMsecs = timeout;
ICacheSession cacheSession;

然后，使用会话实例引用，调用 CreateCacheSession() 方法并传入缓存会话属性，如下所示：

session.CreateCacheSession(cacheProps);

参数	描述
CacheName	要发送缓存请求的分布式缓存、缓存集群或 PubSub+ 缓存实例的标识名称。
指定 PubSub+ 缓存实例会绕过缓存请求的冗余和负载均衡。建议指定分布式缓存。
CacheRequestTimeoutInMsecs	等待缓存对缓存请求的响应的时间量（以毫秒为单位）。这是一个每个请求的超时，应用程序发送的每个请求都可能导致多个底层请求。
MaxMessageAgeInSecs	要检索的消息的最大年龄（以秒为单位）。缓存时间超过此值的消息不会被检索。
值为 0 时，将返回符合 MaxMessagesPerTopic 定义的主题的所有可能消息。
MaxMessagesPerTopic	对于任何一个主题，要检索的缓存消息的最大数量。如果某个主题的缓存消息数量超过最大值，则返回最新的消息。
值为 0 时，将检索比 MaxMessagesPerTopic 更新的所有消息。

缓存会话属性参数

发送缓存请求

应用程序可以通过调用 ICacheSession 上的以下方法之一来发送缓存请求消息：

• ReturnCode SendCacheRequest(Int64 requestId, ITopic topic, bool subscribe, CacheLiveDataAction liveDataAction)
  同步缓存请求。调用此方法时，API 会根据 CacheLiveDataAction 处理选项等待缓存响应完成。

• ReturnCode SendCacheRequest(Int64 requestId, ITopic topic, bool subscribe, CacheLiveDataAction liveDataAction, EventHandler<CacheRequestEventArgs> cacheRequestListener)
  异步缓存请求。调用此方法时，API 在成功缓冲缓存请求以供传输后立即返回。请求的结果通过 cacheRequestListener 报告。

当客户端应用程序发送缓存请求消息时，必须提供以下参数。

参数	描述
requestId	一个正的 Int64，在缓存请求响应中返回给应用程序。请求 ID 可用在返回的每条缓存消息中。
topic	一个 ITopic 实例，表示从缓存中请求的主题。主题中不支持使用 #noexport。
仅支持 FLOW_THRU 缓存请求的通配符缓存请求。当通配符请求匹配多个缓存主题时，返回的各个主题之间没有时间顺序保证（尽管特定主题的消息之间仍然会保留时间顺序）。
liveDataAction	在未完成的缓存请求期间接收实时数据消息时要执行的枚举操作。可能的操作包括：

• FULFILL — 立即将匹配缓存请求的实时数据传递给应用程序。随后的缓存响应将被丢弃。
• QUEUE — 将匹配缓存请求主题的实时数据排队，直到收到缓存响应，然后在缓存响应数据之后将匹配的实时数据传递给应用程序。不匹配未完成缓存请求的实时数据将立即传递给应用程序。
• FLOW_THRU — 立即将匹配缓存请求的实时数据传递给应用程序。随后的缓存响应也会被传递。通配符缓存请求必须是 FLOW_THRU。 | | subscribe | 如果此参数设置为 true，则与缓存请求一起向事件代理发送该主题的订阅请求。
  通过与缓存请求一起发送订阅，客户端在接收完所有缓存消息后，将接收相关的实时数据消息。 | | cacheRequestListener | 用于报告缓存请求完成状态的委托。此参数仅用于异步缓存请求。 |

缓存请求消息参数

接收缓存消息

缓存消息通过 EventHandler<MessageEventArgs> 委托接收。

API 不会尝试对跨不同缓存集群接收的缓存消息进行重新排序。此外，API 不会尝试丢弃来自缓存集群或实时发布者的重复消息。

缓存中的消息可能会被缓存捆绑在一起，但消息 API 会单独将它们传递给应用程序。

如果应用程序为非阻塞缓存请求注册了事件回调委托，则缓存请求状态将返回在 CacheRequest EventArg 的返回代码中。

.NET API 支持缓存请求的主题分发。但是，如果为会话启用了主题分发，则作为缓存请求返回的消息只有在会话具有匹配的订阅时才会传递给会话接收回调。

下表列出了可以返回的返回代码。尽管这些代码也返回用于连接到事件代理的客户端的非缓存请求 API 调用，但提供的描述指示了这些事件对缓存请求的含义。

事件	描述
SOLCLIENT_OK	表示：

• 在计时器到期之前收到了所有缓存回复
• 接收到的缓存消息中没有可疑消息
• 至少有一个缓存回复包含数据 | | SOLCLIENT_INCOMPLETE | 表示返回了不完整的数据。原因可能包括：
• 所有的缓存回复都没有数据
• 至少有一条消息是可疑的 | | SOLCLIENT_FAIL | 表示在初始缓存请求期间发生了错误。可能的原因包括：
• 等待缓存响应超时
• 缓存错误响应
• 添加订阅错误响应
• 与事件代理通信时的传输错误
• 如果在初始缓存请求之后发生错误（例如，与缓存集群中的其他缓存实例通信时），则返回 SOLCLIENT_INCOMPLETE。
• 如果发生故障，API 不会自动重试任何未完成的缓存请求。此外，如果与事件代理的连接丢失，则取消所有未完成的缓存请求。 |

缓存请求事件

销毁缓存会话

要取消所有未完成的请求并销毁缓存会话，请调用 ICacheSession.Dispose() 方法。可以从任何线程安全地调用此方法。

调用 Dispose() 时，会发生以下情况：

• 所有未完成的缓存请求都被取消。
• 已排队的实时消息被传递。
• 所有阻塞的同步缓存请求立即返回，返回代码为 SOLCLIENT_INCOMPLETE，子代码为 ParamNullReference，以及“缓存会话已被销毁”的错误字符串。
• 不会为正在进行的异步缓存请求生成事件。

取消缓存请求

要取消所有未完成的请求，而不销毁缓存会话，请调用 ICacheSession.CacheRequestCancelled() 方法。可以从任何线程安全地调用此方法，并且可以重复调用。

调用 CacheRequestCancelled() 时，会发生以下情况：

• 所有未完成的缓存请求都被取消。
• 所有已排队的实时消息都被传递。
• 所有阻塞的同步缓存请求立即返回，返回代码为 SOLCLIENT_INCOMPLETE，子代码为 CacheRequestCancelled。
• 为每个正在进行的异步缓存请求生成一个缓存事件 RequestCompletedNotice，子代码为 CacheRequestCancelled。