Writing your first IceRPC + Slice server in C#

dotnet new icerpc-slice-server -o MySliceServer

This command creates a new IceRPC server application in directory MySliceServer.

Let's examine each file:

slice/Greeter.slice - the contract

This file holds the contract between our client and server applications, specified with the Slice language.

It's a simple greeter:

[cs::identifier("MySliceServer")]
module VisitorCenter

/// Represents a simple greeter.
interface Greeter {
    /// Creates a personalized greeting.
    /// @param name: The name of the person to greet.
    /// @returns: The greeting.
    greet(name: string) -> string
}

The cs::identifier attribute instructs the C# code generators to map module VisitorCenter to C# namespace MySliceServer (our project name) instead of the default (VisitorCenter).

If you use this code as the starting point for a new application, you should update this interface to represent something meaningful for your application. For this tutorial, we just keep Greeter as-is.

Chatbot.cs - the service implementation

Class Chatbot is a service that implements Slice interface Greeter:

[Service]
internal partial class Chatbot : IGreeterService
{
    public ValueTask<string> GreetAsync(
        string name,
        IFeatureCollection features,
        CancellationToken cancellationToken)
    {
        Console.WriteLine($"Dispatching greet request {{ name = '{name}' }}");
        return new($"Hello, {name}!");
    }
}

The code generator for IceRPC generates C# interface IGreeterService from Slice interface Greeter. This C# interface is a template: we implement Greeter by implementing this interface. As you can see above, the greet operation becomes a GreetAsync method with two additional parameters.

Since we always fulfill greet synchronously, the GreetAsync implementation is not marked async. We could write the return statement as:

return new ValueTask<string>($"Hello, {name}!");

However, it's more convenient to omit the type name, especially when this type is complicated.

We mark class Chatbot as partial because the Service attribute instructs the Service Generator (a C# source generator) to implement interface IDispatcher—in other words, make Chatbot an IceRPC service implementation.

Program.cs - the dispatch pipeline and the server logic

The main program starts by creating and configuring a Router:

// Create a simple console logger factory and configure the log level for category IceRpc.
using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
    builder
        .AddSimpleConsole()
        .AddFilter("IceRpc", LogLevel.Information));

Router router = new Router()
    .UseLogger(loggerFactory)
    .UseDeadline()
    .Map(new Chatbot());

This router corresponds to our dispatch pipeline: when we receive a request, we first give it to the Logger middleware, then to the Deadline middleware and finally we route this request based on its path.

The Map call means if the request's path is the default service path for the Chatbot instance, route it to this Chatbot instance. Otherwise, the router returns a response with status code NotFound.

The default service path for the Chatbot instance is /VisitorCenter.Greeter because Chatbot implements a single Slice interface, Greeter. The Map call above is a shortcut for:

.Map("/VisitorCenter.Greeter", new Chatbot());

The main program then creates a Server that directs all incoming requests to router:

using X509Certificate2 serverCertificate = X509CertificateLoader.LoadPkcs12FromFile(
    "certs/server.p12",
    password: null,
    keyStorageFlags: X509KeyStorageFlags.Exportable);

await using var server = new Server(
    dispatcher: router,
    serverAuthenticationOptions: CreateServerAuthenticationOptions(serverCertificate),
    logger: loggerFactory.CreateLogger<Server>());

We don't specify a server address so this server uses the default server address (icerpc://[::0]). This means the new server uses the icerpc protocol and will listen for connections on all network interfaces with the default port for icerpc (4062).

We don't specify a transport either so we use the default multiplexed transport (quic). Setting serverAuthenticationOptions is required with quic.

At this point, the server is created but is not doing anything yet. A client attempting to connect would get a "connection refused" error.

The server starts listening on the next line:

server.Listen();

Listen returns as soon as the server is listening (so almost immediately).

The main program then awaits until it receives a Ctrl+C. After it receives Ctrl+C, it shuts down the server gracefully:

await CancelKeyPressed;
await server.ShutdownAsync();

Program.CancelKeyPressed.cs - small Ctrl+C helper

This file contains a few lines of code that Programs.cs uses to wait for Ctrl+C. It's not related to RPCs.

MySliceServer.csproj - the project file

The project file is straightforward. It contains references to the required IceRpc NuGet packages:

• IceRpc.Slice - the IceRPC + Slice integration package
• IceRpc.Slice.Tools - the package that compiles Greeter.slice into generated/Greeter.IceRpc.cs
• IceRpc.Deadline and IceRpc.Logger - the packages with the two middleware we installed in the dispatch pipeline

Start the server

cd MySliceServer
dotnet run

The server is now listening for new connections from clients.

Shutdown the server

Press Ctrl+C on the server console to shut it down.