Using Ice and IceRPC Together

6 min read

IceRPC is our new cutting-edge RPC framework, with a modular design, support for QUIC, an improved Slice language, and more.

As an Ice user, there are broadly 3 ways you can adopt IceRPC:

Port your existing Ice application to IceRPC, and then don’t look back. With this scenario, you can take full advantage of the new features provided by IceRPC. Your clients and servers can use the quic transport, or the tcp transport through the slic layer. You can also leverage new Slice features such as structs with optional fields, enums with fields, and custom types. Such a port requires a significant effort since the IceRPC API is very different from the Ice API: while the concepts remain similar, you’ll need to rework your entire communication layer.
Port only a portion of your existing Ice application to IceRPC: some components (clients, servers) use Ice while others use IceRPC.
Extend an existing Ice application with new components (clients, servers) implemented using IceRPC. The existing components remain Ice-based.

This page focuses on #2 and #3, where the Ice and IceRPC clients and servers communicate with each other using the Ice protocol and rely on the original Slice language understood by Ice.

Terminology

We tried to keep the IceRPC terminology in sync with the Ice terminology, but occasionally we found a better term or the Ice and IceRPC concepts aren’t an exact match.

Ice	IceRPC equivalent
Communicator	Connection cache (roughly)
Proxy	Proxy in the IceRPC+Ice integration
Stringified proxy	Service address, service address URI
Endpoint	Server address, server address URI
Connection	Protocol connection (for advanced users)
Transport	Transport
Object adapter	Server and Router (roughly)
Ice object	Service
Servant	Service
Dispatcher	Dispatcher
Middleware	Middleware
Locator	Locator interceptor (client side)
Router	(none)
Properties	(none)

Protocol and Transport

IceRPC implements two RPC protocols: ice and icerpc. The ice protocol is IceRPC’s implementation of the Ice Protocol, the only RPC protocol Ice implements. Your IceRPC components must use the ice protocol to communicate with Ice components.

IceRPC supports only encoding 1.1, the default Ice.Default.EncodingVersion. Make sure your Ice configuration doesn't set this property to 1.0.

Ice and IceRPC have two transports in common: tcp and ssl. You can’t use udp or bt (since they are not supported by IceRPC), and you can’t use quic (since it’s not supported by Ice).

Missing Protocol Features

IceRPC’s implementation of the Ice Protocol (ice) is fairly complete, except it does not include two features:

batched requests
protocol compression

IceRPC aborts a connection when it receives a batched request or a compressed frame. An Ice application that communicates with IceRPC components must therefore not use batch proxies or enable compression.

Using Ice Files with IceRPC

Ice’s Slice compiler for C# (slice2cs) generates code for IceRPC when you specify the --icerpc option. The generated code is compatible with IceRPC C# 0.6.

More commonly, you’ll take advantage of the ZeroC.Ice.Slice.Tools MSBuild integration and set IceRpc to true in your project file:

XML

<!-- Set the default Rpc framework for .ice file compilation to icerpc -->
<ItemDefinitionGroup>
    <SliceCompile>
      <IceRpc>true</IceRpc>
    </SliceCompile>
</ItemDefinitionGroup>

The IceRPC + Ice integration, including the C# mapping, is described in IceRPC for Ice users.

Services

IceStorm

You can use IceRPC to implement an IceStorm publisher or an IceStorm subscriber. As far as the IceStorm server is concerned, publishers and subscribers are just regular clients and servers.

IceGrid

IceRPC provides client-side support for Locators and indirectly IceGrid: an IceRPC application can find objects in IceGrid-managed servers and send requests to these objects.

IceRPC doesn't provide server-side IceGrid integration. An IceGrid node configures the servers it starts through Ice configuration files, which IceRPC doesn't read, and the registration of a server's endpoints and Process object with the registry, which the Ice runtime performs from this configuration, is not built into IceRPC.

Glacier2

IceRPC does not currently provide support for Glacier2 clients. However, you can use IceRPC to implement a server called by Glacier2.

Discovery

The discovery plug-ins provided by Ice rely on UDP multicast, which IceRPC doesn't support. IceDiscovery lets a client discover objects and object adapters through multicast lookups that the servers answer: an IceRPC client can't send these lookups and an IceRPC server can't answer them, so IceDiscovery works only between Ice components. IceLocatorDiscovery lets a client discover an IceGrid registry the same way: an IceRPC client can't, so you configure the registry's address in its locator interceptor.