Table of Contents

Class Router

Namespace
IceRpc
Assembly
IceRpc.dll

Provides methods for routing incoming requests to dispatchers.

public sealed class Router : IDispatcher
Inheritance
Router
Implements
Inherited Members
Extension Methods

Examples

The following example shows how you would install a middleware, and map a service.

// Create a router that uses the compressor middleware, and add a route for a service using its default service
// path.
Router router = new Router()
    .UseCompressor(CompressionFormat.Brotli)
    .Map<IGreeterService>(new Chatbot());

// Create a server that uses the router as its dispatch pipeline.
await using var server = new Server(router);
server.Listen();

You can easily create your own middleware and add it to the router. The next example shows how you can create a middleware using an InlineDispatcher and add it to the router with Use(Func<IDispatcher, IDispatcher>).

// Create a router that uses a custom middleware defined as an inline dispatcher, and add a route for a service
// using its default service path.
Router router = new Router()
    .Use(next => new InlineDispatcher(async (request, cancellationToken) =>
    {
        Console.WriteLine("before next.DispatchAsync");
        OutgoingResponse response = await next.DispatchAsync(request, cancellationToken);
        Console.WriteLine($"after next.DispatchAsync; the response status code is {response.StatusCode}");
        return response;
    }))
    .Map<IGreeterService>(new Chatbot());

// Create a server that uses the router as its dispatcher.
await using var server = new Server(router);
server.Listen();

Remarks

The Router class allows you to define a dispatch pipeline for customizing how incoming requests are processed. You utilize the Router class for creating routes with various middleware, sub-routers, and dispatchers.

Incoming requests flow through the dispatch pipeline. An incoming request is first processed by the router's middleware and then routed to a target dispatcher based on its path. The target dispatcher returns an outgoing response that goes through the dispatch pipeline in the opposite direction.

The routing algorithm determines how incoming requests are routed to dispatchers. The router first checks if a dispatcher is registered with the request's path, which corresponds to dispatchers registered using Map(string, IDispatcher). If there isn't a dispatcher registered for the request's path, the router looks for dispatchers registered with a matching prefix, which corresponds to dispatchers installed using Mount(string, IDispatcher). When searching for a matching prefix, the router starts with the request path and successively tries chopping segments from the end of the path until either the path is exhausted or a dispatcher matching the prefix is found. Finally, if the router cannot find any dispatcher, it returns an OutgoingResponse with a NotFound status code.

Constructors

Router()

Constructs a top-level router.

public Router()

Router(string)

Constructs a router with an absolute prefix.

public Router(string absolutePrefix)

Parameters

absolutePrefix string

The absolute prefix of the new router. It must start with a /.

Exceptions

FormatException

Thrown if absolutePrefix is not a valid path.

Properties

AbsolutePrefix

Gets the absolute path-prefix of this router. The absolute path of a service added to this Router is: $"{AbsolutePrefix}{path}" where path corresponds to the argument given to Map(string, IDispatcher).

public string AbsolutePrefix { get; }

Property Value

string

The absolute prefix of this router. It is either an empty string or a string with two or more characters starting with a /.

Methods

DispatchAsync(IncomingRequest, CancellationToken)

Dispatches an incoming request and returns the corresponding outgoing response.

public ValueTask<OutgoingResponse> DispatchAsync(IncomingRequest request, CancellationToken cancellationToken = default)

Parameters

request IncomingRequest

The incoming request being dispatched.

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

ValueTask<OutgoingResponse>

The corresponding OutgoingResponse.

Map(string, IDispatcher)

Registers a route with a path. If there is an existing route at the same path, it is replaced.

public Router Map(string path, IDispatcher dispatcher)

Parameters

path string

The path of this route. It must match exactly the path of the request. In particular, it must start with a /.

dispatcher IDispatcher

The target of this route. It is typically a service.

Returns

Router

This router.

Exceptions

FormatException

Thrown if path is not a valid path.

InvalidOperationException

Thrown if DispatchAsync(IncomingRequest, CancellationToken) was already called on this router.

See Also

Mount(string, IDispatcher)

Registers a route with a prefix. If there is an existing route at the same prefix, it is replaced.

public Router Mount(string prefix, IDispatcher dispatcher)

Parameters

prefix string

The prefix of this route. This prefix will be compared with the start of the path of the request.

dispatcher IDispatcher

The target of this route.

Returns

Router

This router.

Exceptions

FormatException

Thrown if prefix is not a valid path.

InvalidOperationException

Thrown if DispatchAsync(IncomingRequest, CancellationToken) was already called on this router.

See Also

ToString()

Returns a string that represents this router.

public override string ToString()

Returns

string

A string that represents this router.

Use(Func<IDispatcher, IDispatcher>)

Installs a middleware in this router. A middleware must be installed before calling DispatchAsync(IncomingRequest, CancellationToken).

public Router Use(Func<IDispatcher, IDispatcher> middleware)

Parameters

middleware Func<IDispatcher, IDispatcher>

The middleware to install.

Returns

Router

This router.

Exceptions

InvalidOperationException

Thrown if DispatchAsync(IncomingRequest, CancellationToken) was already called on this router.

Edit this page