Services

Services is a protocol that provides first-class services support for NATS clients and it's supported by NATS tooling. This services protocol is an agreement between clients and tooling and doesn't require any special functionality from the NATS server or JetStream.

To be able to use Services you need to running the nats-server.

Services Quick Start

Download the latest nats-server for your platform and run it:

$ nats-server

Install NATS.Net from Nuget.

Before we can do anything, we need a Services context:

await using var nats = new NatsConnection();
var svc = new NatsSvcContext(nats);

Let's create our first service:

await using var testService = await svc.AddServiceAsync("test", "1.0.0");

Now that we have a service in our stream, let's see its status using the NATS command line client (make sure you have at least v0.1.1):

$ nats --version
0.1.1

$ nats micro info test
Service Information

      Service: test (Bw6eqhVYs3dbNzZecuuFOV)
  Description:
      Version: 1.0.0

Endpoints:

Statistics for 0 Endpoint(s):

Now we can add endpoints to our service:

await testService.AddEndpointAsync<int>(name: "divide42", handler: async m =>
{
    if (m.Data == 0)
    {
        await m.ReplyErrorAsync(400, "Division by zero");
        return;
    }

    await m.ReplyAsync(42 / m.Data);
});

We can also confirm that our endpoint is registered by using the NATS command line:

$ nats req divide42 2
11:34:03 Sending request on "divide42"
11:34:03 Received with rtt 9.5823ms
21

$ nats micro stats test
╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                        test Service Statistics                                       │
├────────────────────────┬──────────┬──────────┬─────────────┬────────┬─────────────────┬──────────────┤
│ ID                     │ Endpoint │ Requests │ Queue Group │ Errors │ Processing Time │ Average Time │
├────────────────────────┼──────────┼──────────┼─────────────┼────────┼─────────────────┼──────────────┤
│ RH6q9Y6qM8em8m6lG2yN34 │ divide42 │ 1        │ q           │ 0      │ 1ms             │ 1ms          │
├────────────────────────┼──────────┼──────────┼─────────────┼────────┼─────────────────┼──────────────┤
│                        │          │ 1        │             │ 0      │ 1MS             │ 1MS          │
╰────────────────────────┴──────────┴──────────┴─────────────┴────────┴─────────────────┴──────────────╯

Groups

A group is a collection of endpoints. These are optional and can provide a logical association between endpoints as well as an optional common subject prefix for all endpoints.

You can group your endpoints optionally in different queue groups:

var grp1 = await testService.AddGroupAsync("grp1");
await grp1.AddEndpointAsync<int>(name: "ep1", handler: async m =>
{
    // handle message
});

Note

Examples in this page uses primitive types for simplicity. See Serialization section for more information about different serialization options.

Table of Contents

Services

Services Quick Start

Groups

Note